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

Os eventos session.created e session.updated

Aula 4 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Eventos de sessão do servidor
  2. session.created
  3. session.updated
  4. conversation.created
  5. A sequência completa de arranque
  6. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na página Speech to Speech da xAI e na referência da Voice API. A referência não detalha o conteúdo do objeto session nestes eventos; o ID a reter é o da conversa, conversation.id, do qual depende a retomada da sessão. Fontes: Speech to Speech · Voice API.

Eventos de sessão do servidor

Ao trabalhar com a Voice Agent API, o servidor mantém-no informado sobre o estado da sessão através de eventos JSON. Os primeiros que recebe são session.created, quando a ligação é estabelecida, e conversation.created. De seguida, surge session.updated, após cada configuração que enviar.

session.created

O servidor envia este evento automaticamente assim que a ligação WebSocket é aberta. Segundo a referência, contém a configuração da sessão, mas os seus campos não são detalhados. Em vez de assumir valores predefinidos, registe o evento uma vez para ver o que o servidor devolve e, em seguida, envie a sua própria configuração.

O que fazer quando chegar session.created

A sua aplicação deve:

  1. Registar o evento, para fins de depuração
  2. Enviar imediatamente o seu session.update com a configuração desejada
  3. Esvaziar o buffer de áudio que preencheu enquanto aguardava a ligação

O terceiro ponto deriva do conselho da xAI para reduzir a latência percecionada: comece a capturar o microfone assim que o ecrã abrir, sem aguardar a ligação, mantenha as amostras na memória e envie-as assim que a ligação estiver pronta e a configuração tiver sido enviada.

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "session.created":
      console.log("Session created:", event.session);
      // Send the configuration
      ws.send(JSON.stringify({
        type: "session.update",
        session: {
          instructions: "You are a voice assistant.",
          voice: "rex",
          turn_detection: { type: "server_vad" }
        }
      }));
      // Then send the audio captured while waiting for the connection
      flushMicBuffer(ws);
      break;
  }
});

session.updated

Este evento confirma o seu session.update: a sessão está configurada. Para algumas definições, a documentação indica que o valor aplicado é devolvido aqui, como acontece com a tabela de substituição de pronúncia (replace). Por outro lado, uma configuração inválida é rejeitada com um evento error que descreve o problema; a sessão permanece aberta e mantém a sua configuração anterior.

Verificar a configuração

Compare os valores devolvidos com os que enviou: é assim que deteta uma definição que foi ignorada.

case "session.updated":
  const s = event.session;
  console.log("Configured voice:", s.voice);
  console.log("Number of tools:", s.tools?.length ?? 0);
  break;

case "error":
  console.error("Configuration rejected:", event);
  break;

conversation.created

O servidor envia também um evento conversation.created, que transporta o ID da conversa:

{
  "type": "conversation.created",
  "conversation": {
    "id": "conv_xyz789"
  }
}

Guarde este ID: é ele que torna possível a retomada da sessão. Por predefinição, uma ligação perde o histórico da conversa quando o WebSocket fecha. Se enviar "resumption": {"enabled": true} em session.update, o servidor coloca em cache cada turno. Quando se voltar a ligar, reabra o WebSocket com ?conversation_id=<id> e ative novamente a retomada: os turnos anteriores serão reproduzidos antes do seu primeiro novo turno. O histórico é eliminado após 30 minutos de inatividade.

A sequência completa de arranque

Em resumo, eis a ordem dos eventos quando uma sessão de voz inicia, conforme descrito na referência:

  1. O WebSocket abre
  2. Recebe session.created (servidor → cliente)
  3. Recebe conversation.created (servidor → cliente)
  4. Envia session.update (cliente → servidor)
  5. Recebe session.updated (servidor → cliente)

Pontos-chave

  • session.created chega quando a ligação é aberta e contém a configuração da sessão, cujos campos a referência não detalha
  • session.updated confirma a sua configuração; uma configuração inválida devolve um evento error
  • Capture o áudio do microfone antes da ligação e esvazie o buffer assim que esta estiver pronta
  • conversation.created transporta o conversation.id, que deve guardar para a retomada da sessão
  • A retomada exige resumption.enabled em cada ligação e o histórico expira após 30 minutos de inatividade