Référence API

SMS

Les messages que vos agents peuvent envoyer pendant un appel, et l'opérateur qui les envoie. Aucune des deux moitiés ne suffit seule : un expéditeur sans messages n'envoie rien, et des messages sans expéditeur ne sont jamais proposés à un agent. Un agent ne rédige jamais son propre texte. Il choisit un message que vous avez écrit et remplit ses {trous}.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 12
Portées: messaging_accounts:readmessaging_accounts:writesms_messages:readsms_messages:write

GET/messaging-accounts/providers

Les opérateurs que ce déploiement sait lier.

Lister les opérateurs disponibles

Lisez cette liste plutôt que de la coder en dur. Twilio en est volontairement absent, parce qu'il ne se relie pas ici du tout : un client Twilio détient déjà le compte qui répond à ses appels, il désigne donc lequel de ses numéros envoie les textos avec PATCH /phone-numbers/{id} et sms_sender=true, et l'ouvre aux textos entrants avec sms_inbound=true. Envoyer provider: "twilio" à cet endpoint est refusé. Ne reliez un compte ici que pour un opérateur où l'expéditeur est un nom déposé plutôt qu'un de vos numéros.

POST/messaging-accounts

Vos propres identifiants, vérifiés avant d'être stockés.

Lier un compte opérateur

Pour les opérateurs où l'expéditeur est un nom déposé plutôt qu'un numéro, comme circulent les SMS d'entreprise dans une grande partie de l'Afrique de l'Ouest. L'identifiant est vérifié chez l'opérateur avant d'être enregistré, chiffré au repos, et jamais renvoyé par aucun endpoint. Un seul compte actif par client, et il a priorité sur un numéro Twilio désigné : ce qui envoie vos SMS ne doit pas dépendre de la ligne qu'une requête a renvoyée en premier. Déliez-le pour revenir en arrière. Si l'opérateur peut aussi recevoir sur ce compte (un shortcode Africa's Talking), la réponse contient une seule fois inbound_callback_url : collez-la dans le dashboard de l'opérateur. Elle n'est plus jamais affichée ; POST /messaging-accounts/:id/inbound-callback en émet une nouvelle.

Corps de la requête

providerstringrequis
Une des valeurs de GET /messaging-accounts/providers.
usernamestringrequis
Votre nom de compte chez l'opérateur. Pour Africa's Talking, votre username.
api_keystringrequis
Votre clé API opérateur. En écriture seule ; aucune réponse ne la contient jamais.
senderstringrequis
De qui le message semble venir : un nom d'expéditeur déposé comme ACME, ou un numéro. Il doit déjà être déposé chez l'opérateur ; rien ici ne peut le vérifier, donc un nom non déposé se manifeste par un refus au premier envoi.
labelstringoptionnel
Votre propre note. Texte d'affichage uniquement.

Erreurs

422Identifiant refusé, ou compte incapable d'envoyer

L'opérateur a refusé le username et la clé, le compte n'a pas de crédit, ou c'est un compte de test sur un déploiement de production.

Vérifiez que les deux moitiés de l'identifiant viennent du même compte opérateur, et qu'il a du crédit. Un compte sandbox est refusé en production à dessein : il accepte tous les messages et n'en délivre aucun, donc un agent promettrait un SMS qui n'arrive jamais.

409Un compte est déjà lié

Ce client a déjà un compte de messagerie actif. Ou un autre tenant a déjà lié ce compte opérateur : une app Africa's Talking livre ses SMS entrants à une seule URL de callback, elle appartient donc à un seul tenant.

Libérez d'abord l'existant, puis liez le nouveau.

429Trop de tentatives

La liaison est limitée par client ; chaque tentative appelle l'opérateur.

Attendez la fenêtre indiquée dans Retry-After.

503Opérateur injoignable

L'opérateur n'a pas répondu, ou la clé de chiffrement du serveur n'est pas configurée.

Réessayez. Ne pas savoir si un identifiant est valide est une raison de réessayer, pas de le déclarer mauvais.

Requête

json

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": "provident_gh",
    "api_key": "atsk_...your-carrier-api-key",
    "sender": "ACME",
    "label": "Provident Ghana"
  }'

