Guide d'intégration de l'API de la plate-forme de chat

Utilisez ce guide pour créer une intégration de chat côté serveur avec l'API Apps. À la fin, votre intégration pourra :

  • Authentifiez-vous auprès de l'API Apps.

  • Créez ou mettez à jour un utilisateur final.

  • Démarrez une discussion avec cet utilisateur final.

  • Recevez et validez les événements de webhook provenant de Contact Center AI Platform.

  • Envoyez des messages dans le chat.

  • Gérez les branches facultatives telles que l'importation de la transcription avant le chat, le routage de l'agent virtuel pour la sélection de la file d'attente, les déviations d'escalade et les pièces jointes multimédias.

  • Mettez fin au chat lorsque la conversation est terminée.

Ce guide s'adresse aux développeurs qui créent un service de backend permettant de connecter une expérience de chat appartenant au client à CCAI Platform. Il suppose que vous pouvez créer des identifiants API dans CCAI Platform, héberger un point de terminaison de webhook HTTPS, stocker des secrets de manière sécurisée et effectuer des requêtes HTTP depuis votre serveur.

Ce guide complète les points de terminaison de l'API Chat Apps. Consultez la documentation de référence de l'API pour obtenir le schéma complet des requêtes et des réponses, et utilisez ce guide pour connaître le flux d'implémentation de bout en bout recommandé.

Terminologie

Les définitions suivantes s'appliquent à ce document :

  • Client : client CCAI Platform qui implémente l'intégration du chat dans son propre logiciel.

  • Consommateur : application côté serveur appartenant au client qui envoie des requêtes à l'API Apps et reçoit les événements de webhook de la plate-forme CCAI.

  • Utilisateur final : personne qui utilise le logiciel du client pour démarrer ou poursuivre une discussion avec un agent ou un agent virtuel.

  • Chat : ressource de conversation CCAI Platform créée par l'API Apps.

  • Point de terminaison du webhook : point de terminaison HTTPS dans l'application consommateur qui reçoit les événements de chat de la plate-forme CCAI.

Avant de commencer

Avant de commencer, vérifiez que vous disposez des éléments suivants :

  • Identifiants de l'API Apps

    • Créez des identifiants d'API dans CCAI Platform en accédant à Paramètres > Paramètres pour les développeurs > Identifiants d'API.

    • Stockez le secret des identifiants de manière sécurisée. Ne l'exposez pas dans le code du navigateur ni du client mobile.

  • Détails de l'URL du locataire

    • Identifiez votre sous-domaine et votre domaine CCAI Platform.

    • L'URL de base de l'API Apps est la suivante : https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

  • Point de terminaison du webhook

    • Hébergez un point de terminaison HTTPS public pouvant recevoir des requêtes POST depuis la plate-forme CCAI.

    • Configurez le point de terminaison dans les paramètres pour les développeurs de CCAI Platform.

    • Générez et stockez les secrets principal et secondaire du webhook.

  • Configuration de la file d'attente ou du menu

    • Identifiez la file d'attente ou le menu dans lesquels les nouvelles discussions sont placées.

    • Si vous utilisez un agent virtuel de sélection de file d'attente, configurez-le et attribuez-le à la file d'attente d'entrée avant de créer des discussions via l'API.

  • Identité de l'utilisateur final

    • Choisissez l'identifiant stable que votre système utilisera pour chaque utilisateur final.

    • Stockez l'ID d'utilisateur final CCAI Platform renvoyé par l'API Apps.

  • Gestion des limites de débit

    • CCAI Platform limite le débit de l'API Apps. Intégrez des mécanismes de nouvelle tentative et d'intervalle entre les tentatives à votre intégration, et évitez d'envoyer des rafales de requêtes pour un seul locataire.

Authentification et sécurité des webhook

Votre intégration utilise deux chemins d'authentification :

  • Authentification de l'API Apps pour les requêtes de votre serveur vers CCAI Platform.

  • Vérification de la signature du webhook pour les requêtes envoyées par CCAI Platform à votre serveur.

Authentifier les requêtes API Apps

Les requêtes utilisent l'authentification HTTP de base. Créez un jeton API dans la plate-forme CCAI sous Paramètres > Paramètres de développement > Identifiants API, puis transmettez-le dans le champ mot de passe (recommandé). Si votre locataire utilise l'ancien chemin d'authentification, vous pouvez à la place transmettre votre clé d'entreprise comme nom d'utilisateur et votre code secret d'entreprise comme mot de passe. Consultez la documentation de référence de l'API Apps pour obtenir la configuration complète de l'authentification. L'exemple suivant montre comment authentifier une requête Apps API à l'aide de l'authentification de base :

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

