Zdarzenia serwer-klient
Na tej stronie
Otrzymywane wiadomości
Serwer wysyła wiele zdarzeń, aby informować Cię o stanie konwersacji, dostarczać odpowiedź audio i zgłaszać błędy. Zrozumienie tych zdarzeń jest kluczowe dla budowania responsywnej i niezawodnej aplikacji.
Zdarzenia sesji i konwersacji
Te zdarzenia pojawiają się przy nawiązywaniu połączenia oraz po każdej zmianie konfiguracji:
session.created: sesja została otwarta; zdarzenie zawiera konfigurację sesjisession.updated: konfiguracja została pomyślnie zaktualizowanaconversation.created: kanał konwersacji został skonfigurowany
Zdarzenia bufora audio
Te zdarzenia informują o aktywności głosowej wykrytej przez VAD (wykrywanie mowy):
input_audio_buffer.speech_started: VAD wykryło, że użytkownik zaczął mówićinput_audio_buffer.speech_stopped: VAD wykryło koniec wypowiedziinput_audio_buffer.committed: bufor audio został zatwierdzony jako wiadomość
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// Użytkownik mówi: pokaż wskaźnik wizualny
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// Użytkownik skończył: ukryj wskaźnik
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Wiadomość audio jest przetwarzana
showProcessingIndicator(true);
break;
}
});
Zdarzenia odpowiedzi audio
Strumień audio odpowiedzi jest przesyłany za pomocą dwóch zdarzeń.
response.output_audio.delta
Każdy delta zawiera fragment audio zakodowany w formacie base64. Zbierz je i odtwórz w odpowiedniej kolejności:
{
"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
Sygnalizuje, że całe audio odpowiedzi zostało wysłane:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Zdarzenia transkrypcji
API potrafi transkrybować zarówno audio użytkownika, jak i audio odpowiedzi:
conversation.item.input_audio_transcription.completed: transkrypcja tego, co powiedział użytkownikresponse.output_audio_transcript.delta: strumieniowa transkrypcja odpowiedzi agenta
case "conversation.item.input_audio_transcription.completed":
console.log("Użytkownik powiedział:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Zdarzenia tekstowe
Jeśli agent generuje tekst (dodatkowo do audio lub zamiast niego), otrzymasz:
response.text.delta: strumieniowy fragment tekstu
{
"type": "response.text.delta",
"delta": "Twoje zamówienie zostało"
}
Zdarzenia wywoływania funkcji
Gdy agent zdecyduje się wywołać funkcję, emitowane są dwa zdarzenia:
response.function_call_arguments.delta: argumenty funkcji, przesyłane strumienioworesponse.function_call_arguments.done: kompletne wywołanie funkcji ze wszystkimi jej argumentami
Lekcja 13, dotycząca wywoływania funkcji głosowych, szczegółowo omawia te zdarzenia.
response.done
To zdarzenie oznacza całkowite zakończenie odpowiedzi. Zawiera podsumowanie odpowiedzi, w tym statystyki użycia:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Zdarzenie błędu
To zdarzenie zgłasza błędy. Zgodnie z dokumentacją referencyjną xAI, większość błędów można naprawić, a połączenie WebSocket pozostaje otwarte:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Określono nieprawidłowy format audio"
}
}
Twoja aplikacja powinna logować te błędy i, w zależności od ich wagi, wyświetlić użytkownikowi komunikat lub spróbować automatycznie naprawić problem.
Kluczowe wnioski
- Serwer wysyła zdarzenia dla każdego etapu: wykrywanie głosu, audio, transkrypcja, tekst i błędy
- Audio odpowiedzi przychodzi jako fragmenty base64 przez
response.output_audio.delta - Transkrypcje są dostępne zarówno dla danych wejściowych użytkownika, jak i wyjściowych agenta
response.doneoznacza koniec kompletnej odpowiedzi- Większość błędów zgłaszanych przez zdarzenie
errormożna naprawić: połączenie pozostaje otwarte