SMS
Vos agents envoient un SMS à la personne en ligne, répondent aux messages qui reviennent et déroulent des campagnes, le tout via un compte Twilio ou Africa's Talking qui vous appartient.
Vue d'ensemble
Le canal SMS repose sur un compte opérateur qui vous appartient. Aethex n'est jamais l'expéditeur : chaque message part sous un numéro ou un nom enregistré qui est le vôtre, et l'opérateur vous facture le trafic directement.Quatre choses produisent un SMS, et toutes suivent les mêmes règles : les mêmes expéditeurs, la même liste de désinscriptions, les mêmes verdicts de l'opérateur.- Un agent, pendant un appel. L'agent choisit un de vos messages enregistrés et en remplit les trous, pour que l'appelant reçoive un lien de réservation ou une confirmation sans quitter la ligne. Le message est déposé sur le fil de ce client, si bien que la personne qui reprend la conversation ensuite voit ce qui a été envoyé.
- Un agent, dans une conversation par SMS. Quelqu'un écrit à un numéro qui répond, et l'agent répond à partir de l'historique de ce fil.
- Votre équipe, depuis la boîte de réception. Du texte libre, écrit par une personne, sur un fil qui existe déjà.
- Une campagne. Un corps de message avec des trous remplis destinataire par destinataire, envoyé le long d'une liste au rythme que vous fixez.Tout ce qu'un client donné envoie ou reçoit sur l'une de vos lignes se retrouve sur un seul fil, que lisent la boîte de réception et l'API des conversations SMS.
Twilio et Africa's Talking
Deux opérateurs peuvent porter le canal, et ils diffèrent sur ce qu'est une identité d'expéditeur.Twilio. Il n'y a rien à lier deux fois : le compte Twilio que vous avez enregistré pour la voix envoie aussi vos SMS. Vous indiquez seulement lequel de vos numéros peut émettre, et lequel répond. Twilio est interrogé à cet instant pour savoir si le numéro sait réellement porter des SMS, si bien qu'une ligne achetée pour la voix est refusée d'emblée plutôt que d'échouer plus tard sur le réseau.Africa's Talking. L'identité voyage sur les identifiants, pas sur un numéro. Vous liez un compte de messagerie (identifiant, clé API, expéditeur enregistré) et les messages partent sous cet expéditeur. Il en existe deux sortes : un nom d'expéditeur alphanumérique comme ACME, uniquement sortant puisqu'on ne peut pas répondre à un nom, et un code court, qui sait aussi recevoir. Enregistrez ce code court comme l'un de vos numéros, pointez-le vers un agent, et collez l'URL de rappel dans le tableau de bord de votre opérateur. Cette URL vous est remise une seule fois, à la liaison du compte ou lorsque vous en demandez une nouvelle, et n'est plus jamais affichée ; là où le déploiement n'a pas d'hôte de webhook propre, elle revient sous forme de chemin, à préfixer de votre propre hôte. Un code court est unique à l'échelle de la plateforme et le premier enregistrement l'emporte, donc enregistrez le vôtre avant de le communiquer.Un compte peut détenir les deux. Ce qu'un appel donné utilise est tranché par l'ordre décrit à la section suivante, jamais par ce qui a été configuré en premier.
| Ce qui change | Twilio | Africa's Talking |
|---|---|---|
| Ce que vous liez | Rien de plus : le compte déjà enregistré pour la voix. | Un compte de messagerie : identifiant, clé API, expéditeur enregistré. |
| Ce que voit le destinataire | L'un de vos numéros de téléphone. | Votre nom d'expéditeur enregistré, ou votre code court. |
| Peut-il recevoir des réponses | Oui, sur tout numéro à qui vous accordez le rôle de réponse. | Un code court, oui. Un nom d'expéditeur alphanumérique, non. |
| Où cela se configure | PATCH /phone-numbers/{id} | POST /messaging-accounts, puis POST /phone-numbers/africastalking/register |
curl -X POST https://api.aethexai.com/api/v1/messaging-accounts \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "africastalking",
"username": "your_at_username",
"api_key": "<carrier API key>",
"sender": "ACME",
"label": "Acme Ghana"
}'
# The response carries inbound_callback_url once, and never again.
# Paste it into Africa's Talking: SMS -> Callback URLs -> Incoming Messages.
# If it comes back as a path rather than a full URL, put your own host in front.Sous quel expéditeur part un message
Émettre repose sur deux faits distincts, et il vaut la peine de les garder séparés.L'autorisation, sms_sender sur un numéro, signifie *cette ligne a le droit d'émettre*. Plusieurs de vos numéros peuvent la porter, et l'avis de l'opérateur sur chacun est vérifié au moment où vous l'accordez.Le défaut, sms_sender_default, signifie *c'est la ligne de repli*. Un seul numéro par compte le détient, et ce doit être l'un des numéros qui émettent. Le premier numéro que vous autorisez à émettre le devient, faute de choix à faire ; en autoriser un second laisse le défaut où il est, car c'est à vous de décider quelle ligne il doit être.Par-dessus, un agent peut nommer la ligne depuis laquelle il écrit : sms_sender_number_id, validé à l'écriture, pour qu'un agent commercial écrive depuis la ligne commerciale quel que soit le défaut du compte.Au moment de l'appel, les trois candidats sont lus dans un ordre fixe, du plus spécifique au plus général. Un numéro libéré ou retiré après avoir été nommé par un agent bascule sur le candidat suivant plutôt que d'entraîner tout le compte avec lui. Si rien ne se résout, l'appel ne peut simplement pas envoyer de SMS, et les outils correspondants ne sont pas proposés à l'agent.Retirer l'autorisation à une ligne est accepté et non refusé, puisque détenir plusieurs expéditeurs est précisément l'intérêt de cette autorisation. Les agents qui la nommaient continuent d'écrire, depuis le défaut du compte, ce qui change l'expéditeur affiché sur le téléphone du destinataire : quand une modification retire l'autorisation à une ligne qu'un agent nomme encore, la réponse indique combien d'agents ont basculé, dans agents_now_on_default.
# Several numbers may carry the sending role. Exactly one is the default.
curl -X PATCH https://api.aethexai.com/api/v1/phone-numbers/<SALES_NUMBER_ID> \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sms_sender": true, "sms_inbound": true}'Recevoir : fils, STOP et transfert
Un numéro répond aux SMS dès que vous lui accordez le rôle de réponse (sms_inbound) et que vous y liez un agent. L'accorder ne touche pas à l'acheminement des appels : une ligne dont les appels passent par votre propre trunk SIP, ou par ailleurs, peut tout de même répondre aux SMS, et les appels restent exactement là où vous les avez dirigés. La réponse le dit d'ailleurs dans calls_routed_elsewhere, en nommant ce qui les porte encore, pour qu'on ne prenne jamais la liaison d'un agent pour un rapatriement des appels.Chaque message entrant franchit trois portes avant qu'un agent ne rédige quoi que ce soit.STOP passe en premier, avant tout autre sens que le message pourrait avoir. STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, ARRET et ARRÊT désinscrivent la personne ; START et UNSTOP la réinscrivent. Elle en est informée une fois, et le message nomme START pour que le chemin du retour ne soit jamais une devinette. Une désinscription vaut pour tout votre compte, pas seulement pour la ligne à laquelle elle a écrit, et elle est relue juste avant chaque envoi, y compris un SMS qu'un agent s'apprête à envoyer en pleine conversation téléphonique.Une demande de parler à quelqu'un (*parler à un humain*, *une vraie personne*, *un conseiller*) enregistre le message, répond une fois, et suspend les réponses de l'agent jusqu'à ce qu'une personne lui rende le fil. Le webhook de l'agent reçoit sms.handoff.requested : personne n'a besoin de surveiller la boîte de réception.Un fil basculé en mode `human` appartient à votre équipe, et l'agent y reste silencieux.Passé ces trois portes, l'agent répond à partir de l'historique du fil, dans une fenêtre de 24 heures. Un fil auquel on a répondu 20 fois en 10 minutes part vers une personne plutôt que de repartir pour un tour, avec le même sms.handoff.requested : quand l'autre bout est lui aussi automatique, aucun des deux n'a de raison de s'arrêter.
La bibliothèque de messages
Un agent ne rédige jamais un SMS. Vous écrivez les messages ; l'agent en choisit un par son nom et en remplit les trous. Un modèle libre d'écrire son propre texte serait une passerelle d'envoi sous votre identité d'expéditeur, pilotable par qui se trouve au bout du fil.Un message, c'est un nom, un corps de 480 caractères au plus, et des {trous} que l'agent remplit avec des valeurs de 120 caractères au plus chacune. Vous pouvez détenir 25 messages actifs à la fois, pour tout le compte et non par agent : chaque message actif est décrit à l'agent au démarrage de l'appel, si bien que le plafond borne ce qu'un agent peut utilement garder en tête, pas ce que nous savons stocker. Retirer un message avec PATCH /sms-messages/{id} libère une place tout en le laissant consultable, pour qu'un SMS envoyé l'an dernier garde son sens dans le fil. Le renommage est délibérément absent : un prompt désigne un message par son nom, donc retirez et recréez plutôt.Deux outils intégrés puisent dans la bibliothèque pendant un appel. send_message envoie l'un de vos messages. send_booking_link envoie un lien de prise de rendez-vous à usage unique, qui existe pour la seule chose qu'un agent vocal ne sait pas faire de façon fiable : noter une adresse e-mail dictée au téléphone. Les deux partagent une même enveloppe de 30 SMS par appel, un même message part au plus deux fois dans un appel par défaut (sms_max_sends_per_message sur l'agent le modifie, jusqu'à 30), et chaque envoi relit d'abord la liste de désinscriptions.POST /sms-messages/{id}/test envoie un message enregistré sur votre propre téléphone pour en vérifier la formulation. Cinq par heure, et sans ouvrir de fil, délibérément : vérifier votre propre texte ne doit pas faire de vous le client de quelqu'un.
curl -X POST https://api.aethexai.com/api/v1/sms-messages \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "booking_confirmation",
"body": "Hi {first_name}, your appointment is confirmed for {time}. Reply STOP to opt out.",
"label": "Booking confirmation"
}'Campagnes
Une campagne, c'est un corps de message, une liste de destinataires portant chacun ses valeurs, et un rythme. Créez-la et lancez-la à la main, ou donnez-lui un scheduled_at et laissez-la démarrer seule.Deux points sont vérifiés à la création, plutôt que découverts lentement destinataire après destinataire : le numéro doit pouvoir émettre, et il doit pouvoir répondre, car quelqu'un qui répond STOP doit bien atteindre quelqu'un. Passez acknowledge_no_replies: true pour renoncer au second en connaissance de cause.Les destinataires passent par pending → sending → sent | failed | skipped, et la liste de désinscriptions est relue pour chacun. Une campagne ne finit en failed que pour une raison définitive ; tout ce que vous pouvez corriger la met en pause et en inscrit la raison sur la campagne.sent signifie que l'opérateur a accepté le message, pas qu'il est arrivé. Chaque destinataire porte l'identifiant de message de l'opérateur lui-même, celui que vous citez dans la console de votre opérateur quand il faut en retracer un.
curl -X POST https://api.aethexai.com/api/v1/sms-campaigns \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number_id": "<SENDING_NUMBER_ID>",
"name": "September reminder",
"body": "Hi {first_name}, your appointment is at {time}.",
"recipients": [
{"to": "+233201234567", "values": {"first_name": "Ama", "time": "3pm"}}
],
"rate_per_minute": 60
}'Limites
Tout ce que le canal borne, au même endroit.
| Quoi | Valeur | S'applique à |
|---|---|---|
| Corps d'un message enregistré | 480 | Caractères, revérifiés une fois les trous remplis. Même plafond pour le corps d'une campagne. |
| Une valeur remplie | 120 | Caractères, par trou rempli par l'agent. |
| Une réponse en texte libre | 1600 | Caractères, pour une réponse de votre équipe comme pour une réponse d'agent sur un fil. Au-delà, le texte est découpé en segments par l'opérateur. |
| SMS par appel | 30 | Un garde-fou plutôt qu'un budget : un même message part au plus deux fois dans un appel par défaut (sms_max_sends_per_message sur l'agent le modifie), et les deux outils partagent la même enveloppe. |
| Messages enregistrés actifs | 25 | Pour tout le compte, pas par agent. Retirer un message libère une place et le laisse consultable. |
| Envois de test | 5 / h | Par compte, sur POST /sms-messages/{id}/test. |
| Réponses d'agent par fil | 20 / 10 min | Au-delà, le fil part vers une personne plutôt que de repartir pour un tour. |
| Fenêtre de conversation | 24 h | Jusqu'où un agent remonte dans son propre fil pour répondre. |
| Rythme d'une campagne | 1-600 / min | Messages par minute, à votre main lors de la création. |
Ce qui n'est pas inclus
Nommé sans détour, parce que la plupart des questions sur ce canal se ramènent à l'un de ces points.- Aucun webhook vers votre système quand un client écrit. Il n'existe pas d'événement sms.received ; lisez plutôt les endpoints de la boîte de réception.
- Pas encore d'accusés de réception. L'identifiant de message de l'opérateur est conservé pour chaque envoi à l'initiative de l'entreprise, et c'est lui que vous collez dans la console de votre opérateur en attendant.
- Un agent n'écrit jamais son propre texte. C'est délibéré, et nous ne prévoyons pas de le changer.
- Un SMS qu'on vous envoie pendant un appel n'atteint pas cet appel. Il ouvre son propre fil, traité séparément, si bien qu'un appelant peut se retrouver à parler à deux choses à la fois.
- Les outils d'envoi ne se pilotent pas depuis n8n. Les deux noms sont refusés par le schéma de liaison.Votre opérateur vous facture le trafic sur votre propre compte. Les messages à l'initiative de l'entreprise envoyés via Aethex consomment en outre des crédits : voir Facturation.
Étapes suivantes
- API SMS : le compte opérateur et la bibliothèque de messages, champ par champ.
- API des conversations SMS : les fils, la boîte de réception et les campagnes.
- Numéros de téléphone : enregistrer les lignes auxquelles ces rôles sont accordés.
- Africa's Talking : lier cet opérateur, étape par étape.