Référence API

Conversations texte

Le côté client de vos numéros : chaque fil sur un numéro qui reçoit les textos, la reprise par une personne, et les campagnes. Un fil apparaît la première fois que quelqu'un vous écrit, il n'y a donc rien à créer. Les réponses partent du numéro auquel le client a écrit, jamais d'un autre des vôtres.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 15
Portées: sms_inbox:readsms_inbox:writesms_campaigns:readsms_campaigns:write

GET/sms-inbox/summary

Faut-il l'ouvrir, tout simplement.

Résumé de la boîte

Messages non lus, nombre de fils concernés, et combien de clients attendent une personne. Compté sur tous vos numéros.

GET/sms-inbox/threads

Vos clients, les plus récents d'abord.

Lister les fils

Un fil par client et par numéro. Filtrable par numéro, par statut ou par mode. « mode=human » est la file qu'une personne doit traiter.

Chemin & Requête

phone_number_iduuidoptionnel
Uniquement les fils ou les campagnes sur ce numéro à vous.
customerstringoptionnel
Uniquement les fils avec ce client, au format E.164 avec l'indicatif et le signe plus. Les espaces et la ponctuation sont ignorés. Un format national, un plus manquant ou une valeur vide renvoie 422 plutôt qu'une liste vide. Plusieurs fils peuvent revenir — un par numéro à vous sur lequel le client a échangé des messages — le plus récent d'abord.
statusstringoptionnel
open, closed ou opted_out.
modestringoptionnel
agent ou human. « human » est la file qu'une personne doit traiter.
offsetintegeroptionnel
Combien de lignes ignorer. 0 par défaut.
limitintegeroptionnel
Combien de lignes renvoyer. 50 par défaut, 200 au maximum.

Requête

json

curl 'https://api.aethexai.com/api/v1/sms-inbox/threads?customer=%2B12345678900' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [{
  "id": "thread-uuid",
  "phone_number_id": "number-uuid",
  "customer": "+233244123456",
  "status": "open",
  "mode": "agent",
  "assigned_to": null,
  "handoff_reason": null,
  "handoff_requested_at": null,
  "last_inbound_at": "2026-08-31T09:14:02Z",
  "last_outbound_at": "2026-08-31T09:14:09Z",
  "last_message_at": "2026-08-31T09:14:09Z",
  "last_message_preview": "Yes, 2pm works for me",
  "last_message_direction": "in",
  "unread_count": 1,
  "created_at": "2026-08-20T11:02:44Z",
  "updated_at": "2026-08-31T09:14:09Z"
}],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/sms-inbox/threads/:thread_id

L'état d'un client sur un de vos numéros.

Lire un fil

Statut, mode, compteur de non-lus, et la date du dernier message reçu. Le contenu des messages est sur la chronologie ci-dessous.

Erreurs

404Introuvable

Aucun fil avec cet identifiant sur votre compte.

Vérifiez l'identifiant, ou listez les fils pour le retrouver.

Requête

json

curl 'https://api.aethexai.com/api/v1/sms-inbox/threads/thread-uuid' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "thread-uuid",
  "phone_number_id": "number-uuid",
  "customer": "+233244123456",
  "status": "open",
  "mode": "agent",
  "assigned_to": null,
  "handoff_reason": null,
  "handoff_requested_at": null,
  "last_inbound_at": "2026-08-31T09:14:02Z",
  "last_outbound_at": "2026-08-31T09:14:09Z",
  "last_message_at": "2026-08-31T09:14:09Z",
  "last_message_preview": "Yes, 2pm works for me",
  "last_message_direction": "in",
  "unread_count": 1,
  "created_at": "2026-08-20T11:02:44Z",
  "updated_at": "2026-08-31T09:14:09Z"
}

GET/sms-inbox/threads/:thread_id/messages

Tout ce qui a été dit, du plus récent au plus ancien.

Chronologie d'un fil

Tous les échanges de ce client sur ce numéro, à travers toutes ses conversations. L'agent en ouvre une nouvelle après une longue interruption, et la chronologie couvre l'interruption. « author » vaut « agent », « system », ou l'opérateur qui a écrit. « delivery_status » vaut « failed » quand le carrier a refusé une réponse. Un message et la réponse écrite avec lui partagent le même « created_at » ; à horodatage égal, l'ordre de la liste fait foi, et la réponse vient donc en premier.

