Événements client vers serveur — Voice Agent API : conversations temps réel

Les messages que vous envoyez

L’API Voice Agent fonctionne par échange d’événements JSON via WebSocket. Dans cette leçon, vous allez découvrir tous les événements que votre application peut envoyer au serveur. Chaque événement a un rôle précis dans le cycle de la conversation.

Événement	Description	Quand l'utiliser
session.update	Configurer la session	Au démarrage et pour modifier la config
input_audio_buffer.append	Envoyer un chunk audio base64	En continu pendant l'enregistrement
input_audio_buffer.commit	Valider le buffer audio	En mode push-to-talk
input_audio_buffer.clear	Vider le buffer sans traitement	Pour annuler un enregistrement
conversation.item.create	Ajouter un message ou résultat de fonction	Historique, contexte, retours de fonctions
conversation.item.delete	Supprimer un élément par ID	Nettoyage de conversation
response.create	Demander une réponse	En mode manuel (auto avec VAD)
response.cancel	Annuler une réponse en cours	Interruption utilisateur

conversation.item.create

Cet événement permet d’injecter des messages dans la conversation sans passer par le flux audio. Il sert à trois cas principaux :

Ajouter un message texte utilisateur

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Quel est le statut de ma commande 12345 ?"
      }
    ]
  }
}

Injecter un historique de conversation

Avant de commencer la conversation vocale, vous pouvez pré-remplir l’historique avec des échanges précédents pour donner du contexte à l’agent :

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Bonjour, je suis votre assistant. Comment puis-je vous aider ?"
      }
    ]
  }
}

Retourner le résultat d’une fonction

Après l’exécution d’un appel de fonction, vous renvoyez le résultat via cet événement (voir la leçon 13 sur le function calling) :

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\": \"expédiée\", \"tracking\": \"FR123456789\"}"
  }
}

conversation.item.delete

Supprime un élément de la conversation par son identifiant :

{
  "type": "conversation.item.delete",
  "item_id": "item_audio_001"
}

Cela peut être utile pour supprimer un message erroné ou pour limiter la taille de l’historique de conversation.

response.create et response.cancel

response.create demande explicitement au serveur de générer une réponse. En mode VAD, cet événement est envoyé automatiquement après la détection de fin de parole :

{
  "type": "response.create"
}

response.cancel interrompt une réponse en cours de génération. C’est utile quand l’utilisateur parle par-dessus l’agent :

{
  "type": "response.cancel"
}

Points clés à retenir

Huit types d’événements peuvent être envoyés du client vers le serveur
session.update configure la session et peut être envoyé plusieurs fois
conversation.item.create permet d’ajouter du texte, de l’historique ou des résultats de fonctions
response.create est nécessaire en mode manuel, automatique en mode VAD
response.cancel permet d’interrompre l’agent quand l’utilisateur reprend la parole