Stockez les identifiants dans un espace secret côté serveur, faites-les tourner en fonction de votre règlement de sécurité et ne les incluez jamais dans les applications mobiles ou de navigateur.

Valider les requêtes de webhook

CCAI Platform envoie des événements de chat à votre point de terminaison de webhook. Chaque requête webhook inclut les éléments suivants :

  • X-Signature

  • X-Signature-Timestamp

L'en-tête X-Signature peut contenir une signature principale, une signature secondaire ou les deux :

primary=<primary_signature> secondary=<secondary_signature>

Chaque signature est un condensé HMAC-SHA256 encodé en base64. La valeur signée est l'en-tête d'horodatage concaténé avec le corps de la requête JSON brute :

X-Signature-Timestamp + raw_request_body

Dans votre gestionnaire de webhook :

  1. Consultez X-Signature et X-Signature-Timestamp.

  2. Rejetez la requête si l'un des en-têtes est manquant.

  3. Rejetez les codes temporels obsolètes pour réduire le risque de réutilisation.

  4. Lisez le corps de la requête brute avant d'analyser le fichier JSON.

  5. Calculez la signature attendue à l'aide de chaque secret de webhook actif.

  6. Comparez la signature reçue et la signature attendue à l'aide d'une comparaison à temps constant.

  7. Acceptez la demande si un secret actif correspond.

L'exemple d'implémentation Ruby suivant montre comment vérifier les signatures de webhook UJET :

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

Si la validation réussit, renvoyez rapidement une réponse de réussite et traitez l'événement de manière idempotente. Les réponses de l'API et les notifications de webhook peuvent arriver dans des ordres différents. Par conséquent, concevez votre intégration de manière à ce qu'elle puisse tolérer la réception de la même modification d'état plusieurs fois sans créer d'enregistrements en double.

Flux d'intégration

Le flux suivant crée un utilisateur final, démarre un chat, reçoit des événements CCAI Platform, échange des messages et met fin au chat.

Créer ou mettre à jour l'utilisateur final

Objectif : S'assurer que CCAI Platform dispose d'une fiche d'utilisateur final avant de créer le chat.

Point de terminaison

Utilisez le point de terminaison suivant pour créer ou modifier un utilisateur final :

POST /apps/api/v1/end_users

Exemple de requête

L'exemple suivant illustre un corps de requête permettant de créer ou de mettre à jour un utilisateur final :

{
  "identifier": "customer-user-12345",
  "email": "customer.user@example.com",
  "name": "Customer User",
  "phone": "+15551234567"
}

Éléments à stocker

Stockez l'ID d'utilisateur final CCAI Platform de la réponse dans votre système. Utilisez cet ID lorsque vous créez un chat.

À quoi faut-il s'attendre ?

  • Si l'utilisateur final n'existe pas, la plate-forme CCAI crée un enregistrement.

  • Si un utilisateur final existe déjà avec le même identifiant, CCAI Platform met à jour l'enregistrement et renvoie les informations de l'utilisateur final existant.

Créer le chat

Objectif : Démarrer une nouvelle discussion CCAI Platform pour l'utilisateur final.

Point de terminaison

Utilisez le point de terminaison suivant pour démarrer une nouvelle discussion :

POST /apps/api/v1/chats

Exemple de requête

L'exemple suivant montre un corps de requête pour créer une discussion :

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

Contexte facultatif pour le routage des agents virtuels

Si votre agent virtuel de sélection de file d'attente a besoin du contexte de votre application, incluez une charge utile de contexte lorsque vous créez le chat, comme illustré dans l'exemple suivant :

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

Un agent virtuel peut utiliser les valeurs de ce contexte pour déterminer la file d'attente à laquelle le chat est attribué.

À quoi faut-il s'attendre ?

  • L'API Apps renvoie la ressource de chat.

  • CCAI Platform envoie un événement de webhook chat_created au point de terminaison du webhook que vous avez configuré.

  • La réponse de l'API et l'événement de webhook peuvent arriver dans n'importe quel ordre. Traitez les deux comme des mises à jour du même enregistrement de chat, identifié par l'ID de chat.

Traiter les événements de webhook de chat

Objectif : synchroniser l'application grand public avec l'état du chat CCAI Platform.

Votre point de terminaison de webhook gère le cycle de vie du chat et les événements de message de CCAI Platform. Au minimum, le magasin doit :

  • ID du chat.

  • Type d'événement.

  • Code temporel de l'événement.

  • Expéditeur, type et contenu du message lorsque l'événement contient un message.

  • Toutes les données d'escalade ou de redirection lorsque l'événement décrit le comportement de routage.

