Händelserna session.created och session.updated
På denna sida
Uppdaterat den 3 november 2026, baserat på xAI:s sida Speech to Speech och referensen för Voice API. Referensen specificerar inte innehållet i
session-objektet i dessa händelser; det ID du måste behålla är konversationens,conversation.id, vilket återupptagning av sessionen förlitar sig på. Källor: Speech to Speech · Voice API.
Serverns sessionshändelser
När du arbetar med Voice Agent API håller servern dig informerad om sessionens tillstånd via JSON-händelser. De första du får är session.created, när anslutningen öppnas, och conversation.created. Därefter följer session.updated efter varje konfiguration du skickar.
session.created
Servern skickar denna händelse automatiskt så snart WebSocket-anslutningen öppnas. Enligt referensen innehåller den sessionskonfigurationen, men fälten specificeras inte i detalj. Istället för att anta standardvärden bör du logga händelsen en gång för att se vad servern returnerar, och sedan skicka din egen konfiguration.
Vad du ska göra när session.created anländer
Din applikation bör:
- Logga händelsen, för felsökning
- Omedelbart skicka din
session.updatemed den konfiguration du önskar - Tömma ljudbufferten du fyllde medan du väntade på anslutningen
Den tredje punkten kommer från xAI:s råd för att minska den upplevda latensen: börja fånga ljud från mikrofonen så snart skärmen öppnas, utan att vänta på anslutningen, behåll sampel i minnet och skicka dem sedan så snart anslutningen är redo och konfigurationen har skickats.
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
Denna händelse bekräftar din session.update: sessionen är konfigurerad. För vissa inställningar anger dokumentationen att det tillämpade värdet skickas tillbaka här, precis som med tabellen för uttalsersättning (replace). En ogiltig konfiguration å andra sidas avvisas med en error-händelse som beskriver problemet; sessionen förblir öppen och behåller sin tidigare konfiguration.
Kontrollera konfigurationen
Jämför de returnerade värdena med de du skickade: det är så du fångar upp en inställning som ignorerades.
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
Servern skickar också en conversation.created-händelse, som bär på konversations-ID:t:
{
"type": "conversation.created",
"conversation": {
"id": "conv_xyz789"
}
}
Behåll detta ID: det är vad som möjliggör återupptagning av sessionen. Som standard förlorar en anslutning konversationshistoriken när WebSocket stängs. Om du skickar "resumption": {"enabled": true} i session.update, cachelagrar servern varje tur. När du återansluter, öppna WebSocket igen med ?conversation_id=<id> och aktivera återupptagning igen: de tidigare turerna spelas upp innan din första nya tur. Historiken raderas efter 30 minuters inaktivitet.
Den fullständiga startsekvensen
Sammanfattningsvis är detta ordningen på händelser när en röstsession startar, enligt hur referensen beskriver det:
- WebSocket öppnas
- Du får
session.created(server → klient) - Du får
conversation.created(server → klient) - Du skickar
session.update(klient → server) - Du får
session.updated(server → klient)
Viktiga punkter
session.createdanländer när anslutningen öppnas och innehåller sessionskonfigurationen, vars fält referensen inte specificerar i detaljsession.updatedbekräftar din konfiguration; en ogiltig konfiguration returnerar enerror-händelse- Fånga ljud från mikrofonen innan anslutningen och töm bufferten så snart den är redo
conversation.createdbär påconversation.id, vilket du behåller för att återuppta sessionen- Återupptagning kräver
resumption.enabledvid varje anslutning, och historiken löper ut efter 30 minuters inaktivitet