API SMS

Avec Contact Center AI Platform (CCAI Platform), vous pouvez utiliser l'API SMS pour gérer les SMS entrants et sortants.

Authentification

Pour utiliser l'API SMS, vous avez besoin d'identifiants.

Pour créer des identifiants pour l'API SMS, procédez comme suit :

  1. Dans le portail CCAI Platform, cliquez sur Settings (Paramètres) > Developer Settings (Paramètres du développeur) > API Credential management (Gestion des identifiants d'API).

  2. Cliquez sur le bouton + Add API Credential (+ Ajouter des identifiants d'API). Un message Add API Credential (Ajouter des identifiants d'API) s'ouvre.

  3. Saisissez un Name (Nom) pour les identifiants.

  4. Cliquez sur Create (Créer).

API SMS sortants

L'API SMS sortants fournit un point de terminaison permettant d'envoyer des SMS sortants. Elle permet d'automatiser l'envoi de SMS aux clients.

Voici trois points clés à prendre en compte lorsque vous utilisez cette API :

  • Ce service n'est pas conçu pour envoyer des dizaines de milliers de messages à la fois. L'objectif est d'envoyer des messages déclenchés par des événements.

  • Les clients peuvent répondre au SMS et lancer une session d'assistance.

  • Cette API ne fonctionne pas si vous devez envoyer plusieurs SMS au même numéro au cours de la même journée.

Cas d'utilisation

Les exemples de cas d'utilisation de l'API SMS sortants sont basés sur des événements. Par exemple, si vous voulez dire au client que sa commande est prête et qu'il peut la retirer tout en lui donnant la possibilité de répondre. Une session active est créée quand un SMS sortant est envoyé. Si le client répond, il est orienté vers un agent.

La différence entre cette API et l'API SMS sortants sans session est que, dans le cas de l'API sans session, vous n'envoyez que la notification. Si le client répond, il reçoit un message par défaut (si configuré) et n'est pas orienté vers un agent.

Autres cas d'utilisation possibles :

  • Connexion à votre compte
  • Activité du compte
  • Événements importants liés à l'utilisation du compte
  • Détection des problèmes liés aux appareils connectés
  • Notifications d'heure d'arrivée estimée pour les services à la demande, comme les livraisons et les services de covoiturage
  • Rappels de rendez-vous
  • Alertes proactives concernant le service ou le compte
  • Authentification à deux facteurs (nécessite que le client dispose d'un générateur de code et d'un processus de service existants)

Point de terminaison de l'API SMS sortants

L'URI de base de ce nouveau point de terminaison est la suivante :

POST https://<subdomain>.<domain>/apps/api/v1/sms

Assistance pour les SMS entrants

Si un environnement souhaite prendre en charge les réponses par SMS entrants, le numéro sortant doit également être configuré comme numéro de SMS entrant attribué à une file d'attente. Chaque numéro de téléphone SMS ne peut être attribué qu'à une seule file d'attente. Pour en savoir plus, consultez Configuration générale du chat par SMS.

Si un utilisateur final répond à un SMS configuré de cette manière, il est redirigé vers le menu de la file d'attente SMS à laquelle le numéro de téléphone SMS entrant est attribué. Pour en savoir plus , consultez Paramètres de chat par SMS – Numéro de téléphone.

Opérations d'API

Cette section décrit les opérations d'API, les paramètres de corps et les codes de réponse.

Corps et paramètres

Les champs suivants doivent être inclus dans le corps de la requête d'API :

Nom du champ Type Obligatoire Description Valeurs Remarques
agent_id Integer Non L'agent correspondant à cet ID sera attribué à un nouveau chat si aucun chat n'existe entre les numéros fournis. Si l'agent est connecté à un chat existant, le message sera envoyé en son nom.
agent_email Chaîne Non Adresse e-mail de l'agent.
chat_type Chaîne Oui SMS SMSAP
chat_subtype Chaîne Oui api_initiated
end_user_number Chaîne Oui Numéro auquel le SMS doit être envoyé Validation : numéro de téléphone valide : +18882468888 pour un numéro de téléphone américain
outbound_number Chaîne Oui Numéro de téléphone sortant à utiliser pour envoyer le SMS Validation : a) le numéro de téléphone doit être un numéro de téléphone SMS associé au locataire ; b) le numéro de téléphone est manquant ; c) le format du numéro de téléphone est incorrect : +18882468888 pour un numéro de téléphone américain
message Chaîne Oui SMS à envoyer au client Messages longs : divisez les longs messages en plusieurs messages (cela devrait être couvert par la fonctionnalité SMS sortants existante) Validation : a) le message est manquant ; b) le message dépasse le nombre maximal de caractères (de x)
ticket_id id Non Associera la session à un ID de demande CRM spécifique Remarque : Les ID de demande non valides seront ignorés.

Erreur et réussite

