Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Eventos do servidor para o cliente

Aula 10 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. As mensagens que recebe
  2. Eventos de sessão e de conversa
  3. Eventos do buffer de áudio
  4. Eventos de áudio da resposta
  5. Eventos de transcrição
  6. Eventos de texto
  7. Eventos de chamada de função
  8. response.done
  9. O evento de erro
  10. Pontos-chave

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ão
  • session.updated: a configuração foi atualizada com sucesso
  • conversation.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 falar
  • input_audio_buffer.speech_stopped: o VAD detetou o fim da fala
  • input_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 disse
  • response.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ínuo
  • response.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.done marca o fim de uma resposta completa
  • A maioria dos erros reportados através do evento error é recuperável: a ligação permanece aberta