API SMS

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

Authentification

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

Pour créer un identifiant 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 API).

  2. Cliquez sur le bouton + Ajouter un identifiant API. Le message Ajouter des identifiants d'API s'affiche.

  3. Saisissez un nom pour les identifiants.

  4. Cliquez sur 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 basés sur les événements.

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

  • Cette API ne fonctionnera 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 lorsqu'un SMS sortant est envoyé. Lorsque le client répond, il est redirigé vers un agent.

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

Autres cas d'utilisation potentiels :

  • 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'estimation du délai de livraison pour les services à la demande, comme les livraisons et le covoiturage.
  • Rappels de rendez-vous.
  • Alertes proactives concernant le service ou le compte.
  • Authentification à deux facteurs (le client doit disposer 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 le suivant :

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

Assistance par 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 pour les 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 des SMS à laquelle le numéro de téléphone des SMS entrants est attribué. Pour en savoir plus, consultez Paramètres de chat pour les messages 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 API :

Nom du champ Type Obligatoire Description Valeurs Remarques
agent_id Integer Non L'agent correspondant à cet ID sera attribué à une nouvelle discussion si aucune discussion n'existe entre les numéros fournis. Si l'agent est connecté à une discussion existante, 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 de téléphone auquel le message doit être envoyé Validation : numéro de téléphone valide : +18882468888 pour un numéro de téléphone aux États-Unis
outbound_number Chaîne Oui Numéro de téléphone sortant à utiliser pour envoyer le message SMS Validation : a) le numéro de téléphone doit être un numéro de téléphone SMS associé au locataire, b) numéro de téléphone manquant, c) le format du numéro de téléphone est incorrect : +18882468888 pour un numéro de téléphone aux États-Unis
message Chaîne Oui Message SMS à envoyer au client Messages longs : divisez les messages longs en plusieurs messages (cette fonctionnalité devrait être couverte par la fonctionnalité SMS sortants existante). Validation : a) message manquant, b) message dépassant le nombre maximal de caractères (de x)
ticket_id id Non Associera la session à un ID de demande CRM spécifique Remarque : Les numéros de ticket non valides seront ignorés.

Erreur et réussite