201 Réponse

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "africastalking",
  "sender": "ACME",
  "label": "Provident Ghana",
  "status": "active",
  "created_at": "2026-08-28T12:00:00Z",
  "updated_at": "2026-08-28T12:00:00Z",
  "inbound_callback_url": "/africastalking/sms/MU5-Qidcvd...one-time-token"
}

GET/messaging-accounts

Ce qui est lié, sans aucune moitié de l'identifiant.

Lister les comptes opérateurs liés

Inclut les comptes libérés, pour voir ce qu'un client utilisait avant. Ni le username ni la clé API ne sont renvoyés : chacun est une moitié d'identifiant fonctionnel, et en renvoyer un transformerait un scope de lecture en presque un scope d'écriture.

Chemin & Requête

limitintegeroptionnel
Nombre de lignes à renvoyer. De 1 à 200, 50 par défaut.
offsetintegeroptionnel
Nombre de lignes à ignorer avant la première renvoyée. 0 par défaut.

Requête

json

curl https://api.aethexai.com/api/v1/messaging-accounts \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider": "africastalking",
      "sender": "ACME",
      "label": "Provident Ghana",
      "status": "active",
      "created_at": "2026-08-28T12:00:00Z",
      "updated_at": "2026-08-28T12:00:00Z",
      "inbound_callback_url": null
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/messaging-accounts/:id

Un compte lié, sans sa clé.

Lire un compte opérateur

Renvoie le compte tel que la liste le montre : opérateur, nom d'expéditeur, identifiant et statut. La clé API n'est jamais renvoyée, ni par cette route ni par une autre.

Chemin & Requête

idstringrequis
Le compte à lire.

Erreurs

404Introuvable

Aucun compte avec cet id sur votre tenant, ou il a été libéré.

Listez vos comptes ; un compte libéré ne revient pas, liez-en un nouveau.

Requête

json

curl https://api.aethexai.com/api/v1/messaging-accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "africastalking",
  "sender": "ACME",
  "label": "Provident Ghana",
  "status": "active",
  "created_at": "2026-08-28T12:00:00Z",
  "updated_at": "2026-08-28T12:00:00Z"
}

POST/messaging-accounts/:id/inbound-callback

Où l'opérateur poste les SMS envoyés à vos shortcodes ; l'URL précédente cesse de fonctionner.

Émettre une nouvelle URL de callback entrant

Africa's Talking ne signe pas ses callbacks : c'est l'URL elle-même qui prouve à quel compte un message est destiné, grâce à un jeton que seul votre compte reconnaît. Le jeton est stocké sous forme d'empreinte, comme une clé API : il est affiché une fois, ici et à la liaison du compte, puis plus jamais. Quand le déploiement publie un hôte pour les webhooks opérateur, le champ est une URL absolue ; sinon il ne porte que le chemin, à faire précéder de cet hôte. Collez-le dans le dashboard Africa's Talking, rubrique SMS, Callback URLs, Incoming Messages. Rappeler cette route révoque immédiatement l'URL précédente, c'est ainsi qu'on reprend une URL qui a fui. Libérer le compte la révoque aussi.

Chemin & Requête

idstringrequis
Le compte pour lequel émettre l'URL.

Erreurs

404Compte de messagerie introuvable

Aucun compte de ce type sur votre tenant.

Utilisez un ID renvoyé par GET /messaging-accounts.

409Compte libéré

Un compte libéré n'a plus d'identifiant pour répondre, il ne peut donc pas recevoir.

Liez un compte actif et enregistrez vos shortcodes dessus.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/messaging-accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/inbound-callback \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "africastalking",
  "sender": "ACME",
  "label": "Provident Ghana",
  "status": "active",
  "created_at": "2026-08-28T12:00:00Z",
  "updated_at": "2026-09-09T12:00:00Z",
  "inbound_callback_url": "/africastalking/sms/7kQ2...new-one-time-token"
}

DELETE/messaging-accounts/:id

Cesser d'envoyer par lui, et effacer la clé stockée.

Libérer un compte opérateur

Idempotent : 204 dans tous les cas. La clé API stockée est écrasée, pas seulement marquée inutilisée. Les appels en cours gardent l'identifiant résolu avant leur démarrage ; l'appel suivant retombe sur un numéro Twilio désigné s'il y en a un, sinon n'envoie rien. Tout shortcode qui répondait sur ce compte cesse de répondre (sms_inbound désactivé) : son URL de callback est morte, l'état affiché est donc l'état réel. Reliez, déplacez le shortcode avec PATCH /phone-numbers/:id, puis réactivez.

