Guide de l'API de la plate-forme de chat

Cette page explique comment utiliser les points de terminaison de chat décrits dans Points de terminaison de l'API de la plate-forme de chat.

Terminologie

Pour plus de clarté, voici quelques définitions importantes à retenir lorsque vous utilisez ce document.

Client : client de la plate-forme Contact Center AI (CCAI Platform) qui implémente l'API de la plate-forme de chat dans son logiciel.
Consommateur : logiciel qui envoie des requêtes à l'API de la plate-forme de chat.
Utilisateur final : utilisateur du logiciel du client qui tente de discuter avec un agent.

Authentification Webhook

L'API de la plate-forme de chat communique les événements qui se produisent pendant le chat au consommateur en envoyant des requêtes de webhook au serveur du consommateur. Les types et charges utiles des Webhooks sont définis dans la spécification de l'API. Chaque requête de Webhook contient deux en-têtes, X-Signature et X-Signature-Timestamp.

X-Signature contient une signature de webhook au format suivant : primary=<primary_signature> secondary=<secondary_signature>

Les signatures principale et secondaire sont un condensé sha256 encodé en base64 des secrets de webhook principal ou secondaire, respectivement, avec une chaîne concaténée de l'en-tête X-Signature-Timestamp et de la charge utile JSON de la requête.

Voici un exemple d'implémentation de l'autorisation pour les requêtes de webhook dans un exemple d'application Ruby on Rails :

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

Présentation

En général, le flux de base d'une conversation avec l'API d'une plate-forme de chat doit se dérouler comme suit. Les points clés sont numérotés et des notes sont fournies pour plus de contexte. Notez que le client n'est responsable que de l'implémentation du côté "Client" du diagramme, tandis que Contact Center AI Platform gère les côtés "Notre système" et "Agent" du diagramme. Leur inclusion dans le diagramme ne vise qu'à donner au lecteur un contexte pour le flux global d'une discussion.

Le flux d'une conversation avec une API de plate-forme de chat est illustré.

Créer des utilisateurs finaux

Les discussions nécessitent un ID d'utilisateur final valide lors de leur création. Cela signifie qu'un utilisateur final doit exister dans le système Contact Center AI Platform avant la création d'une discussion.
Les utilisateurs finaux sont identifiés de manière unique par leur attribut identifier, qui est une valeur de chaîne fournie par le consommateur. Il est possible qu'un utilisateur final existe déjà dans le système s'il a utilisé les SDK Web ou mobile. Le point de terminaison POST /end_users est implémenté en tant qu'upsert idempotent. Par conséquent, si un utilisateur final existe déjà, toute tentative de création mettra à jour les données modifiées et renverra les informations de l'utilisateur final.

Créer des discussions

Pour créer des discussions à l'aide de l'API de la plate-forme de chat, procédez comme suit :

Gestion des nouvelles charges utiles de chat : le processus d'initialisation du chat se déroule de manière asynchrone par rapport à la requête POST /chats. Par conséquent, l'événement chat_created peut être reçu avant ou après la réponse de l'API du point de terminaison de création POST /chats. Il est recommandé de gérer l'événement chat_created et la réponse de l'API de création de chat de manière idempotente pour éviter tout bug dans le consommateur.
Créer des discussions avec des transcriptions : l'API de la plate-forme de chat permet de créer une discussion avec la transcription d'une conversation existante, dans le cas où une discussion a lieu sur la plate-forme d'un client, par exemple avec un chatbot, avant d'être envoyée à Contact Center AI Platform. Cela fournit à l'agent qui répond au chat des informations supplémentaires sur la session de chat et permet d'éviter que l'utilisateur final ne se répète. Pour connaître le format de la charge utile de la transcription, consultez chat_platform_openapi.yaml.

Agent virtuel de sélection de file d'attente

Pour simplifier la sélection de menu pour les consommateurs d'API, l'API de plate-forme de chat est conçue pour être utilisée conjointement avec un agent virtuel Dialogflow afin d'aider à placer les nouveaux chats dans la file d'attente.

Pour configurer l'agent virtuel, vous devez suivre les étapes suivantes :

