Události ze serveru na klienta
Na této stránce
Zprávy, které přijímáš
Server ti posílá mnoho událostí, aby tě informoval o stavu konverzace, doručoval zvukovou odpověď a hlásil chyby. Porozumění těmto událostem je zásadní pro vytvoření responzivní a spolehlivé aplikace.
Události relace a konverzace
Tyto události přicházejí při navázání spojení a po každé změně konfigurace:
session.created: relace je otevřena; událost obsahuje konfiguraci relacesession.updated: konfigurace byla úspěšně aktualizovánaconversation.created: kanál konverzace je nastaven
Události zvukové vyrovnávací paměti
Tyto události tě informují o hlasové aktivitě detekované systémem VAD:
input_audio_buffer.speech_started: VAD detekoval, že uživatel začal mluvitinput_audio_buffer.speech_stopped: VAD detekoval konec řečiinput_audio_buffer.committed: zvuková vyrovnávací paměť byla potvrzena jako zpráva
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// Uživatel mluví: zobraz vizuální indikátor
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// Uživatel skončil: skryj indikátor
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Zvuková zpráva se zpracovává
showProcessingIndicator(true);
break;
}
});
Události odpovědního zvuku
Zvuk odpovědi proudí prostřednictvím dvou událostí.
response.output_audio.delta
Každá delta obsahuje část zvuku kódovanou v base64. Shromáždi je a přehraj v pořadí:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Signalizuje, že byl odeslán veškerý zvuk odpovědi:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Události přepisu
API dokáže přepisovat jak uživatelův zvuk, tak zvuk odpovědi:
conversation.item.input_audio_transcription.completed: přepis toho, co uživatel řeklresponse.output_audio_transcript.delta: streamovaný přepis odpovědi agenta
case "conversation.item.input_audio_transcription.completed":
console.log("Uživatel řekl:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Textové události
Pokud agent generuje text (navíc k zvuku nebo místo něj), obdržíš:
response.text.delta: streamovaný fragment textu
{
"type": "response.text.delta",
"delta": "Vaše objednávka byla"
}
Události volání funkcí
Když se agent rozhodne zavolat funkci, jsou vydány dvě události:
response.function_call_arguments.delta: argumenty funkce, streamovanéresponse.function_call_arguments.done: úplné volání funkce se všemi jejími argumenty
Lekce 13 o volání hlasových funkcí tyto události podrobně probírá.
response.done
Tato událost označuje úplný konec odpovědi. Obsahuje shrnutí odpovědi, včetně statistik využití:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Událost chyby
Tato událost hlásí chyby. Podle reference xAI je většina chyb obnovitelná a spojení WebSocket zůstává otevřené:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Zadán neplatný formát zvuku"
}
}
Tvoje aplikace by měla tyto chyby logovat a v závislosti na jejich závažnosti buď uživateli zobrazit zprávu, nebo se pokusit problém automaticky opravit.
Klíčové poznatky
- Server posílá události pro každý krok: detekci hlasu, zvuk, přepis, text a chyby
- Zvuk odpovědi přichází jako části v base64 prostřednictvím
response.output_audio.delta - Přepisy jsou dostupné jak pro vstup uživatele, tak pro výstup agenta
response.doneoznačuje konec úplné odpovědi- Většina chyb hlášených prostřednictvím události
errorje obnovitelná: spojení zůstává otevřené