Chemin & Requête

idstringrequis
Le compte à libérer.

POST/sms-messages

Un message que vos agents peuvent envoyer, avec des trous à remplir.

Écrire un message

L'agent choisit quel message, jamais ce qu'il dit. Placez des {trous} là où une valeur doit aller et l'agent les remplit pendant l'appel ; les trous sont analysés à partir du corps, jamais stockés, donc un corps modifié ne peut pas contredire ce qu'on demande à l'agent. Nommez-le dans le prompt de votre agent pour lui dire quand envoyer lequel. Jusqu'à 25 messages actifs par client.

Corps de la requête

namestringrequis
Le nom utilisé dans votre prompt : minuscules, chiffres et tirets bas, commençant par une lettre. Il ne peut pas être changé, car le renommer casserait tous les prompts qui le nomment.
bodystringrequis
Le texte, jusqu'à 480 caractères, avec des {trous} pour les valeurs que l'agent remplit. Il doit dire quelque chose par lui-même : un corps réduit à un seul trou serait du texte libre sous votre identité d'expéditeur, précisément ce que cette conception empêche.
labelstringrequis
À quoi sert ce message, dans vos mots. Obligatoire : l'agent le lit pour décider quel message envoyer, alors dites ce qu'il fait et quand. Jamais envoyé au destinataire.

Erreurs

422Message mal formé

Le nom ne respecte pas le motif, le corps est vide ou dépasse 480 caractères, ses accolades sont déséquilibrées, ou il n'a aucun contenu propre.

Corrigez le champ nommé dans la réponse et renvoyez.

409Nom déjà pris, ou trop de messages

Un message actif porte déjà ce nom, ou le client est à 25 messages actifs.

Choisissez un autre nom, ou retirez un message que vous n'envoyez plus.

Requête

json

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_link",
    "body": "Here is your booking link: {link}",
    "label": "Sent when we could not take an email"
  }'

201 Réponse

json

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "booking_link",
  "label": "Sent when we could not take an email",
  "body": "Here is your booking link: {link}",
  "placeholders": ["link"],
  "status": "active",
  "created_at": "2026-08-28T12:00:00Z",
  "updated_at": "2026-08-28T12:00:00Z"
}

GET/sms-messages

Tous les messages du client, avec leurs trous analysés.

Lister les messages

Inclut les messages retirés, pour voir à quoi se référait un ancien prompt. placeholders est dérivé du corps à chaque lecture, donc c'est toujours ce qu'on demanderait réellement à un agent de fournir.

Chemin & Requête

statusstringoptionnel
Ne renvoie que les messages ayant ce statut : active ou retired.
limitintegeroptionnel
Nombre de lignes à renvoyer. De 1 à 200, 50 par défaut.
offsetintegeroptionnel
Nombre de lignes à ignorer avant la première renvoyée. 0 par défaut.

Requête

json

curl "https://api.aethexai.com/api/v1/sms-messages?limit=50" \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "booking_link",
      "label": "Sent when we could not take an email",
      "body": "Here is your booking link: {link}",
      "placeholders": ["link"],
      "status": "active"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/sms-messages/:id

Un modèle de message, avec ses trous.

Lire un message

Renvoie le modèle tel qu'il a été écrit, plus les trous extraits de son corps, dans la forme que la liste renvoie.

Chemin & Requête

idstringrequis
Le message à lire.

Erreurs

404Introuvable

Aucun message avec cet id sur votre tenant, ou il a été supprimé.

Listez vos messages pour retrouver le bon id.

Requête

json

curl https://api.aethexai.com/api/v1/sms-messages/b2c3d4e5-f6a7-8901-bcde-f23456789012 \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "booking_link",
  "body": "Your appointment link: {link}",
  "placeholders": ["link"],
  "status": "active"
}

PATCH/sms-messages/:id

Changer le texte ; le nom est fixe.

Modifier un message

name n'est volontairement pas accepté. Le prompt de votre agent désigne un message par son nom, donc le renommer casserait en silence tous les prompts qui le nomment. Retirez le message et écrivez son remplaçant. Changer le corps réanalyse les trous : en retirer un cesse de le demander à l'agent.