Cas Résultat attendu Copier
Le service SMS est activé
Le service SMS sortant est activé
La valeur 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
Aucune discussion active entre outbound_number et end_user_number		 success Exemple de réponse de réussite (200)
{ 
  "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 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 ou l'adresse e-mail de l'agent sont fournis
L'agent n'est pas connecté à la discussion existante		 erreur Échec de l'envoi du SMS. 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 d'envoi de SMS n'est pas activé erreur "Le service SMS sortants n'est pas activé"
chat_type n'est pas fourni erreur "chat_type needs to be provided" (Le type de chat doit être fourni)
chat_type est fourni, mais n'est pas défini sur "sms" erreur "Un chat_type valide doit être fourni"
end_user_number est fourni, mais n'est pas bien formé erreur "end_user_number is invalid"
(remarque : numéro de téléphone valide : "+18882468888" pour un numéro de téléphone aux États-Unis)
end_user_number n'est pas fourni erreur "end_user_number is required"
outbound_number est fourni, mais n'est pas bien formé erreur "outbound_number is invalid"
(remarque : numéro de téléphone valide : "+18882468888" pour un numéro de téléphone américain)
Le numéro sortant fourni n'existe pas pour ce locataire. erreur "outbound_number is not found"
outbound_number n'est pas fourni erreur "outbound_number is required" (outbound_number est obligatoire)
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 Numéro de téléphone non américain dans Paramètres > SMS en cours d'appel > Configurations de numéro de téléphone non américain
Le message est vide erreur "message is required" (message obligatoire)
Discussion active entre outbound_number et end_user_number erreur "Échec de l'envoi du SMS. Le consommateur est déjà dans une session SMS active."
ticket_id est renseigné, mais n'existe pas dans le CRM erreur "Titre de transport introuvable"

Expiration des SMS

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

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

Options de délai d'attente automatique du chat

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

Distinctions concernant la disponibilité

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

  • Expiration des chats à 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 consommateur 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 consommateur 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 consommateur ne répond pas dans le délai imparti : le chat expire).

  • Expiration des chats par SMS sans réponse (pendant les horaires d'ouverture) : durée pendant laquelle un chat peut rester sans réponse dans une file d'attente avant d'expirer pendant les horaires d'ouverture définis pour la file d'attente spécifique.

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

  • Délai avant expiration des chats par SMS sortants : les sessions de chat par SMS sortants expirent automatiquement en l'absence d'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 comme connecté.

  • Ces discussions SMS sortantes actives sont considérées comme étant dans l'état de sélection de la file d'attente jusqu'à ce que le client réponde.

  • Les discussions sont considérées comme connectées une fois que le client a répondu et qu'un agent a été attribué à la discussion.

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

  • Les discussions actives envoyées à l'aide de l'API et auxquelles le consommateur n'a pas répondu sont soumises au minuteur de sélection de l'état de la file d'attente.

  • Les discussions mises en relation avec un agent sont soumises au minuteur d'expiration du trafic sortant.

  • 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 des chats sans réponse, pendant ou après les heures d'ouverture.

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

  1. Un message SMS est envoyé au consommateur à l'aide de l'API. La discussion est dans l'état Sélection de la file d'attente et n'est pas connectée à un agent.

  2. Le minuteur d'expiration de la discussion démarre lorsque l'état de sélection de la file d'attente est défini. 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, qui est désormais connecté à un agent.

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

  5. Le seuil du minuteur de délai d'inactivité des chats par SMS sortants a été atteint. La discussion est terminée.

Pas de minuteur de fermeture du chat : pour les sessions SMS sortantes initiées par l'API, le minuteur de fermeture du chat ne fonctionne pas. Par conséquent, un événement de fermeture du chat ne se produit pas, même si le chat devient 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

La plate-forme CCAI propose une API SMS sortants qui peut gérer les messages SMS sortants sans aucune session associée.

Cet appel d'API lance des messages SMS non liés à une session qui peuvent être déclenchés pendant 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 dédiée aux SMS sortants permet d'envoyer jusqu'à 500 messages par appel d'API.

Cas d'utilisation

Voici quelques cas d'utilisation courants pour les 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 sortante sans session et l'API SMS sortante diffèrent en ce que, avec l'API SMS sortante, lorsqu'un consommateur répond, une session active est lancée et il peut être redirigé vers un agent. Bien qu'ils 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 consommateur répond. Il est possible qu'ils reçoivent une notification par défaut "Ne pas répondre" sans session, mais avec les SMS sortants, ils seront redirigés vers un agent.

Point de terminaison de l'API SMS sortants sans session

L'URI de base de ce point de terminaison est le suivant :

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

Ajouter un identifiant d'API

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

  2. Cliquez sur le bouton + Ajouter un identifiant API. Le message Ajouter des identifiants d'API s'affiche.

  3. Attribuez un nom à l'identifiant dans le champ Name (Nom).

  4. Cliquez sur Créer.

Envoyer des 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 renverra 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 numéro de téléphone ne respecte pas le format 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 que l'appel d'API aboutisse :
* Vérifiez que vous disposez d'un numéro de téléphone valide, par exemple +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. Vous pouvez envoyer jusqu'à cinq messages distincts.
Chaque message est limité à 320 caractères.

Réponses d'API

Si l'appel d'API aboutit, vous verrez le message suivant :

  • code : 200

  • Identifiant de la demande

    Assurez-vous d'enregistrer l'ID de la demande dans les journaux de votre système. Si vous avez besoin de résoudre un problème, l'assistance aura besoin de l'ID de la demande pour vous aider.

Si l'appel d'API échoue, le message suivant s'affiche :

  • 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.