Événements session.created et session.updated

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 via des événements JSON. Les deux premiers événements que vous recevez sont session.created (à l’ouverture de la connexion) et session.updated (après chaque configuration réussie).

session.created

Cet événement est envoyé automatiquement par le serveur dès que la connexion WebSocket est établie et authentifiée. Il confirme que la session est active et prête à être configurée :

{
  "type": "session.created",
  "session": {
    "id": "sess_abc123def456",
    "object": "realtime.session",
    "model": "grok-3",
    "voice": "Eve",
    "instructions": "",
    "tools": [],
    "turn_detection": {
      "type": "server_vad",
      "threshold": 0.5,
      "silence_duration_ms": 300,
      "prefix_padding_ms": 200
    }
  }
}

Ce message contient les valeurs par défaut de la session. Notez que les instructions sont vides et que la voix par défaut est Eve. C’est pourquoi vous devez envoyer un session.update juste après pour personnaliser ces paramètres.

Que faire à la réception de session.created

Votre application doit :

1. Stocker l’identifiant de session (session.id) pour le suivi et le débogage
2. Envoyer immédiatement votre session.update avec la configuration souhaitée
3. Ne pas envoyer d’audio tant que session.updated n’a pas été reçu

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

  switch (event.type) {
    case "session.created":
      console.log("Session créée :", event.session.id);
      // Envoyer la configuration
      ws.send(JSON.stringify({
        type: "session.update",
        session: {
          instructions: "Vous êtes un assistant vocal.",
          voice: "Rex",
          turn_detection: {
            type: "server_vad",
            threshold: 0.85,
            silence_duration_ms: 500,
            prefix_padding_ms: 333
          }
        }
      }));
      break;
  }
});

session.updated

Cet événement est la confirmation du serveur que votre session.update a été appliqué avec succès. Il renvoie la configuration complète après fusion :

{
  "type": "session.updated",
  "session": {
    "id": "sess_abc123def456",
    "object": "realtime.session",
    "model": "grok-3",
    "voice": "Rex",
    "instructions": "Vous êtes un assistant vocal.",
    "tools": [],
    "turn_detection": {
      "type": "server_vad",
      "threshold": 0.85,
      "silence_duration_ms": 500,
      "prefix_padding_ms": 333
    }
  }
}

Vérification de la configuration

Comparez toujours les valeurs retournées dans session.updated avec celles que vous avez envoyées. Cela vous permet de détecter les erreurs silencieuses (un paramètre ignoré, une valeur corrigée par le serveur) :

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

  // La session est prête — activer la capture audio
  startAudioCapture();
  break;

conversation.created

Juste après session.created, le serveur envoie également un événement conversation.created qui initialise l’objet de conversation :

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

Cet événement confirme que le canal de conversation est ouvert. Chaque session contient une seule conversation.

Séquence complète d’initialisation

Pour résumer, voici l’ordre des événements lors du démarrage d’une session vocale :

1. Ouverture du WebSocket (handshake HTTP → upgrade 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)
6. La session est prête pour l’échange audio

Points clés à retenir

• session.created est le premier événement reçu et contient les paramètres par défaut de la session
• session.updated confirme que votre configuration a été appliquée
• Ne commencez pas à envoyer de l’audio avant d’avoir reçu session.updated
• conversation.created initialise le canal de conversation (un par session)
• Stockez l’identifiant de session pour le suivi et le débogage