Maitriser les Evenements WebSocket

Le protocole evenementiel du Voice Agent

La communication entre votre application et le Voice Agent repose sur un echange d’evenements JSON via WebSocket. Chaque evenement possede un champ type qui identifie son role. Comprendre ces evenements est essentiel pour construire une application vocale robuste.

Evenements client vers serveur

Ce sont les messages que votre application envoie au serveur :

Gestion de la session

• session.update : configure ou reconfigure la session (voix, instructions, outils, VAD, format audio)

Gestion du buffer audio

• input_audio_buffer.append : envoie un chunk d’audio encode en base64. Vous appelez cet evenement en continu pendant que l’utilisateur parle
• input_audio_buffer.commit : valide le contenu actuel du buffer comme un message de l’utilisateur. Necessaire uniquement en mode manuel (sans VAD)
• input_audio_buffer.clear : vide le buffer audio sans le traiter

Gestion de la conversation

• conversation.item.create : ajoute un element a la conversation. Peut etre un message texte, un historique prealable, ou le resultat d’un appel de fonction
• conversation.item.delete : supprime un element de la conversation par son identifiant

Gestion des reponses

• response.create : demande au modele de generer une reponse. En mode VAD, ce declenchement est automatique ; en mode manuel, vous devez l’appeler explicitement
• response.cancel : annule une reponse en cours de generation

Evenements serveur vers client

Ce sont les messages que le serveur envoie a votre application :

Cycle de vie de la session

• session.created : confirme l’ouverture de la session
• session.updated : confirme une mise a jour de configuration
• conversation.created : confirme l’etablissement de la conversation

Detection de la parole (VAD)

• input_audio_buffer.speech_started : le VAD detecte que l’utilisateur commence a parler
• input_audio_buffer.speech_stopped : le VAD detecte que l’utilisateur a cesse de parler
• input_audio_buffer.committed : le buffer audio a ete valide (automatiquement par le VAD ou manuellement)

Reponse audio

• response.created : une reponse est en cours de generation
• response.output_audio.delta : un chunk d’audio de reponse en base64
• response.output_audio.done : l’audio de reponse est complet
• response.output_audio_transcript.delta : la transcription texte de l’audio en streaming
• response.done : la reponse est entierement terminee

Transcription de l’entree

• conversation.item.input_audio_transcription.completed : la transcription du message de l’utilisateur est disponible

Texte et fonctions

• response.text.delta : du texte en streaming (pour les reponses non vocales)
• response.function_call_arguments.delta : les arguments d’un appel de fonction arrivent en streaming
• response.function_call_arguments.done : l’appel de fonction est complet, pret a etre execute

Erreurs

• error : une erreur recuperable s’est produite. Votre application doit la gerer sans couper la connexion

Implementer le flux en pratique

Voici le squelette typique d’un client Voice Agent en JavaScript :

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "session.created":
      // Envoyer session.update avec la configuration
      break;

    case "input_audio_buffer.speech_started":
      // L'utilisateur parle : couper l'audio de reponse en cours
      break;

    case "response.output_audio.delta":
      // Decoder le base64 et jouer l'audio
      playAudioChunk(msg.delta);
      break;

    case "response.function_call_arguments.done":
      // Executer la fonction et renvoyer le resultat
      handleFunctionCall(msg);
      break;

    case "error":
      console.error("Erreur Voice Agent:", msg.error);
      break;
  }
};

Gerer les interruptions

Quand l’utilisateur parle pendant que l’agent repond (barge-in), le VAD envoie speech_started. A ce moment, vous devez :

1. Arreter la lecture audio de la reponse en cours
2. Vider votre buffer de sortie pour eviter de jouer de l’audio obsolete
3. Laisser le serveur traiter la nouvelle entree de l’utilisateur

Le serveur annule automatiquement la reponse en cours et commence a en generer une nouvelle basee sur ce que l’utilisateur vient de dire.

Points cles a retenir

• Les evenements client couvrent la configuration, l’envoi audio, la gestion de conversation et le controle des reponses
• Les evenements serveur informent sur la detection de parole, les chunks audio, les transcriptions et les appels de fonctions
• Le VAD gere automatiquement les interruptions (barge-in)
• L’evenement error est recuperable : ne fermez pas la connexion, gerez l’erreur
• En mode manuel, vous devez appeler commit puis response.create explicitement