Événements de session externes

La fonctionnalité d'événements de session externes permet la diffusion de données en temps réel de CCAI Platform vers vos systèmes externes à l'aide de webhooks. Vous bénéficiez ainsi d'une visibilité immédiate sur les cycles de vie des sessions pour la création de rapports personnalisés, la mise à jour des enregistrements CRM ou les workflows automatisés post-interaction.

Les événements de session externes fournissent un mécanisme basé sur la diffusion pour avertir votre serveur chaque fois que l'état d'un chat ou d'un appel vocal change. En fournissant un point de terminaison d'API, CCAI Platform envoie des données d'événement au format JSON à votre infrastructure lorsque des transitions se produisent (par exemple, appel connecté, agent attribué, session déconnectée).

Configurer les événements de session externes

Pour configurer les événements de session externes, procédez comme suit :

  1. Dans le portail CCAI Platform, cliquez sur Settings > Developer Settings (Paramètres > Paramètres du développeur). Si le menu Settings (Paramètres) ne s'affiche pas, cliquez sur Menu.

  2. Dans le volet Session Data Export (Exportation des données de session), cliquez sur Manage Data Export Settings (Gérer les paramètres d'exportation des données). La page Session Data Export (Exportation des données de session) s'affiche.

  3. Accédez au volet External Session Events (Événements de session externes), puis cliquez sur le bouton pour l'activer.

  4. Effectuez l'une des opérations suivantes, ou les deux :

    • Pour configurer les événements de session d'appel externes, procédez comme suit :

      1. Cochez la case Call events - Send call sessions event (Événements d'appel – Envoyer un événement de session d'appel).

      2. Dans le champ API Endpoint (Point de terminaison d'API), saisissez l'URL HTTPS complète de votre API cible.

      3. Saisissez le nom d'utilisateur et le mot de passe. La plate-forme les utilise pour l'authentification de base.

    • Pour configurer les événements de session de chat externes, procédez comme suit :

      1. Cochez la case Chat events - Send chat sessions event (Événements de chat – Envoyer un événement de session de chat).

      2. Dans le champ API Endpoint (Point de terminaison d'API), saisissez l'URL HTTPS complète de votre API cible.

      3. Saisissez le nom d'utilisateur et le mot de passe. La plate-forme les utilise pour l'authentification de base.

  5. Cliquez sur Save (Enregistrer).

Cycle de vie des événements et logique d'état

Au fur et à mesure qu'une session progresse, CCAI Platform envoie plusieurs mises à jour. Chaque mise à jour enrichit l'objet item avec davantage de métadonnées à mesure qu'elles deviennent disponibles.

Tableau de progression de l'état

Ordre des événements État État des participants Points de données clés ajoutés
1. Démarrer connected Externe : connected call_id, dn du client (numéro de téléphone).
2. Routage connected Externe : connected queue_path_names, initiator (agent virtuel).
3. Attribué connected Agent: accepted Le nom et l'ID de l'agent en direct sont ajoutés.
4. Actif connected Agent: connected Flux multimédia établi (début de la conversation).
5. Terminer disconnected Les deux : disconnected L'horodatage ends_at est renseigné.
6. Finale disconnected Agent: dispositionSubmitted Objet dispositions contenant les codes de finalisation.

Documentation de référence sur le schéma des données d'événement

Les événements sont envoyés au webhook dans un objet. Chaque événement de webhook a la même structure, qui est présentée dans le tableau suivant :

Objet racine

Champ Type Description
count Integer Nombre d'objets d'événement dans la charge utile actuelle.
events Tableau Collection d'objets d'événement contenant les détails de la session.

Champs de session clés

  • event_id: UUID pour la notification d'événement.
  • timestamp: heure epoch en millisecondes à laquelle l'événement a été généré.
  • connected_at et ends_at : horodatages ISO 8601 pour la durée de la session.
  • initiator : identifie l'entité qui a géré le changement d'état (par exemple, virtual_agent_15 ou agent_1).
  • dispositions : objet imbriqué contenant code, custom_code_id et toute note de l'agent.

Sécurité

Toutes les requêtes sont envoyées avec un en-tête d'autorisation standard : Authorization: Basic <base64_encoded_credentials>

Consignes à respecter pour la distribution

  • Méthode : POST
  • Type de contenu : application/json
  • Délai avant expiration : votre serveur doit répondre dans un délai de cinq secondes.
  • Accusé de réception : votre point de terminaison doit renvoyer un code d'état 200 OK. La plate-forme peut utiliser des nouvelles tentatives avec intervalle exponentiel si un code autre que 200 est reçu.

Exemples de charges utiles

Voici des exemples de charges utiles reçues dans les messages d'événement envoyés au webhook.

Conversation active (média connecté)

{
  "count": 1,
  "events": [
    {
      "event_id": "fc066edb-d99f-4db4-ba04-fb5dfea0e86a",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "connected",
        "queue_path_names": "Test/Talk to Andrew/English",
        "participants": [
          { "state": "connected", "type": "external", "dn": "+15555555555" },
          { "state": "connected", "type": "agent", "name": "Joe Smith", "agent_number": "528431" }
        ]
      }
    }
  ]
}

Disposition finale (travail après appel)

{
  "count": 1,
  "events": [
    {
      "event_id": "479798ff-b1ed-4a5c-a910-17a7edb3f283",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "disconnected",
        "participants": [
          {
            "type": "agent",
            "state": "dispositionSubmitted",
            "dispositions": {
              "code": "Call completed",
              "custom_code_id": "callComplete",
              "note": "none"
            }
          }
        ]
      }
    }
  ]
}