Chemin & Requête

idstringrequis
Le message à modifier.

Corps de la requête

bodystringoptionnel
Le nouveau texte, mêmes règles qu'à l'écriture.
labelstringoptionnel
La nouvelle description. Ne peut pas être vidée — c'est ce sur quoi l'agent choisit.

Erreurs

422Message mal formé

Le corps enfreint une des règles, ou vous avez tenté de changer le nom.

Corrigez le champ nommé dans la réponse, ou retirez et recréez pour renommer.

Requête

json

curl -X PATCH https://api.aethexai.com/api/v1/sms-messages/b2c3d4e5-f6a7-8901-bcde-f23456789012 \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Your appointment link: {link}"}'

Réponse 200

json

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "booking_link",
  "body": "Your appointment link: {link}",
  "placeholders": ["link"],
  "status": "active"
}

POST/sms-messages/:id/test

Un vrai message vers un numéro que vous choisissez, sans passer d'appel.

Envoyer un message maintenant, en test

Il exécute le même chemin qu'un appel : même résolution de l'expéditeur, même remplissage des trous, même plafond de longueur, même opérateur. Un message qui arrive ici arrivera donc en appel, ce qu'une implémentation de test séparée ne pourrait jamais promettre. L'envoi est réel et coûte réellement : cinq par heure et par client. La réponse contient le texte réellement parti, parce que c'est tout l'intérêt d'un test.

Chemin & Requête

idstringrequis
Le message à envoyer.

Corps de la requête

tostringrequis
Où l'envoyer, en E.164. Votre propre mobile, pour un test.
valuesobjectoptionnel
Une valeur par trou du corps, 120 caractères maximum chacune.
agent_idstringoptionnel
Résout l'expéditeur comme le ferait un appel de cet agent : le numéro depuis lequel il envoie ses textos, à défaut l'expéditeur par défaut du compte. Omettez-le pour tester le défaut seul. 404 si l'agent n'est pas le vôtre.

Erreurs

409Aucun expéditeur

Ce client n'a aucun expéditeur fonctionnel : aucun désigné, aucun lié, ou l'identifiant stocké est illisible.

Désignez un numéro Twilio ou liez un compte opérateur, puis réessayez. Dans cet état, un appel ne proposerait simplement pas d'envoyer de SMS.

422Refusé avant ou par l'opérateur

Un trou n'a pas de valeur, le message rempli dépasse 480 caractères, ou l'opérateur l'a refusé : un expéditeur qu'il ne reconnaît pas, un numéro incapable de recevoir des SMS, ou un destinataire désabonné.

La réponse dit lequel. Un refus de l'opérateur signifie que rien n'a été délivré, donc rien n'a été facturé.

429Trop d'envois de test

Cinq par heure et par client. Cet endpoint sert à vérifier un message.

Attendez la fenêtre indiquée dans Retry-After.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/sms-messages/b2c3d4e5-f6a7-8901-bcde-f23456789012/test \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233201234567",
    "values": { "link": "https://cal.example.com/x7f2" }
  }'

Réponse 200

json

{
  "sent": true,
  "sender": "ACME",
  "body": "Here is your booking link: https://cal.example.com/x7f2"
}

DELETE/sms-messages/:id

Le sortir de la circulation et libérer son nom.

Retirer un message

Le message cesse d'être proposé à tout agent. Son nom redevient disponible, donc un remplaçant peut le reprendre : c'est ainsi qu'on renomme.

Chemin & Requête

idstringrequis
Le message à retirer.

Erreurs

409Le message est dans la liste d'un agent

Un agent a ce message dans ses sms_message_ids. Le supprimer viderait la sélection de cet agent, ce qui se lit « tous les messages actifs » — élargissant la liste au lieu de la réduire.

Retirez-le des agents qui le nomment, ou mettez-le hors service (PATCH avec status: "retired") : un message hors service cesse d'être envoyable et reste dans les listes qui le nomment.

Requête

json

curl -X DELETE https://api.aethexai.com/api/v1/sms-messages/b2c3d4e5-f6a7-8901-bcde-f23456789012 \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{ "success": true, "message": "Message deleted." }