Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Die Ereignisse session.created und session.updated

Lektion 4 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Server-Ereignisse für Sitzungen
  2. session.created
  3. session.updated
  4. conversation.created
  5. Der vollständige Startablauf
  6. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf der xAI-Seite Speech to Speech und der Voice-API-Referenz. Die Referenz erläutert nicht den Inhalt des session-Objekts in diesen Ereignissen; die zu speichernde ID ist die der Konversation, conversation.id, auf die die Wiederaufnahme der Sitzung (session resumption) angewiesen ist. Quellen: Speech to Speech · Voice API.

Server-Ereignisse für Sitzungen

Wenn Sie mit der Voice-Agent-API arbeiten, informiert Sie der Server über den Zustand der Sitzung mittels JSON-Ereignissen. Die ersten, die Sie empfangen, sind session.created beim Öffnen der Verbindung und conversation.created. Anschließend folgt session.updated nach jeder von Ihnen gesendeten Konfiguration.

session.created

Der Server sendet dieses Ereignis automatisch, sobald die WebSocket-Verbindung geöffnet wird. Laut der Referenz enthält es die Sitzungskonfiguration, deren Felder jedoch nicht detailliert beschrieben sind. Anstatt Standardwerte anzunehmen, sollten Sie das Ereignis einmal protokollieren, um zu sehen, was der Server zurückgibt, und erst danach Ihre eigene Konfiguration senden.

Vorgehensweise beim Eintreffen von session.created

Ihre Anwendung sollte:

  1. Das Ereignis protokollieren, zur Fehlerbehebung
  2. Sofort Ihre session.update mit der gewünschten Konfiguration senden
  3. Den Audio-Puffer leeren, den Sie während des Wartens auf die Verbindung aufgefüllt haben

Der dritte Punkt ergibt sich aus dem Rat von xAI zur Verringerung der wahrgenommenen Latenz: Beginnen Sie mit der Mikrofon-Aufnahme, sobald der Bildschirm geöffnet wird, ohne auf die Verbindung zu warten. Speichern Sie die Samples im Arbeitsspeicher und senden Sie sie, sobald die Verbindung bereit ist und die Konfiguration gesendet wurde.

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

  switch (event.type) {
    case "session.created":
      console.log("Sitzung erstellt:", event.session);
      // Senden Sie die Konfiguration
      ws.send(JSON.stringify({
        type: "session.update",
        session: {
          instructions: "Sie sind eine Sprachassistentin.",
          voice: "rex",
          turn_detection: { type: "server_vad" }
        }
      }));
      // Senden Sie dann das Audio, das während des Wartens auf die Verbindung aufgezeichnet wurde
      flushMicBuffer(ws);
      break;
  }
});

session.updated

Dieses Ereignis bestätigt Ihre session.update: Die Sitzung ist konfiguriert. Für einige Einstellungen gibt die Dokumentation an, dass der angewandte Wert hier zurückgesendet wird, wie bei der Tabelle zur Aussprachenersetzung (replace). Eine ungültige Konfiguration wird hingegen mit einem error-Ereignis abgelehnt, das das Problem beschreibt; die Sitzung bleibt offen und behält ihre vorherige Konfiguration.

Konfiguration prüfen

Vergleichen Sie die zurückgegebenen Werte mit denen, die Sie gesendet haben: So erkennen Sie Einstellungen, die ignoriert wurden.

case "session.updated":
  const s = event.session;
  console.log("Konfigurierte Stimme:", s.voice);
  console.log("Anzahl der Tools:", s.tools?.length ?? 0);
  break;

case "error":
  console.error("Konfiguration abgelehnt:", event);
  break;

conversation.created

Der Server sendet ebenfalls ein conversation.created-Ereignis, das die Konversations-ID enthält:

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

Speichern Sie diese ID: Sie ist die Voraussetzung für die Wiederaufnahme der Sitzung. Standardmäßig verliert eine Verbindung die Konversationsverlaufsgeschichte, wenn die WebSocket-Verbindung schließt. Wenn Sie "resumption": {"enabled": true} in session.update senden, puffert der Server jede Runde. Wenn Sie sich erneut verbinden, öffnen Sie die WebSocket-Verbindung mit ?conversation_id=<id> und aktivieren Sie die Wiederaufnahme erneut: Die vorherigen Runden werden vor Ihrer ersten neuen Runde abgespielt. Die Verlaufsgeschichte wird nach 30 Minuten Inaktivität gelöscht.

Der vollständige Startablauf

Zusammengefasst ist dies die Reihenfolge der Ereignisse, wenn eine Sprachsession startet, wie in der Referenz beschrieben:

  1. Die WebSocket-Verbindung wird geöffnet
  2. Sie erhalten session.created (Server → Client)
  3. Sie erhalten conversation.created (Server → Client)
  4. Sie senden session.update (Client → Server)
  5. Sie erhalten session.updated (Server → Client)

Kernaussagen

  • session.created wird beim Öffnen der Verbindung empfangen und enthält die Sitzungskonfiguration, deren Felder in der Referenz nicht detailliert beschrieben sind
  • session.updated bestätigt Ihre Konfiguration; eine ungültige Konfiguration führt zu einem error-Ereignis
  • Erfassen Sie das Mikrofon vor der Verbindung und leeren Sie den Puffer, sobald er bereit ist
  • conversation.created enthält die conversation.id, die Sie für die Wiederaufnahme der Sitzung speichern
  • Die Wiederaufnahme erfordert resumption.enabled bei jeder Verbindung, und die Verlaufsgeschichte verfällt nach 30 Minuten Inaktivität