Chemin & Requête

offsetintegeroptionnel
Combien de lignes ignorer. 0 par défaut.
limitintegeroptionnel
Combien de lignes renvoyer. 50 par défaut, 200 au maximum.

Requête

json

curl 'https://api.aethexai.com/api/v1/sms-inbox/threads/thread-uuid/messages?limit=50' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [
    {
      "id": "turn-uuid-2",
      "conversation_id": "conversation-uuid",
      "role": "assistant",
      "text": "Perfect, you are booked for 2pm.",
      "author": "agent",
      "kind": "text",
      "delivery_status": "sent",
      "created_at": "2026-08-31T09:14:09Z"
    },
    {
      "id": "turn-uuid",
      "conversation_id": "conversation-uuid",
      "role": "user",
      "text": "Yes, 2pm works for me",
      "author": null,
      "kind": "text",
      "delivery_status": null,
      "created_at": "2026-08-31T09:14:09Z"
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 50
}

POST/sms-inbox/threads/:thread_id/read

Remettre son compteur à zéro.

Marquer un fil comme lu

Met le compteur de non-lus à zéro et horodate la lecture. Ne change pas qui répond.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-inbox/threads/thread-uuid/read' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "thread-uuid",
  "phone_number_id": "number-uuid",
  "customer": "+233244123456",
  "status": "open",
  "mode": "agent",
  "assigned_to": null,
  "handoff_reason": null,
  "handoff_requested_at": null,
  "last_inbound_at": "2026-08-31T09:14:02Z",
  "last_outbound_at": "2026-08-31T09:14:09Z",
  "last_message_at": "2026-08-31T09:14:09Z",
  "last_message_preview": "Yes, 2pm works for me",
  "last_message_direction": "in",
  "unread_count": 1,
  "created_at": "2026-08-20T11:02:44Z",
  "updated_at": "2026-08-31T09:14:09Z"
}

POST/sms-inbox/threads/:thread_id/mode

Basculer entre l'agent et un humain.

Passer un fil à une personne, ou le rendre

Tant qu'un fil est en « human », l'agent cesse de répondre, et les messages du client sont toujours enregistrés et comptés. Remettez « agent » quand c'est terminé. Un client qui demande une personne actionne lui-même cet interrupteur.

Corps de la requête

modestringrequis
« agent » ou « human ».
reasonstringoptionnel
Pourquoi le fil a été repris. Affiché dans le fil.
assigned_tostringoptionnel
À qui il appartient maintenant. Texte libre : un e-mail, un nom.

Erreurs

422Requête invalide

« mode » n'était ni « agent » ni « human ».

Envoyez l'une des deux valeurs.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-inbox/threads/thread-uuid/mode' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "human", "assigned_to": "[email protected]", "reason": "billing question"}'

Réponse 200

json

{
  "id": "thread-uuid",
  "phone_number_id": "number-uuid",
  "customer": "+233244123456",
  "status": "open",
  "mode": "agent",
  "assigned_to": null,
  "handoff_reason": null,
  "handoff_requested_at": null,
  "last_inbound_at": "2026-08-31T09:14:02Z",
  "last_outbound_at": "2026-08-31T09:14:09Z",
  "last_message_at": "2026-08-31T09:14:09Z",
  "last_message_preview": "Yes, 2pm works for me",
  "last_message_direction": "in",
  "unread_count": 1,
  "created_at": "2026-08-20T11:02:44Z",
  "updated_at": "2026-08-31T09:14:09Z"
}

PATCH/sms-inbox/threads/:thread_id

De la gestion, pas du routage.

Clôturer ou attribuer un fil

Clôturer relève de la gestion : le client rouvre le fil en écrivant à nouveau. « opted_out » n'est pas modifiable ici. C'est la décision du client, enregistrée quand il écrit STOP, et levée seulement quand il écrit START.

Corps de la requête

statusstringoptionnel
« open » ou « closed ».
assigned_tostringoptionnel
À qui appartient le fil. Envoyez null pour désattribuer.

Erreurs

409Conflit

Ce client s'est désinscrit, le fil ne peut donc pas être rouvert ici.

Rien à faire. Le fil se rouvre quand il écrit START.

Requête

json