Cas Résultat attendu Copier
Le service SMS est activé.
Le service SMS sortants est activé.
La valeur de chat_type est "OutboundSMSAPI".
end_user_number est fourni et bien formé.
outbound_number est fourni et bien formé.
Pour les numéros de téléphone non américains : le numéro de téléphone non américain est activé.
Le message est fourni.
Aucun chat actif entre outbound_number et end_user_number		 success Exemple de réponse indiquant une réussite
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
L'ID de l'agent et l'adresse e-mail de l'agent sont fournis. erreur Vous ne pouvez fournir qu'un seul élément : agent_id ou agent_email.
L'ID de l'agent ou l'adresse e-mail de l'agent est fourni.
L'agent n'est pas connecté à un chat existant.		 erreur Échec de l'envoi du SMS sortant. L'agent n'est pas connecté au chat.
Le service SMS n'est pas activé. erreur "Le service SMS n'est pas activé."
Le service SMS sortants n'est pas activé. erreur "Le service SMS sortants n'est pas activé."
chat_type n'est pas fourni. erreur "Vous devez fournir chat_type."
chat_type est fourni, mais n'est pas défini sur "sms". erreur "Vous devez fournir un chat_type valide."
end_user_number est fourni, mais n'est pas bien formé. erreur "end_user_number n'est pas valide"
(Remarque : Numéro de téléphone valide : "+18882468888" pour un numéro de téléphone américain)
end_user_number n'est pas fourni. erreur "Vous devez fournir end_user_number."
outbound_number est fourni, mais n'est pas bien formé. erreur "outbound_number n'est pas valide"
(Remarque : Numéro de téléphone valide : "+18882468888" pour un numéro de téléphone américain)
outbound_number est fourni, mais n'existe pas pour ce locataire. erreur "outbound_number est introuvable."
outbound_number n'est pas fourni. erreur "Vous devez fournir outbound_number."
outbound_number est un numéro de téléphone non américain et le "service de numéro de téléphone non américain" n'est pas activé. erreur "Le service de numéro de téléphone non américain n'est pas activé"
Remarque : dépend du paramètre Non-US phone number (Numéro de téléphone non américain) dans Settings > In Call SMS > Non-US Phone Number Configurations (Paramètres > SMS en cours d’appel > Configurations de numéro de téléphone non américain)
Le message est vide. erreur "Vous devez fournir un message."
Chat actif entre outbound_number et end_user_number erreur "Échec de l'envoi du SMS sortant. Le client est déjà dans une session SMS active."
ticket_id est renseigné, mais n'existe pas dans le CRM. erreur "La demande est introuvable."

Expiration des SMS

Les SMS sortants sont actifs dès qu'ils sont envoyés.

Toute discussion par SMS doit se terminer avant qu'une nouvelle session de discussion par SMS puisse être établie entre un numéro de téléphone sortant et un numéro de téléphone client donnés. Cela inclut les SMS sortants envoyés à l'aide de l'API. Tout SMS sortant échouera s'il existe un chat actif entre les numéros de téléphone sortant et client.

Options de délai d'inactivité automatique du chat

Les options de délai d'inactivité automatique du chat sont configurées dans Settings > Chat > SMS Expiration & Global Timeout (Paramètres > Chat > Expiration des SMS et délai d'inactivité global). Cela permet de contrôler la durée pendant laquelle une session de chat reste active en l'absence d'activité ou de progression dans le flux de la session de chat.

Distinctions entre les états du chat

