Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Události session.created a session.updated

Lekce 4 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Události relace na straně serveru
  2. session.created
  3. session.updated
  4. conversation.created
  5. Kompletní sekvence spuštění
  6. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě stránky xAI Speech to Speech a reference k Voice API. Reference nepopisuje podrobně obsah objektu session v 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:

  1. Zalogovat událost pro účely ladění
  2. Okamžitě odeslat příkaz session.update s požadovanou konfigurací
  3. 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:

  1. Otevře se WebSocket
  2. Obdržíš session.created (server → klient)
  3. Obdržíš conversation.created (server → klient)
  4. Odešleš session.update (klient → server)
  5. Obdržíš session.updated (server → klient)

Klíčové poznatky

  • Událost session.created přichází při otevření připojení a obsahuje konfiguraci relace, jejíž pole reference podrobně nepopisuje
  • Událost session.updated potvrzuje tvou konfiguraci; neplatná konfigurace vrací událost error
  • Zachytávej mikrofon před navázáním připojení a vyprázdni buffer, jakmile je připraven
  • Událost conversation.created nese conversation.id, které si uchováš pro obnovení relace
  • Obnovení vyžaduje resumption.enabled při každém připojení a historie expiruje po 30 minutách nečinnosti