Événements session.created et session.updated

Leçon corrigée le 3 novembre 2026 d’après la page Speech to Speech et la référence de l’API Voice de xAI : la référence ne détaille pas le contenu de l’objet session de ces événements, et les valeurs que montrait l’ancienne version ("model": "grok-4.5", réglages threshold, silence_duration_ms, prefix_padding_ms) n’y figurent pas ; l’identifiant à conserver est celui de la conversation, conversation.id, qui sert à la reprise de session. Sources : Speech to Speech · Voice API.

Les événements de session du serveur

Lorsque vous interagissez avec l’API Voice Agent, le serveur vous informe de l’état de la session par des événements JSON. Les premiers que vous recevez sont session.created, à l’ouverture de la connexion, et conversation.created ; viennent ensuite session.updated, après chaque configuration que vous envoyez.

session.created

Le serveur envoie cet événement automatiquement dès l’ouverture de la connexion WebSocket. D’après la référence, il contient la configuration de la session ; ses champs ne sont pas détaillés. Plutôt que de supposer des valeurs par défaut, journalisez-le une fois pour voir ce que renvoie le serveur, puis envoyez votre propre configuration.

Que faire à la réception de session.created

Votre application doit :

1. Journaliser l’événement, pour le débogage
2. Envoyer immédiatement votre session.update avec la configuration souhaitée
3. Vider le tampon audio accumulé en attendant la connexion

Le troisième point vient des recommandations de xAI pour réduire la latence perçue : démarrez la capture du micro dès l’ouverture de l’écran, sans attendre la connexion, conservez les échantillons en mémoire, puis envoyez-les dès que la connexion est prête et la configuration envoyée.

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

  switch (event.type) {
    case "session.created":
      console.log("Session créée :", event.session);
      // Envoyer la configuration
      ws.send(JSON.stringify({
        type: "session.update",
        session: {
          instructions: "Vous êtes un assistant vocal.",
          voice: "rex",
          turn_detection: { type: "server_vad" }
        }
      }));
      // Puis envoyer l'audio capturé en attendant la connexion
      viderTamponMicro(ws);
      break;
  }
});

session.updated

Cet événement accuse réception de votre session.update : la session est configurée. Pour certains réglages, la documentation précise que la valeur appliquée y est renvoyée — c’est le cas de la table de remplacements de prononciation (replace). Une configuration invalide, elle, est refusée par un événement error qui décrit le problème ; la session reste ouverte et garde sa configuration précédente.

Vérification de la configuration

Comparez les valeurs renvoyées avec celles que vous avez envoyées : c’est ainsi que l’on repère un paramètre ignoré.

case "session.updated":
  const s = event.session;
  console.log("Voix configurée :", s.voice);
  console.log("Nombre d'outils :", s.tools?.length ?? 0);
  break;

case "error":
  console.error("Configuration refusée :", event);
  break;

conversation.created

Le serveur envoie aussi un événement conversation.created, qui porte l’identifiant de la conversation :

{
  "type": "conversation.created",
  "conversation": {
    "id": "conv_xyz789"
  }
}

Conservez cet identifiant : c’est lui qui permet la reprise de session. Par défaut, une connexion perd l’historique de la conversation quand le WebSocket se ferme. Si vous envoyez "resumption": {"enabled": true} dans session.update, le serveur met chaque tour en cache ; à la reconnexion, rouvrez le WebSocket avec ?conversation_id=<id> et activez de nouveau la reprise : les tours précédents sont rejoués avant votre premier nouveau tour. L’historique est effacé après 30 minutes d’inactivité.

Séquence complète d’initialisation

Pour résumer, voici l’ordre des événements au démarrage d’une session vocale, tel que le décrit la référence :

1. Ouverture du WebSocket
2. Réception de session.created (serveur → client)
3. Réception de conversation.created (serveur → client)
4. Envoi de session.update (client → serveur)
5. Réception de session.updated (serveur → client)

Points clés à retenir

• session.created arrive à l’ouverture de la connexion et contient la configuration de la session, dont la référence ne détaille pas les champs
• session.updated accuse réception de votre configuration ; une configuration invalide renvoie un événement error
• Capturez le micro avant la connexion et videz le tampon dès qu’elle est prête
• conversation.created porte l’identifiant conversation.id, à conserver pour la reprise de session
• La reprise demande resumption.enabled à chaque connexion, et l’historique expire après 30 minutes d’inactivité