Événements de session externes

La fonctionnalité d'événements de session externes permet de diffuser des données en temps réel depuis la CCAI Platform vers vos systèmes externes à l'aide de webhooks. Cela permet d'obtenir une visibilité immédiate sur les cycles de vie des sessions pour les rapports personnalisés, les mises à jour des enregistrements CRM ou les workflows post-interaction automatisés.

Les événements de session externes fournissent un mécanisme push 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, la plate-forme CCAI enverra des données d'événement au format JSON à votre infrastructure lorsque des transitions se produiront (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 pour les développeurs). Si le menu Paramètres ne s'affiche pas, cliquez sur  Menu.

  2. Dans le volet Exportation des données de session, cliquez sur Gérer les paramètres d'exportation des données. La page Exporter les données de session s'affiche.

  3. Accédez au volet Événements de session externes, puis cliquez sur le bouton bascule pour l'activer.

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

    • Pour configurer les événements de session d'appel externe :

      1. Cochez la case Événements d'appel : envoyer l'événement "Sessions d'appel".

      2. Dans le champ Point de terminaison de l'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 externe :

      1. Cochez la case Événements de chat – Événement "Envoyer des sessions de chat".

      2. Dans le champ Point de terminaison de l'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 Enregistrer.

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

Au fur et à mesure de la progression d'une session, 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 des états

Ordre des événements État État des participants Ajout de points de données clés
1. Démarrer connected Externe : connected call_id, Client dn (numéro de téléphone).
2. Routage connected Externe : connected queue_path_names, initiator (agent virtuel).
3. Attribuée connected Agent : accepted Le nom et l'ID de l'agent en direct sont ajoutés.
4. Actif connected Agent : connected Le flux multimédia est établi (la conversation commence).
5. Fin disconnected Les deux : disconnected L'horodatage ends_at est renseigné.
6. Final disconnected Agent : dispositionSubmitted Objet dispositions contenant les codes de clôture.

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 des informations sur la session.

Champs clés des sessions

  • event_id : UUID de la notification d'événement.
  • timestamp : heure epoch en millisecondes à laquelle l'événement a été généré.
  • connected_at et ends_at : codes temporels 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 tout note d'agent.

Sécurité

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

Exigences concernant la distribution

  • Méthode : POST
  • Content-Type : 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 tentatives avec intervalle exponentiel entre elles si un code autre que 200 est reçu.

Exemples de charges utiles

Vous trouverez ci-dessous des exemples de charges utiles reçues dans les messages d'événement envoyés au webhook.

Conversation active (multimé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"
            }
          }
        ]
      }
    }
  ]
}