Voici les distinctions entre les changements d'état du processus de chat :

  • Expiration du chat à l'état de sélection de la file d'attenteLes chats sortants envoyés à l'aide de l' API sont considérés comme étant à l'état de sélection de la file d'attente jusqu'à ce que le client réponde.

    Toute session de chat qui n'a pas dépassé l'état de sélection de la file d'attente. Cela inclut les SMS sortants envoyés auxquels un client n'a pas répondu. Il est possible de définir la durée pendant laquelle un chat peut rester dans cet état avant d'expirer (message envoyé et client ne répondant pas dans le délai imparti – le chat expire).

  • Expiration du chat par SMS sans réponse (pendant les heures d'ouverture)La durée pendant laquelle un chat peut rester sans réponse dans une file d'attente avant d' expirer pendant les heures d'ouverture définies pour la file d'attente spécifique.

  • Expiration du chat par SMS sans réponse (en dehors des heures d'ouverture) : durée pendant laquelle un chat peut rester sans réponse dans une file d'attente avant d'expirer en dehors des heures d'ouverture définies pour la file d'attente spécifique.

  • Délai d'inactivité du chat par SMS sortants : les sessions de chat par SMS sortants expirent automatiquement s'il n'y a aucune activité pendant [x] minutes.

Détails sur l'état du chat

  • Lorsqu'un SMS sortant est envoyé à l'aide de l'API, le chat est considéré comme actif , mais pas connecté.

  • Ces chats par SMS sortants actifs sont considérés comme étant à l'état de sélection de la file d'attente jusqu'à ce que le client réponde.

  • Les chats sont considérés comme connectés une fois que le client a répondu et qu'un agent est attribué au chat.

Impact de l'état du chat sur les minuteurs appliqués

  • Les chats actifs envoyés à l'aide de l'API auxquels le client n'a pas répondu sont soumis au minuteur de l'état de sélection de la file d'attente.

  • Les chats connectés à un agent sont soumis au minuteur d'expiration des messages sortants.

  • Si un client répond au message initial, mais qu'aucun agent n'est attribué, le chat n'est pas connecté et est soumis au minuteur d'expiration du chat sans réponse, pendant ou après les heures d'ouverture.

Exemple de flux et d'états des messages d'API :

  1. Un SMS est envoyé au client à l'aide de l'API. Le chat est à l'état de sélection de la file d'attente et n'est pas connecté à un agent.

  2. Le minuteur d'expiration du chat à l'état de sélection de la file d'attente démarre. Le chat expire et se termine si le client ne répond pas dans le délai imparti.

  3. Le client répond au chat. Le chat est désormais connecté à un agent.

  4. Le client envoie le dernier message. Le minuteur de délai d'inactivité du chat par SMS sortants démarre.

  5. Le seuil du minuteur de délai d'inactivité du chat par SMS sortants est atteint. Le chat est terminé.

Aucun minuteur de fermeture du chat : pour les sessions de SMS sortants lancées par l'API, le minuteur de fermeture du chat ne fonctionne pas. Par conséquent, aucun événement de fermeture du chat ne se produit, même après que ce chat est arrivé en tant que chat entrant lorsqu'un client répond au message.

Définition de la réponse

L'API répond avec un seul objet d'appel, comme indiqué dans le modèle de /calls.

API SMS sortants sans session

CCAI Platform propose une API SMS sortants qui peut prendre en charge les SMS sortants sans aucune session associée.

Cet appel d'API lance des SMS non liés à une session qui peuvent être déclenchés lors d'un workflow existant à l'aide de CCAI Platform.

L'API sans session est préférable s'il n'est pas nécessaire d'envoyer plus d'un message aux clients et que l'ouverture d'une demande CRM n'est pas requise.

Cette API SMS sortants permet d'envoyer jusqu'à 500 messages par appel d'API.

Cas d'utilisation

Voici quelques cas d'utilisation courants pour un SMS sans session :

  • Configuration d'un mot de passe à usage unique

  • Code de validation

  • Rappels de rendez-vous

  • Liens vers les commentaires

  • Messages marketing ou promotionnels

L'API sortants sans session et l'API SMS sortants diffèrent en ce que avec l'API SMS sortants, lorsqu'un client répond, une session active est lancée et il peut être orienté vers un agent. Bien qu'elles partagent des cas d'utilisation similaires (notifications de livraison, rappels de rendez-vous), la différence réside dans ce qui se passe lorsque le client répond. Il peut recevoir une notification par défaut indiquant de ne pas répondre avec l'API sans session, mais avec l'API SMS sortants, il sera orienté vers un agent.

Point de terminaison de l'API SMS sortants sans session

L'URI de base de ce point de terminaison est la suivante :

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

Ajouter des identifiants d'API

  1. Dans le portail CCAI Platform, accédez à Settings (Paramètres) > Developer Settings (Paramètres du développeur) > API Credential management (Gestion des identifiants d'API).

  2. Cliquez sur le bouton + Add API Credential (+ Ajouter des identifiants d'API). Un message Add API Credential (Ajouter des identifiants d'API) s'ouvre.

  3. Saisissez un nom pour les identifiants dans le champ Name (Nom).

  4. Cliquez sur Create (Créer).

Envoi de messages SMS

Pour envoyer un SMS sortant sans session, appelez POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms et transmettez les paramètres de requête suivants :

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
Nom du champ Type Obligatoire Description Remarques
from_phone Chaîne Oui Numéro de téléphone à partir duquel les messages seront envoyés. Doit être un numéro américain valide.
L'appel d'API renvoie une erreur si :
* le numéro de téléphone n'est pas un numéro de téléphone SMS associé au locataire ;
* le champ from_phone est vide ;
* le format du numéro de téléphone n'est pas correct. Par exemple, le numéro suivant est un numéro de téléphone américain valide : +18882468888
to_phones Tableau [Chaîne] Oui Numéros de téléphone auxquels les messages seront envoyés. Pour vous assurer que l'appel d'API réussit :
* Vérifiez que vous disposez d'un numéro de téléphone valide, tel que +18882468888
Le nombre maximal de numéros de téléphone est de 100 par appel d'API.
messages Tableau [Chaîne] Oui Messages à envoyer. Le nombre maximal de messages distincts que vous pouvez envoyer est de 5.
Chaque message est limité à 320 caractères.

Réponses d'API

Si l'appel d'API réussit, vous verrez :

  • code: 200

  • Identifiant de la demande

    Assurez-vous de consigner l'identifiant de la demande dans les enregistrements de votre système. Si vous devez résoudre un problème, l'assistance aura besoin de l'identifiant de la demande pour vous aider.

Si l'appel d'API échoue, vous verrez :

  • code: 4xx

  • Message d'erreur

Limites concernant les SMS

  • L'API traite un maximum de 300 messages par minute.

  • Tous les messages non traités expireront dans deux heures.