Události session.created a session.updated
Na této stránce
Aktualizováno 3. listopadu 2026 na základě stránky xAI Speech to Speech a reference k Voice API. Reference nepopisuje podrobně obsah objektu
sessionv těchto událostech; klíčové ID, které si musíš ponechat, je ID konverzace,conversation.id, na němž závisí obnovení relace. Zdroje: Speech to Speech · Voice API.
Události relace na straně serveru
Při práci s Voice Agent API tě server průběžně informuje o stavu relace prostřednictvím událostí ve formátu JSON. Prvními událostmi, které obdržíš, jsou session.created (při otevření připojení) a conversation.created. Následuje událost session.updated, která přichází po každé konfiguraci, kterou odešleš.
session.created
Server tuto událost odešle automaticky ihned po otevření WebSocket připojení. Podle reference obsahuje konfiguraci relace, ale její pole nejsou podrobně specifikována. Místo abys předpokládal výchozí hodnoty, jednou si tuto událost zaloguj, abys viděl, co server vrací, a teprve poté odešli svou vlastní konfiguraci.
Co dělat při příchodu události session.created
Tvoje aplikace by měla:
- Zalogovat událost pro účely ladění
- Okamžitě odeslat příkaz
session.updates požadovanou konfigurací - Vyprázdnit audio buffer, který jsi naplnil během čekání na připojení
Třetí bod vychází z doporučení xAI pro snížení vnímané latence: začni zachytávat mikrofon hned po otevření obrazovky, nečekej na připojení, uchovávej vzorky v paměti a odešli je, jakmile je připojení připraveno a konfigurace odeslána.
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "session.created":
console.log("Session created:", event.session);
// Odešli konfiguraci
ws.send(JSON.stringify({
type: "session.update",
session: {
instructions: "You are a voice assistant.",
voice: "rex",
turn_detection: { type: "server_vad" }
}
}));
// Poté odešli audio zachycené během čekání na připojení
flushMicBuffer(ws);
break;
}
});
session.updated
Tato událost potvrzuje tvůj příkaz session.update: relace je nakonfigurována. U některých nastavení dokumentace uvádí, že zde je vrácena skutečně aplikovaná hodnota, jako je tomu u tabulky náhrad výslovnosti (replace). Neplatná konfigurace je naopak zamítnuta událostí error, která popisuje problém; relace zůstane otevřená a zachová si svou předchozí konfiguraci.
Kontrola konfigurace
Porovnej vrácené hodnoty s těmi, které jsi odeslal: právě tak odhalíš nastavení, které bylo ignorováno.
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
Server také odesílá událost conversation.created, která nese ID konverzace:
{
"type": "conversation.created",
"conversation": {
"id": "conv_xyz789"
}
}
Toto ID si uchovej: právě ono umožňuje obnovení relace. Ve výchozím nastavení ztrácí připojení historii konverzace při uzavření WebSocketu. Pokud do session.update odešleš "resumption": {"enabled": true}, server cachuje každý obrat. Při opětovném připojení znovu otevři WebSocket s parametrem ?conversation_id=<id> a znovu povol obnovení: předchozí obraty se přehrají před tvým prvním novým obratem. Historie se zahodí po 30 minutách nečinnosti.
Kompletní sekvence spuštění
Shrňme si pořadí událostí při startu hlasové relace tak, jak jej popisuje reference:
- Otevře se WebSocket
- Obdržíš
session.created(server → klient) - Obdržíš
conversation.created(server → klient) - Odešleš
session.update(klient → server) - Obdržíš
session.updated(server → klient)
Klíčové poznatky
- Událost
session.createdpřichází při otevření připojení a obsahuje konfiguraci relace, jejíž pole reference podrobně nepopisuje - Událost
session.updatedpotvrzuje tvou konfiguraci; neplatná konfigurace vrací událosterror - Zachytávej mikrofon před navázáním připojení a vyprázdni buffer, jakmile je připraven
- Událost
conversation.createdneseconversation.id, které si uchováš pro obnovení relace - Obnovení vyžaduje
resumption.enabledpři každém připojení a historie expiruje po 30 minutách nečinnosti