Os eventos session.created e session.updated
Nesta página
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
sessionnestes 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:
- Registar o evento, para fins de depuração
- Enviar imediatamente o seu
session.updatecom a configuração desejada - 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:
- O WebSocket abre
- Recebe
session.created(servidor → cliente) - Recebe
conversation.created(servidor → cliente) - Envia
session.update(cliente → servidor) - Recebe
session.updated(servidor → cliente)
Pontos-chave
session.createdchega quando a ligação é aberta e contém a configuração da sessão, cujos campos a referência não detalhasession.updatedconfirma a sua configuração; uma configuração inválida devolve um eventoerror- Capture o áudio do microfone antes da ligação e esvazie o buffer assim que esta estiver pronta
conversation.createdtransporta oconversation.id, que deve guardar para a retomada da sessão- A retomada exige
resumption.enabledem cada ligação e o histórico expira após 30 minutos de inatividade