curl -X PATCH 'https://api.aethexai.com/api/v1/sms-inbox/threads/thread-uuid' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"status": "closed"}'

Réponse 200

json

{
  "id": "thread-uuid",
  "phone_number_id": "number-uuid",
  "customer": "+233244123456",
  "status": "open",
  "mode": "agent",
  "assigned_to": null,
  "handoff_reason": null,
  "handoff_requested_at": null,
  "last_inbound_at": "2026-08-31T09:14:02Z",
  "last_outbound_at": "2026-08-31T09:14:09Z",
  "last_message_at": "2026-08-31T09:14:09Z",
  "last_message_preview": "Yes, 2pm works for me",
  "last_message_direction": "in",
  "unread_count": 1,
  "created_at": "2026-08-20T11:02:44Z",
  "updated_at": "2026-08-31T09:14:09Z"
}

POST/sms-inbox/threads/:thread_id/messages

Envoyer un message vous-même, depuis le numéro auquel il a écrit.

Répondre en tant que personne

Accepté pour livraison et inscrit dans le fil à votre nom. Ne bascule pas le fil en mode humain : dites une chose et laissez l'agent tourner, ou reprenez le fil d'abord avec le point de terminaison de mode. recorded: false signifie que le message est parti et que le client l'a reçu, mais que l'entrée n'a pas pu être écrite dans le fil ; message_id et conversation_id sont alors absents. Ce n'est jamais une raison de renvoyer.

Corps de la requête

bodystringrequis
Le texte à envoyer, tel quel. Jusqu'à 1600 caractères.
authorstringoptionnel
Qui répond. Affiché dans la chronologie ; « operator » par défaut.

Erreurs

409Conflit

Ce client s'est désinscrit de vos messages sur tous vos numéros.

Rien ne peut être envoyé jusqu'à ce qu'il écrive START. Joignez-le autrement.

422Requête invalide

« body » était vide.

Envoyez du texte.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-inbox/threads/thread-uuid/messages' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"body": "Your invoice is attached to the email we just sent.", "author": "[email protected]"}'

202 Réponse

json

{
  "message_id": "turn-uuid",
  "conversation_id": "conversation-uuid",
  "accepted_at": "2026-08-31T09:20:00Z",
  "recorded": true
}

POST/sms-campaigns

Un message pour une liste, cadencé, rien d'envoyé encore.

Créer une campagne

Créée en brouillon, ou « scheduled » si vous passez « scheduled_at ». Rien ne part avant le démarrage ou l'heure prévue. Tout ce qui peut être refusé l'est ici plutôt qu'un destinataire à la fois : une valeur manquante sur une ligne, un message trop long une fois rempli, un numéro incapable d'envoyer. Les destinataires désinscrits sont marqués « skipped » avant le départ, et revérifiés avant chaque envoi.

Corps de la requête

phone_number_iduuidrequis
Le numéro d'où elle part. Il doit recevoir les textos (sms_inbound), pour qu'un STOP d'un destinataire atteigne quelqu'un.
namestringrequis
Ce à quoi vous la reconnaîtrez.
bodystringrequis
Le message, avec des trous « {nom_en_minuscules} » remplis par destinataire. Jusqu'à 480 caractères une fois rempli.
recipientsarrayrequis
Jusqu'à 50 000 lignes « {to, values} ». « to » est en E.164 avec le plus ; espaces et tirets sont tolérés. Un numéro répété est conservé une seule fois.
rate_per_minuteintegeroptionnel
Messages par minute, de 1 à 600. 60 par défaut.
scheduled_atstringoptionnel
Quand démarrer. Laissez vide pour créer un brouillon et le démarrer à la main.
acknowledge_no_repliesbooleanoptionnel
Lancer la campagne même si ce numéro ne reçoit pas les textos. Un destinataire qui répond STOP n'atteindrait personne, et sur les marchés où l'opérateur ne filtre pas le STOP à votre place, sa demande n'atteint personne du tout. Ce choix est enregistré sur la campagne.
webhook_urlstringoptionnel
URL HTTPS qui reçoit un sms.campaign.paused signé si le worker arrête cette campagne de lui-même : numéro devenu inactif, compte expéditeur refusé par l'opérateur, cinq refus identiques d'affilée, compte sans crédit. Une pause que vous demandez n'est pas signalée. Nécessite le secret webhook de votre compte. Laissée vide, personne n'est prévenu.

