Eventi server-to-client
In questa pagina
I messaggi che ricevi
Il server invia numerosi eventi per tenerti aggiornato sullo stato della conversazione, fornire l’audio di risposta e segnalare eventuali errori. Comprendere questi eventi è fondamentale per costruire un’applicazione reattiva e affidabile.
Eventi di sessione e conversazione
Questi eventi arrivano all’avvio della connessione e dopo ogni modifica alla configurazione:
session.created: la sessione è aperta; l’evento contiene la configurazione della sessionesession.updated: la configurazione è stata aggiornata con successoconversation.created: il canale di conversazione è stato impostato
Eventi del buffer audio
Questi eventi ti informano sull’attività vocale rilevata dal VAD (Voice Activity Detection):
input_audio_buffer.speech_started: il VAD rileva che l’utente ha iniziato a parlareinput_audio_buffer.speech_stopped: il VAD rileva la fine del discorsoinput_audio_buffer.committed: il buffer audio è stato confermato come messaggio
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// L'utente sta parlando: mostra un indicatore visivo
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// L'utente ha finito: nascondi l'indicatore
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Il messaggio audio è in elaborazione
showProcessingIndicator(true);
break;
}
});
Eventi audio di risposta
L’audio di risposta viene trasmesso in streaming tramite due eventi.
response.output_audio.delta
Ogni delta contiene un frammento di audio codificato in base64. Raccoglili e riproducili in ordine:
{
"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
Segnala che tutto l’audio di risposta è stato inviato:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Eventi di trascrizione
L’API può trascrivere sia l’audio dell’utente che l’audio di risposta:
conversation.item.input_audio_transcription.completed: una trascrizione di ciò che ha detto l’utenteresponse.output_audio_transcript.delta: una trascrizione in streaming della risposta dell’agente
case "conversation.item.input_audio_transcription.completed":
console.log("L'utente ha detto:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Eventi di testo
Se l’agente genera testo (in aggiunta o al posto dell’audio), ricevi:
response.text.delta: un frammento di testo in streaming
{
"type": "response.text.delta",
"delta": "Il tuo ordine è stato"
}
Eventi di chiamata di funzione
Quando l’agente decide di chiamare una funzione, vengono emessi due eventi:
response.function_call_arguments.delta: gli argomenti della funzione, in streamingresponse.function_call_arguments.done: la chiamata di funzione completa con tutti i suoi argomenti
La Lezione 13, sulla chiamata di funzioni vocali, tratta questi eventi nel dettaglio.
response.done
Questo evento segna la fine completa di una risposta. Contiene un riepilogo della risposta, incluse le statistiche di utilizzo:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
L’evento di errore
Questo evento segnala gli errori. Secondo il riferimento xAI, la maggior parte degli errori è recuperabile e la connessione WebSocket rimane aperta:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Formato audio specificato non valido"
}
}
La tua applicazione dovrebbe registrare questi errori e, a seconda della loro gravità, mostrare un messaggio all’utente o tentare di risolvere il problema automaticamente.
Punti chiave
- Il server invia eventi per ogni fase: rilevamento vocale, audio, trascrizione, testo ed errori
- L’audio di risposta arriva come frammenti base64 tramite
response.output_audio.delta - Le trascrizioni sono disponibili sia per l’input dell’utente che per l’output dell’agente
response.donesegna la fine di una risposta completa- La maggior parte degli errori segnalati tramite l’evento
errorè recuperabile: la connessione rimane aperta