Server-naar-client events
Op deze pagina
De berichten die u ontvangt
De server verzendt talrijke events om u op de hoogte te houden van de status van het gesprek, de respons-audio te leveren en fouten te rapporteren. Inzicht in deze events is essentieel voor het bouwen van een responsieve en betrouwbare applicatie.
Sessie- en conversatie-events
Deze events arriveren bij het tot stand komen van de verbinding en na elke configuratiewijziging:
session.created: de sessie is geopend; het event bevat de sessieconfiguratiesession.updated: de configuratie is succesvol bijgewerktconversation.created: het conversatiekanaal is ingesteld
Audiobuffer-events
Deze events informeren u over de spraakactiviteit die VAD detecteert:
input_audio_buffer.speech_started: VAD detecteert dat de gebruiker is begonnen met sprekeninput_audio_buffer.speech_stopped: VAD detecteert het einde van de spraakinput_audio_buffer.committed: de audiobuffer is als bericht vastgelegd
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// De gebruiker spreekt: toon een visuele indicator
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// De gebruiker is klaar: verberg de indicator
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Het audiobericht wordt verwerkt
showProcessingIndicator(true);
break;
}
});
Respons-audio-events
De respons-audio wordt gestreamd via twee events.
response.output_audio.delta
Elke delta bevat een base64-gecodeerd chunk audio. Verzamel deze en speel ze in de juiste volgorde af:
{
"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
Geeft aan dat alle respons-audio is verzonden:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Transcriptie-events
De API kan zowel de audio van de gebruiker als de respons-audio transcriberen:
conversation.item.input_audio_transcription.completed: een transcriptie van wat de gebruiker heeft gezegdresponse.output_audio_transcript.delta: een gestreamde transcriptie van het antwoord van de agent
case "conversation.item.input_audio_transcription.completed":
console.log("User said:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Tekst-events
Als de agent tekst genereert (naast of in plaats van audio), ontvangt u:
response.text.delta: een gestreamd tekstfragment
{
"type": "response.text.delta",
"delta": "Your order has been"
}
Function calling-events
Wanneer de agent besluit een functie aan te roepen, worden twee events gegenereerd:
response.function_call_arguments.delta: de functieargumenten, gestreamdresponse.function_call_arguments.done: de volledige functieaanroep met alle argumenten
Les 13, over voice function calling, behandelt deze events in detail.
response.done
Dit event markeert het volledige einde van een respons. Het bevat een samenvatting van de respons, inclusief gebruiksstatistieken:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Het error-event
Dit event rapporteert fouten. Volgens de xAI-referentie zijn de meeste fouten herstelbaar en blijft de WebSocket-verbinding open:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Invalid audio format specified"
}
}
Uw applicatie moet deze fouten loggen en, afhankelijk van de ernst, de gebruiker een bericht tonen of proberen het probleem automatisch op te lossen.
Belangrijkste punten
- De server verzendt events voor elke stap: spraakdetectie, audio, transcriptie, tekst en fouten
- Respons-audio arriveert als base64-chunks via
response.output_audio.delta - Transcripties zijn beschikbaar voor zowel gebruikersinvoer als agent-uitvoer
response.donemarkeert het einde van een volledige respons- De meeste fouten die via het
error-event worden gerapporteerd, zijn herstelbaar: de verbinding blijft open