Eventos do servidor para o cliente
Nesta página
As mensagens que recebe
O servidor envia diversos eventos para o manter informado sobre o estado da conversa, entregar o áudio da resposta e reportar erros. Compreender estes eventos é essencial para criar uma aplicação responsiva e fiável.
Eventos de sessão e de conversa
Estes eventos são recebidos quando a ligação é estabelecida e após cada alteração de configuração:
session.created: a sessão foi aberta; o evento contém a configuração da sessãosession.updated: a configuração foi atualizada com sucessoconversation.created: o canal de conversa foi configurado
Eventos do buffer de áudio
Estes eventos informam sobre a atividade de voz detetada pelo VAD (Detetor de Atividade de Voz):
input_audio_buffer.speech_started: o VAD detetou que o utilizador começou a falarinput_audio_buffer.speech_stopped: o VAD detetou o fim da falainput_audio_buffer.committed: o buffer de áudio foi confirmado como uma mensagem
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// O utilizador está a falar: mostrar um indicador visual
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// O utilizador terminou: ocultar o indicador
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// A mensagem de áudio está a ser processada
showProcessingIndicator(true);
break;
}
});
Eventos de áudio da resposta
O áudio da resposta é transmitido em fluxo contínuo através de dois eventos.
response.output_audio.delta
Cada delta contém um fragmento de áudio codificado em base64. Recolha-os e reproduza-os pela ordem correta:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Sinaliza que todo o áudio da resposta foi enviado:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Eventos de transcrição
A API pode transcrever tanto o áudio do utilizador como o áudio da resposta:
conversation.item.input_audio_transcription.completed: uma transcrição do que o utilizador disseresponse.output_audio_transcript.delta: uma transcrição em fluxo contínuo da resposta do agente
case "conversation.item.input_audio_transcription.completed":
console.log("O utilizador disse:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Eventos de texto
Se o agente gerar texto (além do áudio ou em sua substituição), receberá:
response.text.delta: um fragmento de texto transmitido em fluxo contínuo
{
"type": "response.text.delta",
"delta": "A sua encomenda foi"
}
Eventos de chamada de função
Quando o agente decide chamar uma função, são emitidos dois eventos:
response.function_call_arguments.delta: os argumentos da função, transmitidos em fluxo contínuoresponse.function_call_arguments.done: a chamada de função completa com todos os seus argumentos
A Lição 13, sobre chamada de funções por voz, aborda estes eventos em detalhe.
response.done
Este evento marca o fim completo de uma resposta. Contém um resumo da resposta, incluindo estatísticas de utilização:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
O evento de erro
Este evento reporta erros. De acordo com a referência da xAI, a maioria dos erros é recuperável e a ligação WebSocket permanece aberta:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Formato de áudio inválido especificado"
}
}
A sua aplicação deve registar estes erros e, dependendo da sua gravidade, mostrar uma mensagem ao utilizador ou tentar corrigir o problema automaticamente.
Pontos-chave
- O servidor envia eventos para cada etapa: deteção de voz, áudio, transcrição, texto e erros
- O áudio da resposta chega como fragmentos em base64 através de
response.output_audio.delta - As transcrições estão disponíveis tanto para a entrada do utilizador como para a saída do agente
response.donemarca o fim de uma resposta completa- A maioria dos erros reportados através do evento
erroré recuperável: a ligação permanece aberta