Événements serveur vers client

Les messages que vous recevez

Le serveur envoie de nombreux événements pour vous informer de l’état de la conversation, transmettre l’audio de réponse et signaler les erreurs. Comprendre ces événements est essentiel pour construire une application réactive et fiable.

Événements de session et de conversation

Ces événements sont envoyés au début de la connexion et après chaque modification de configuration :

• session.created : la session est ouverte, contient les paramètres par défaut
• session.updated : la configuration a été mise à jour avec succès
• conversation.created : le canal de conversation est initialisé

Événements du buffer audio

Ces événements vous informent de l’activité vocale détectée par le VAD :

• input_audio_buffer.speech_started : le VAD détecte que l’utilisateur commence à parler
• input_audio_buffer.speech_stopped : le VAD détecte la fin de la parole
• input_audio_buffer.committed : le buffer audio a été validé comme message

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "input_audio_buffer.speech_started":
      // L'utilisateur parle — afficher un indicateur visuel
      showSpeakingIndicator(true);
      break;

    case "input_audio_buffer.speech_stopped":
      // L'utilisateur a fini — masquer l'indicateur
      showSpeakingIndicator(false);
      break;

    case "input_audio_buffer.committed":
      // Le message audio est en cours de traitement
      showProcessingIndicator(true);
      break;
  }
});

Événements de réponse audio

L’audio de réponse est envoyé en streaming via deux événements :

response.output_audio.delta

Chaque delta contient un chunk d’audio encodé en base64. Vous devez les accumuler et les jouer en séquence :

{
  "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

Indique que tout l’audio de la réponse a été envoyé :

{
  "type": "response.output_audio.done",
  "item_id": "item_resp_001"
}

Événements de transcription

L’API peut transcrire à la fois l’audio de l’utilisateur et l’audio de la réponse :

• conversation.item.input_audio_transcription.completed : transcription de ce que l’utilisateur a dit
• response.output_audio_transcript.delta : transcription en streaming de la réponse de l’agent

case "conversation.item.input_audio_transcription.completed":
  console.log("Utilisateur a dit :", event.transcript);
  displayUserMessage(event.transcript);
  break;

case "response.output_audio_transcript.delta":
  appendAgentTranscript(event.delta);
  break;

Événements texte

Si l’agent génère du texte (en plus ou à la place de l’audio), vous recevez :

• response.text.delta : fragment de texte en streaming

{
  "type": "response.text.delta",
  "delta": "Votre commande a été"
}

Événements de function calling

Lorsque l’agent décide d’appeler une fonction, deux événements sont émis :

• response.function_call_arguments.delta : arguments de la fonction en streaming
• response.function_call_arguments.done : appel de fonction complet avec tous les arguments

Ces événements seront détaillés dans la leçon 13 sur le function calling vocal.

response.done

Cet événement marque la fin complète d’une réponse. Il contient un résumé de la réponse incluant les statistiques d’utilisation :

{
  "type": "response.done",
  "response": {
    "id": "resp_001",
    "status": "completed",
    "output": [...]
  }
}

Événement error

Les erreurs récupérables sont signalées par cet événement. La connexion WebSocket reste ouverte :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid audio format specified"
  }
}

Votre application doit journaliser ces erreurs et, selon leur gravité, afficher un message à l’utilisateur ou tenter de corriger le problème automatiquement.

Points clés à retenir

• Le serveur envoie des événements pour chaque étape : détection vocale, audio, transcription, texte et erreurs
• L’audio de réponse arrive en chunks base64 via response.output_audio.delta
• Les transcriptions sont disponibles pour l’entrée utilisateur et la sortie agent
• response.done marque la fin d’une réponse complète
• Les erreurs via l’événement error sont récupérables : la connexion reste ouverte