Zdarzenia session.created i session.updated
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Speech to Speech oraz dokumentacji Voice API. Dokumentacja nie szczegółowo opisuje zawartości obiektu
sessionw 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:
- Zalogować zdarzenie w celach debugowania.
- Natychmiast wysłać
session.updatez żądaną konfiguracją. - 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:
- Otwarcie połączenia WebSocket
- Otrzymanie
session.created(serwer → klient) - Otrzymanie
conversation.created(serwer → klient) - Wysłanie
session.update(klient → serwer) - Otrzymanie
session.updated(serwer → klient)
Kluczowe wnioski
session.createdpojawia się po otwarciu połączenia i zawiera konfigurację sesji, której pola nie są szczegółowo opisane w dokumentacjisession.updatedpotwierdza Twoją konfigurację; nieprawidłowa konfiguracja zwraca zdarzenieerror- Przechwytuj dźwięk z mikrofonu przed nawiązaniem połączenia i wyczyść bufor natychmiast, gdy będzie gotowy
conversation.createdniesieconversation.id, które zachowujesz do wznawiania sesji- Wznawianie wymaga ustawienia
resumption.enabledprzy każdym połączeniu, a historia wygasa po 30 minutach bezczynności