Comportement recommandé

  • Vérifiez la signature de chaque webhook avant de traiter l'événement.

  • Stockez les ID d'événement traités ou une clé d'événement déterministe afin que les nouvelles tentatives ne créent pas de doublons.

  • Renvoie une réponse 2xx après avoir accepté l'événement.

  • Traitez les effets secondaires en aval de manière asynchrone lorsque c'est possible.

À quoi faut-il s'attendre ?

Votre application met à jour son état de chat lorsque la plate-forme CCAI envoie des événements tels que la création d'un chat, les messages entrants, les messages d'agent, les changements d'escalade et la fin d'un chat.

Envoyer un SMS

Objectif : Envoyer un message d'utilisateur final depuis l'application consommateur vers le chat de la plate-forme CCAI.

Point de terminaison

Utilisez le point de terminaison suivant pour envoyer un message texte dans le chat :

POST /apps/api/v1/chats/{chat_id}/message

Exemple de requête

L'exemple suivant illustre un corps de requête pour l'envoi d'un message texte :

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

À quoi faut-il s'attendre ?

  • CCAI Platform accepte le message.

  • Le message s'affiche dans la conversation avec l'agent ou l'agent virtuel.

  • Votre point de terminaison de webhook reçoit un événement de message pour le message, y compris les messages que votre propre application a envoyés via l'API Apps.

Recevoir et afficher des messages depuis CCAI Platform

Objectif : afficher les messages de l'agent ou de l'agent virtuel dans l'expérience de chat appartenant au client.

Lorsque votre point de terminaison de webhook reçoit un événement de message :

  1. Vérifiez la signature du webhook.

  2. Vérifiez si l'événement est nouveau.

  3. Identifiez le chat par son ID.

  4. Identifiez l'expéditeur et le type de message.

  5. Affichez le message dans l'interface utilisateur de chat appartenant au client.

  6. Persistez l'événement pour que l'historique des conversations ne soit pas perdu lors des actualisations ou des nouvelles tentatives.

À quoi faut-il s'attendre ?

L'UI de chat appartenant au client affiche les messages envoyés par les agents, les agents virtuels et l'utilisateur final dans le bon ordre. Si les événements arrivent dans le désordre, utilisez les codes temporels des événements et votre propre couche de persistance pour réconcilier l'ordre d'affichage.

Escalader une demande d'un agent virtuel à un agent humain

Objectif : transférer le chat de la gestion par un agent virtuel vers une file d'attente humaine lorsque l'utilisateur final a besoin de l'aide d'un agent.

Si votre intégration utilise un agent virtuel de sélection de file d'attente, configurez l'agent virtuel pour qu'il route les discussions vers la file d'attente cible. Si votre serveur lance directement l'escalade, utilisez le point de terminaison d'escalade de l'API Apps.

Point de terminaison

Utilisez le point de terminaison suivant pour transférer une discussion depuis un agent virtuel vers un agent humain :

POST /apps/api/v1/chats/{chat_id}/escalations

Exemple de requête

L'exemple suivant montre un corps de requête pour escalader une discussion :

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

À quoi faut-il s'attendre ?

  • Si la file d'attente cible est disponible, le chat est transféré à un agent.

  • Si la file d'attente n'est pas disponible en raison des conditions hors des heures de travail ou de dépassement de capacité, la plate-forme CCAI peut renvoyer ou envoyer des options de déviation via le flux de chat.

  • Votre intégration affiche les options de déviation disponibles à l'utilisateur final.

Enregistrer un choix de déviation d'escalade

Objectif : indiquer à CCAI Platform l'option de déviation sélectionnée par l'utilisateur final.

Lorsque la plate-forme CCAI propose des options de redirection, enregistrez le choix de l'utilisateur final avec le point de terminaison de mise à jour de l'escalade.

Point de terminaison

Utilisez le point de terminaison suivant pour mettre à jour un enregistrement d'escalade avec un choix d'évitement :

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

Valeurs deflection_channel acceptées :

  • email : l'utilisateur final choisit l'option de redirection des e-mails.

  • virtual_agent : l'utilisateur final choisit de continuer avec un agent virtuel.

  • human_agent : l'utilisateur final choisit de continuer à attendre un agent humain. Cette valeur ne s'applique qu'aux redirections en cas de dépassement de capacité.

Exemple de requête

L'exemple suivant illustre un corps de requête permettant d'enregistrer un choix de déviation :

{
  "deflection_channel": "email"
}

N'envoyez qu'une valeur deflection_channel acceptée à ce point de terminaison. external_link n'est pas une valeur valide pour le point de terminaison de mise à jour de l'escalade. Lorsque l'utilisateur final suit un lien de redirection externe, la discussion se termine à la place.

