Maîtriser les Événements WebSocket

Une conversation faite d’événements JSON

Sous la surface, un échange vocal avec le Voice Agent n’est qu’une suite de messages JSON qui circulent dans les deux sens sur la connexion WebSocket. Chaque message porte un champ type qui dit ce qu’il est. Tant que vous ne connaissez pas ce vocabulaire, votre client fonctionne par chance ; dès que vous le maîtrisez, vous savez exactement où intervenir pour couper une réponse, afficher une transcription ou rattraper une erreur.

Les événements se répartissent en deux familles selon leur sens de circulation. Ceux que vous émettez pilotent la session ; ceux que vous recevez vous racontent ce qui se passe côté serveur.

Ce que votre application envoie

Vos messages sortants couvrent quatre besoins : configurer la session, alimenter le buffer audio, manipuler l’historique de conversation et contrôler la génération des réponses.

Deux de ces messages méritent qu’on s’y arrête. conversation.item.create est votre porte d’entrée pour injecter du contexte : c’est par lui que vous replacez l’historique d’un appel précédent au début d’une nouvelle session, contournant ainsi la limite de trente minutes. Quant à input_audio_buffer.clear, il rend service quand l’utilisateur a manifestement parlé pour ne rien dire — un raclement de gorge capté par un micro trop sensible — et que vous préférez repartir d’un buffer propre plutôt que de laisser le modèle interpréter du bruit.

Ce que le serveur vous renvoie

Le flux entrant est plus dense, parce qu’il commente en direct chaque étape du traitement.

Le dernier appelle une mise en garde. Recevoir error ne signifie pas que la session est perdue : ces erreurs sont récupérables, et un client qui ferme la connexion au premier error venu casse une conversation qui aurait pu continuer. Journalisez, informez éventuellement l’utilisateur, mais laissez la socket ouverte.

Le squelette d’un client

En pratique, tout se joue dans un aiguillage sur msg.type. Voici la forme minimale d’un client 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;
  }
};

Quatre branches suffisent à faire tourner un agent : configurer à l’ouverture, réagir à la prise de parole, jouer l’audio entrant, exécuter les fonctions. Le reste des événements sert à enrichir l’interface et peut attendre une seconde itération.

Le cas délicat : l’interruption

Le barge-in, c’est-à-dire l’utilisateur qui reprend la parole alors que l’agent est en train de répondre, est le moment où une implémentation approximative se voit. Le serveur annule de lui-même la réponse en cours et se met à en générer une nouvelle à partir de ce qu’il vient d’entendre. Mais lui a arrêté d’émettre, tandis que votre application, elle, tient encore dans son buffer de sortie plusieurs secondes d’audio déjà reçues.

Si vous ne faites rien, l’utilisateur continue d’entendre la phrase qu’il vient d’interrompre pendant qu’il parle par-dessus : l’effet est celui d’un agent qui n’écoute pas. Dès la réception de speech_started, coupez donc la lecture audio en cours, videz le buffer de sortie pour ne pas jouer de son devenu obsolète, et laissez le serveur traiter la nouvelle entrée. Ces deux gestes tiennent en quelques lignes et font toute la différence entre un agent qu’on peut couper et un agent qui parle dans le vide.

Points clés à retenir

• Les événements client couvrent la configuration, l’envoi audio, la gestion de conversation et le contrôle des réponses
• Les événements serveur informent sur la détection de parole, les chunks audio, les transcriptions et les appels de fonctions
• Le VAD gère automatiquement les interruptions (barge-in)
• L’événement error est récupérable : ne fermez pas la connexion, gérez l’erreur
• En mode manuel, vous devez appeler commit puis response.create explicitement