Erreurs

409Conflit

Le numéro ne reçoit pas les messages texte.

Activez sms_inbound dessus, ou envoyez acknowledge_no_replies=true.

409Conflit

L'opérateur indique que ce numéro ne peut pas porter de messages texte, ou il est sur un compte partagé.

Utilisez un numéro SMS-capable sur votre propre compte. acknowledge_no_replies ne lève pas ce refus.

422Requête invalide

Une ligne n'a pas de valeur pour un trou du message, n'est pas en E.164, ou dépasse la longueur une fois rendue.

L'erreur nomme la ligne. Corrigez-la et renvoyez la liste.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-campaigns' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "number-uuid",
    "name": "Tomorrow'"'"'s appointments",
    "body": "Hello {name}, your appointment is tomorrow at {time}.",
    "recipients": [
      {"to": "+233244123456", "values": {"name": "Ama", "time": "14:00"}},
      {"to": "+233208887777", "values": {"name": "Kofi", "time": "15:30"}}
    ],
    "rate_per_minute": 60
  }'

201 Réponse

json

{
  "id": "campaign-uuid",
  "phone_number_id": "number-uuid",
  "name": "Tomorrow's appointments",
  "body": "Hello {name}, your appointment is tomorrow at {time}.",
  "placeholders": ["name", "time"],
  "status": "draft",
  "rate_per_minute": 60,
  "scheduled_at": null,
  "started_at": null,
  "completed_at": null,
  "total_count": 240,
  "sent_count": 0,
  "failed_count": 0,
  "skipped_count": 3,
  "replies_acknowledged_at": null,
  "created_by": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-08-31T09:00:00Z",
  "updated_at": "2026-08-31T09:00:00Z"
}

GET/sms-campaigns

Ce qui a tourné et ce qui tourne.

Lister les campagnes

Les plus récentes d'abord, avec les compteurs : envoyés, échoués, sautés. « skipped » désigne quelqu'un délibérément non contacté, presque toujours une désinscription.

Chemin & Requête

phone_number_iduuidoptionnel
Uniquement les fils ou les campagnes sur ce numéro à vous.
statusstringoptionnel
draft, scheduled, running, paused, completed, cancelled ou failed.
offsetintegeroptionnel
Combien de lignes ignorer. 0 par défaut.
limitintegeroptionnel
Combien de lignes renvoyer. 50 par défaut, 200 au maximum.

Requête

json

curl 'https://api.aethexai.com/api/v1/sms-campaigns?status=running' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [{
  "id": "campaign-uuid",
  "phone_number_id": "number-uuid",
  "name": "Tomorrow's appointments",
  "body": "Hello {name}, your appointment is tomorrow at {time}.",
  "placeholders": ["name", "time"],
  "status": "draft",
  "rate_per_minute": 60,
  "scheduled_at": null,
  "started_at": null,
  "completed_at": null,
  "total_count": 240,
  "sent_count": 0,
  "failed_count": 0,
  "skipped_count": 3,
  "replies_acknowledged_at": null,
  "created_by": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-08-31T09:00:00Z",
  "updated_at": "2026-08-31T09:00:00Z"
}],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/sms-campaigns/:campaign_id

Son état et ses compteurs.

Lire une campagne

« replies_acknowledged_at » est renseigné quand la campagne a été autorisée à partir d'un numéro qui n'accepte pas de réponses, et indique quand ce choix a été fait.

Erreurs

404Introuvable

Aucune campagne avec cet identifiant sur votre compte.

Vérifiez l'identifiant.

Requête

json

curl 'https://api.aethexai.com/api/v1/sms-campaigns/campaign-uuid' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "campaign-uuid",
  "phone_number_id": "number-uuid",
  "name": "Tomorrow's appointments",
  "body": "Hello {name}, your appointment is tomorrow at {time}.",
  "placeholders": ["name", "time"],
  "status": "draft",
  "rate_per_minute": 60,
  "scheduled_at": null,
  "started_at": null,
  "completed_at": null,
  "total_count": 240,
  "sent_count": 0,
  "failed_count": 0,
  "skipped_count": 3,
  "replies_acknowledged_at": null,
  "created_by": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-08-31T09:00:00Z",
  "updated_at": "2026-08-31T09:00:00Z"
}