À quoi faut-il s'attendre ?

CCAI Platform met à jour l'enregistrement de l'escalade et transfère le chat en fonction de l'option sélectionnée.

Mettez fin à la discussion

Objectif : fermer le chat une fois la conversation terminée.

Point de terminaison

Utilisez le point de terminaison suivant pour mettre fin à une discussion active :

PATCH /apps/api/v1/chats/{chat_id}/end

Exemple de requête

L'exemple suivant illustre un corps de requête pour mettre fin à une discussion :

{
  "ended_by_user_id": 456
}

À quoi faut-il s'attendre ?

  • La plate-forme CCAI met fin au chat.

  • Votre point de terminaison de webhook reçoit l'événement d'état de discussion final.

  • Votre application marque le chat comme terminé et cesse d'accepter de nouveaux messages de l'utilisateur final pour ce chat.

Flux avancés

Les branches suivantes sont facultatives. N'implémentez que les flux qui s'appliquent à votre intégration.

Importer une transcription de pré-chat

Utilisez ce flux lorsque l'utilisateur final a déjà eu une conversation dans votre système avant que vous ne créiez le chat CCAI Platform, par exemple une conversation avec un chatbot.

Ajoutez la charge utile de la transcription lorsque vous créez le chat. La transcription fournit au conseiller un contexte qui évite à l'utilisateur final de répéter des informations.

La documentation de référence de l'API Apps inclut le schéma exact de la transcription.

Router les discussions avec un agent virtuel de sélection de file d'attente

Utilisez ce flux lorsque votre application envoie toutes les nouvelles discussions dans une file d'attente d'entrée et permet à un agent virtuel de décider de la file d'attente cible finale.

  1. Créez un agent virtuel pour la sélection de files d'attente.

  2. Attribuez l'agent virtuel à la file d'attente d'entrée.

  3. Incluez du contexte lorsque vous créez le chat.

  4. Configurez l'agent virtuel pour qu'il examine le contexte et transfère la discussion vers la file d'attente appropriée.

  5. Gérez les options de redirection si la file d'attente cible n'est pas disponible.

Envoyer des photos ou des vidéos en pièces jointes

Utilisez ce flux lorsque l'utilisateur final envoie des éléments multimédias depuis l'UI de chat appartenant au client.

Le flux multimédia comporte quatre étapes.

Étape 1 : Demander une URL de transfert pré-signée

Utilisez les points de terminaison suivants pour demander une URL présignée permettant d'importer une photo ou une vidéo :

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

Étape 2 : Importez le fichier dans l'URL de stockage renvoyée.

Incluez le fichier et tous les champs renvoyés par CCAI Platform dans la réponse presigned-upload.

Étape 3 : Ajouter le fichier importé à la discussion

Utilisez les points de terminaison suivants pour ajouter une photo ou une vidéo importée à la discussion :

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

Stockez le media_id renvoyé par CCAI Platform. Les charges utiles des messages de chat font référence aux éléments multimédias par leur ID.

Étape 4 : Envoyer le contenu multimédia sous forme de message

Utilisez le point de terminaison suivant pour envoyer un message multimédia dans le chat :

POST /apps/api/v1/chats/{chat_id}/message

Exemple de requête

L'exemple suivant illustre un corps de requête pour l'envoi d'une pièce jointe photo :

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": {
      "media_id": 789
    }
  }
}

Utilisez le type de message video et la vidéo media_id pour les messages vidéo.

Envoyer des données personnalisées pendant un chat

Utilisez le point de terminaison suivant lorsque votre intégration doit associer un contexte défini par le client à une discussion active :

POST /apps/api/v1/chats/{chat_id}/custom_data

La documentation de référence de l'API Apps définit la forme exacte de la charge utile et le comportement des clés réservées.

Mettre à jour l'identité de l'utilisateur final pendant une discussion

Utilisez le point de terminaison suivant lorsque l'identité de l'utilisateur final change ou devient connue après le début de la discussion :

POST /apps/api/v1/chats/{chat_id}/end_user

Par exemple, utilisez ce point de terminaison lorsqu'un utilisateur final anonyme se connecte pendant une discussion active et que votre intégration a besoin que CCAI Platform associe la discussion à l'identité mise à jour de l'utilisateur final.

Collecter des données de CSAT ou d'évaluation

Utilisez les points de terminaison suivants pour le score CSAT et l'évaluation du chat lorsque votre intégration est propriétaire de l'expérience d'évaluation post-chat :

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

Pour connaître les règles d'éligibilité exactes et les charges utiles de classification, consultez la documentation de référence de l'API Apps.