Przejdź do głównej treści
Polski— Wybierz język
Menu

Zdarzenia session.created i session.updated

Lekcja 4 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Zdarzenia sesji serwerowej
  2. session.created
  3. session.updated
  4. conversation.created
  5. Pełna sekwencja uruchamiania
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Speech to Speech oraz dokumentacji Voice API. Dokumentacja nie szczegółowo opisuje zawartości obiektu session w tych zdarzeniach; identyfikatorem, który musisz zachować, jest ID konwersacji, conversation.id, od którego zależy wznawianie sesji. Źródła: Speech to Speech · Voice API.

Zdarzenia sesji serwerowej

Pracując z Voice Agent API, serwer na bieżąco informuje Cię o stanie sesji za pomocą zdarzeń JSON. Pierwsze otrzymywane zdarzenia to session.created (gdy połączenie zostanie otwarte) oraz conversation.created. Następnie pojawia się session.updated po każdym wysłanym przez Ciebie konfigurowaniu.

session.created

Serwer wysyła to zdarzenie automatycznie natychmiast po otwarciu połączenia WebSocket. Zgodnie z dokumentacją zawiera ono konfigurację sesji, ale pola nie są szczegółowo opisane. Zamiast zakładać wartości domyślne, zaloguj to zdarzenie raz, aby zobaczyć, co zwraca serwer, a następnie wyślij własną konfigurację.

Co zrobić po otrzymaniu session.created

Twoja aplikacja powinna:

  1. Zalogować zdarzenie w celach debugowania.
  2. Natychmiast wysłać session.update z żądaną konfiguracją.
  3. Wyczyścić bufor audio, który wypełniłeś podczas oczekiwania na połączenie.

Trzeci punkt wynika z zaleceń xAI dotyczących redukcji postrzeganego opóźnienia: zacznij przechwytywać dźwięk z mikrofonu zaraz po otwarciu ekranu, nie czekając na połączenie, przechowuj próbki w pamięci, a następnie wyślij je natychmiast, gdy połączenie będzie gotowe i konfiguracja zostanie wysłana.

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

To zdarzenie potwierdza Twoje session.update: sesja jest skonfigurowana. W przypadku niektórych ustawień dokumentacja wskazuje, że zastosowana wartość jest tutaj odsyłana z powrotem, jak ma to miejsce w tabeli zastępowania wymowy (replace). Nieprawidłowa konfiguracja zostaje natomiast odrzucona zdarzeniem error, które opisuje problem; sesja pozostaje otwarta i zachowuje swoją poprzednią konfigurację.

Sprawdź konfigurację

Porównaj zwrócone wartości z tymi, które wysłałeś: w ten sposób wychwycisz ustawienie, które zostało zignorowane.

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

Serwer wysyła również zdarzenie conversation.created, które niesie ze sobą identyfikator konwersacji:

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

Zachowaj ten identyfikator: to właśnie on umożliwia wznawianie sesji. Domyślnie połączenie traci historię konwersacji po zamknięciu WebSocketu. Jeśli wyślesz "resumption": {"enabled": true} w ramach session.update, serwer przechowuje w pamięci podręcznej każdą turę rozmowy. Gdy ponownie się połączysz, otwórz WebSocket z parametrem ?conversation_id=<id> i ponownie włącz wznawianie: poprzednie tury zostaną odtworzone przed Twoją pierwszą nową turą. Historia jest usuwana po 30 minutach bezczynności.

Pełna sekwencja uruchamiania

Podsumowując, oto kolejność zdarzeń podczas uruchamiania sesji głosowej, zgodnie z opisem w dokumentacji:

  1. Otwarcie połączenia WebSocket
  2. Otrzymanie session.created (serwer → klient)
  3. Otrzymanie conversation.created (serwer → klient)
  4. Wysłanie session.update (klient → serwer)
  5. Otrzymanie session.updated (serwer → klient)

Kluczowe wnioski

  • session.created pojawia się po otwarciu połączenia i zawiera konfigurację sesji, której pola nie są szczegółowo opisane w dokumentacji
  • session.updated potwierdza Twoją konfigurację; nieprawidłowa konfiguracja zwraca zdarzenie error
  • Przechwytuj dźwięk z mikrofonu przed nawiązaniem połączenia i wyczyść bufor natychmiast, gdy będzie gotowy
  • conversation.created niesie conversation.id, które zachowujesz do wznawiania sesji
  • Wznawianie wymaga ustawienia resumption.enabled przy każdym połączeniu, a historia wygasa po 30 minutach bezczynności