GET/sms-campaigns/:campaign_id/recipients

Qui a été joint, qui ne l'a pas été, et pourquoi.

Destinataires d'une campagne

La liste sur laquelle une campagne se juge. « pending » n'a pas été tenté, « sending » est en vol, « sent » est parti chez l'opérateur, « failed » porte le verdict de l'opérateur, et « skipped » n'a délibérément pas été contacté.

Chemin & Requête

statusstringoptionnel
pending, sending, sent, failed ou skipped.
offsetintegeroptionnel
Combien de lignes ignorer. 0 par défaut.
limitintegeroptionnel
Combien de lignes renvoyer. 50 par défaut, 200 au maximum.

Requête

json

curl 'https://api.aethexai.com/api/v1/sms-campaigns/campaign-uuid/recipients?status=skipped' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [
    {
      "id": "recipient-uuid",
      "to_number": "+233244123456",
      "status": "skipped",
      "error": "opted out",
      "sent_at": null,
      "message_id": null
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 100
}

POST/sms-campaigns/:campaign_id/start

Commencer à envoyer, dans la minute.

Démarrer une campagne

Efface toute heure planifiée, car demander à démarrer c'est demander à ne plus attendre. Un worker la prend au balayage suivant. Pause et annulation prennent effet au message suivant, pas au lot suivant.

Erreurs

409Conflit

La campagne est terminée, annulée ou en échec.

Créez une nouvelle campagne. Une campagne terminée ne redémarre pas.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-campaigns/campaign-uuid/start' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "campaign-uuid",
  "phone_number_id": "number-uuid",
  "name": "Tomorrow's appointments",
  "body": "Hello {name}, your appointment is tomorrow at {time}.",
  "placeholders": ["name", "time"],
  "status": "running",
  "rate_per_minute": 60,
  "scheduled_at": null,
  "started_at": null,
  "completed_at": null,
  "total_count": 240,
  "sent_count": 0,
  "failed_count": 0,
  "skipped_count": 3,
  "replies_acknowledged_at": null,
  "created_by": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-08-31T09:00:00Z",
  "updated_at": "2026-08-31T09:00:00Z"
}

POST/sms-campaigns/:campaign_id/pause

S'arrêter après le message en cours.

Mettre une campagne en pause

Prend effet au message suivant. Redémarrez-la quand vous voulez ; les destinataires déjà joints ne le sont pas deux fois.

Erreurs

409Conflit

La campagne n'est ni en cours ni planifiée.

Rien à mettre en pause.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-campaigns/campaign-uuid/pause' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "campaign-uuid",
  "phone_number_id": "number-uuid",
  "name": "Tomorrow's appointments",
  "body": "Hello {name}, your appointment is tomorrow at {time}.",
  "placeholders": ["name", "time"],
  "status": "paused",
  "rate_per_minute": 60,
  "scheduled_at": null,
  "started_at": null,
  "completed_at": null,
  "total_count": 240,
  "sent_count": 0,
  "failed_count": 0,
  "skipped_count": 3,
  "replies_acknowledged_at": null,
  "created_by": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-08-31T09:00:00Z",
  "updated_at": "2026-08-31T09:00:00Z"
}

POST/sms-campaigns/:campaign_id/cancel

Arrêter définitivement.

Annuler une campagne

Ce qui est parti reste parti. Rien d'autre ne sort, et la campagne ne peut plus être démarrée.

Erreurs

409Conflit

La campagne est déjà terminée, annulée ou en échec.

Rien à annuler.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/sms-campaigns/campaign-uuid/cancel' \
  -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "campaign-uuid",
  "phone_number_id": "number-uuid",
  "name": "Tomorrow's appointments",
  "body": "Hello {name}, your appointment is tomorrow at {time}.",
  "placeholders": ["name", "time"],
  "status": "cancelled",
  "rate_per_minute": 60,
  "scheduled_at": null,
  "started_at": null,
  "completed_at": null,
  "total_count": 240,
  "sent_count": 0,
  "failed_count": 0,
  "skipped_count": 3,
  "replies_acknowledged_at": null,
  "created_by": null,
  "error": null,
  "webhook_url": null,
  "created_at": "2026-08-31T09:00:00Z",
  "updated_at": "2026-08-31T09:00:00Z"
}