Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Eventi server-to-client

Lezione 10 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. I messaggi che ricevi
  2. Eventi di sessione e conversazione
  3. Eventi del buffer audio
  4. Eventi audio di risposta
  5. Eventi di trascrizione
  6. Eventi di testo
  7. Eventi di chiamata di funzione
  8. response.done
  9. L’evento di errore
  10. Punti chiave

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 sessione
  • session.updated: la configurazione è stata aggiornata con successo
  • conversation.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 parlare
  • input_audio_buffer.speech_stopped: il VAD rileva la fine del discorso
  • input_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’utente
  • response.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 streaming
  • response.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.done segna la fine di una risposta completa
  • La maggior parte degli errori segnalati tramite l’evento error è recuperabile: la connessione rimane aperta