Créez un agent virtuel dédié à cet effet et attribuez-le à une file d'attente. Toutes les nouvelles discussions créées par l'API de la plate-forme de chat doivent être créées dans cette file d'attente. La création et la configuration d'un agent virtuel ne sont pas abordées dans ce document.
Lorsque vous créez une discussion avec le point de terminaison POST ou chats, incluez une charge utile de contexte personnalisée qui inclut du contexte sur la discussion créée que l'agent virtuel peut utiliser pour déterminer la file d'attente vers laquelle la discussion doit être acheminée. La charge utile du contexte peut contenir n'importe quelle donnée personnalisée définie par le client, mais elle doit être au format suivant pour que les données soient accessibles par l'agent virtuel attribué à la file d'attente.
- Par exemple, "context": {"value": {"foo": "bar" } } permettrait à l'agent virtuel de lire $session.params.context.foo avec une valeur de bar.
À l'aide des données contenues dans le champ de contexte, l'agent virtuel (en fonction de la façon dont le client l'a configuré) transfère le chat vers la file d'attente sélectionnée. Si aucun agent n'est disponible dans la file d'attente cible (par exemple, si une file d'attente est hors des heures de travail ou en dépassement de capacité), l'escalade est déviée et le consommateur reçoit un webhook indiquant la raison de la déviation et les options de déviation disponibles.

Éviter l'escalade : les escalades de chat dans l'API de la plate-forme de chat sont compatibles avec les options d'évitement suivantes, si elles sont configurées dans le portail Contact Center AI Platform :

E-mail : demandez à l'utilisateur final d'envoyer un e-mail à l'assistance et de mettre fin au chat. Lorsqu'un utilisateur final sélectionne cette option, une fois l'e-mail envoyé, le client doit marquer le chat comme résolu et terminé à l'aide du point de terminaison PATCH /chats/:id avec les paramètres suivants dans le corps de la requête : "status": "finished" , "escalation_id": <id of escalation> , et "deflection_channel": "email".
Continuer avec l'agent virtuel : il s'agit techniquement d'une option de redirection valide, mais elle n'a pas de sens pour l'utilisation de l'agent virtuel de sélection de file d'attente, car l'agent virtuel essaierait simplement d'escalader à nouveau la discussion.
Continuer à attendre un agent humain : cette option ne peut être utilisée que pour les escalades dont le motif est over_capacity. Si l'utilisateur final choisit cette option, mettez à jour la déviation de l'escalade avec PATCH chats/:id/escalations/:id with deflection_channel=human_agent.
- Lien de déviation externe : avertissez l'utilisateur final que la sélection d'un lien fourni dans la déviation mettra fin au chat. Si un lien est sélectionné, mettez fin à la discussion et utilisez external_link pour le paramètre deflection_channel.

Envoyer et recevoir des messages

Pour envoyer ou recevoir des messages, procédez comme suit :

Contenu textuel : pour envoyer des messages texte, utilisez le point de terminaison POST /chats/:id/message tel que défini dans la documentation de l'API. Pour recevoir des messages, écoutez l'événement de webhook message_received. Notez que le consommateur d'API recevra un événement message_received pour tous les messages envoyés à l'aide de l'API, y compris ceux envoyés par l'utilisateur final.
Contenu photo et vidéo : le contenu photo et vidéo est envoyé en récupérant une URL d'importation pré-signée pour un service Cloud Storage configuré depuis Contact Center AI Platform, en l'important dans le service de stockage, puis en envoyant l'URL de stockage dans une charge utile de message à Contact Center AI Platform.
1. Récupérer l'URL pré-signée : récupérez une URL de transfert pré-signée depuis Contact Center AI Platform à l'aide de POST /v1/chats/:chat_id/photos/upload ou POST /v1/chats/:chat_id/videos/upload endpoints. Ce point de terminaison renvoie une URL présignée, ainsi qu'une collection de champs à transférer au service de stockage lors de l'importation du fichier. Les importations avec URL signée sont soumises aux restrictions suivantes :
  - Content-Type est défini sur image/jpeg pour les photos et sur video/mp4 pour les vidéos.
  - La taille maximale des photos est de 2 Mo. La taille maximale de la vidéo est de 20 Mo.
  - Le délai d'expiration est de cinq minutes.
  - Le client doit redimensionner la photo et ajuster son orientation avant de l'importer.
  - Chaque URL pré-signée correspond à une seule photo ou vidéo. Pour envoyer plusieurs pièces jointes, vous devez demander une URL pré-signée pour chacune d'elles.
2. Importer le fichier multimédia : pour importer le fichier multimédia, envoyez une requête POST à l'URL pré-signée récupérée à l'étape 2a avec les éléments suivants dans le corps de la requête :
  - "file" : fichier à importer
  - Tous les champs renvoyés dans l'objet "fields" de la requête d'URL pré-signée.
3. Ajouter le fichier multimédia à la discussion : pour ajouter le fichier multimédia à la discussion, utilisez le point de terminaison POST /chats/:id/photos ou POST /chats/:id/videos. Notez que le point de terminaison des photos permet d'envoyer un tableau de photos, tandis que le point de terminaison des vidéos ne permet d'envoyer qu'une seule vidéo à la fois.
  - Le paramètre de corps de requête s3_path doit avoir la même valeur que le champ key de la réponse de l'URL pré-signée.
  - Si la requête aboutit, elle renvoie deux champs. Il est recommandé d'enregistrer ou de mettre en cache un mappage de media_id vers l'URL dans le consommateur d'API, car tous les contenus multimédias des messages de chat seront référencés uniquement par media_id.
    - url : URL S3 ou Cloud Storage en lecture seule où se trouve le fichier.
    - media_id : ID du fichier multimédia dans Contact Center AI Platform. Il s'agit de l'ID par lequel le contenu multimédia sera référencé dans les charges utiles de chat.
4. Envoyer le fichier multimédia en tant que message de chat : pour envoyer le fichier multimédia en tant que message de chat, envoyez la charge utile suivante à POST /chats/:id/message endpoint :
```
{
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

S'attendre à des clés JSON non reconnues dans les réponses de l'API

Toutes les mises à jour de l'API sont rétrocompatibles. Nous nous réservons le droit d'introduire de nouvelles clés JSON dans les réponses d'API existantes à tout moment. Nous vous recommandons de gérer les réponses de manière défensive en ignorant les clés non reconnues pour maintenir la fonctionnalité.

Guide de l'API de la plate-forme de chat Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.