Portail développeur Aethex

Référence API

Connectez un numéro WhatsApp Business, par un lien d'inscription hébergé ou votre propre application Meta, laissez votre agent y répondre, gérez les modèles, répondez en personne et lancez des campagnes.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 41
Portées: whatsapp_accounts:readwhatsapp_accounts:writewhatsapp_messages:writewhatsapp_inbox:readwhatsapp_inbox:write

POST/whatsapp-accounts/onboarding-sessions

Un lien à usage unique que votre client ouvre pour connecter son numéro WhatsApp à votre organisation.

Créer un lien d'inscription

Meta n'ouvre sa fenêtre d'inscription que sur les domaines autorisés dans l'application Meta : elle ne peut donc pas s'ouvrir sur votre site avec l'application d'Aethex. Envoyez plutôt votre client vers url. Une page hébergée par Aethex ouvre la fenêtre de Meta, connecte le numéro à votre organisation avec l'agent choisi, puis renvoie votre client vers return_url avec whatsapp_onboarding_session, status, whatsapp_account_id et votre state. Le webhook de l'agent reçoit un événement signé whatsapp.onboarding.completed. url n'est renvoyé que dans cette réponse et son secret est stocké sous forme d'empreinte. Le lien peut être réessayé jusqu'à ce qu'il aboutisse ou expire. Les liens cessent de fonctionner si le compte de votre organisation est fermé ou suspendu : ils répondent alors comme un lien qui n'existe pas.

Corps de la requête

return_urlstring (https URL)requis
Où votre client est renvoyé, terminé ou annulé. HTTPS, sans identifiants ni #fragment. Aethex ajoute whatsapp_onboarding_session, status, whatsapp_account_id (si terminé) et state.
statestringoptionnel
Valeur opaque à vous (512 caractères au plus), renvoyée telle quelle sur return_url et dans l'événement, comme l'identifiant de votre client.
default_agent_idstring (uuid)optionnel
L’agent qui répond aux messages et appels sur ce numéro.
labelstringoptionnel
Un nom pour ce numéro dans votre propre tableau de bord. Jamais montré aux clients.
expires_in_secondsintegeroptionnel
Durée de validité du lien : de 300 à 604800 secondes (5 minutes à 7 jours). Par défaut 86400 (24 heures).

Erreurs

403Non autorisé

Code whatsapp_hosted_onboarding_requires_billing : votre organisation n'a pas de moyen de paiement enregistré et n'est pas sur une offre payante. La page affiche le nom de votre organisation sur le domaine d'Aethex : seul un compte identifiable peut créer des liens.

Ajoutez un moyen de paiement dans Facturation, ou passez à une offre payante, puis recréez le lien.

422Requête invalide

return_url n'est pas une URL HTTPS absolue, default_agent_id n'est pas un UUID, ou expires_in_seconds est hors limites.

Corrigez le champ nommé dans fields et renvoyez la requête.

503Indisponible

Code whatsapp_hosted_onboarding_unavailable : l'inscription hébergée n'est pas encore disponible sur ce déploiement. Rien n'a été créé.

Réessayez plus tard, ou connectez les numéros que vous gérez vous-même avec POST /whatsapp-accounts.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/onboarding-sessions' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"return_url": "https://app.example.com/whatsapp/connected", "state": "customer-8841", "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94"}'

201 Réponse

json

{
  "id": "b2f0c9e4-7a3d-4f1e-9c8b-2d6a5e4f3c21",
  "status": "pending",
  "url": "https://api.aethexai.com/whatsapp/onboarding#k3J...",
  "return_url": "https://app.example.com/whatsapp/connected",
  "state": "customer-8841",
  "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
  "label": "",
  "whatsapp_account_id": null,
  "last_error_code": null,
  "last_error_message": null,
  "expires_at": "2026-10-01T09:00:00Z",
  "completed_at": null,
  "created_at": "2026-09-30T09:00:00Z"
}

GET/whatsapp-accounts/onboarding-sessions/:session_id

En attente, terminé ou expiré, avec le numéro connecté une fois terminé.

Consulter l'état d'un lien d'inscription

La solution de repli à la redirection et à l'événement. pending contient last_error_code et last_error_message quand la dernière tentative du client a échoué ; le lien reste valable jusqu'à expires_at. last_error_code est l'un des codes de refus de connexion (par exemple whatsapp_pin_locked, whatsapp_registration_throttled, whatsapp_signup_code_rejected, whatsapp_token_rejected ou whatsapp_meta_rejected), ou whatsapp_meta_unreachable quand Meta n'a pas pu être joint : réessayer suffit alors en général. completed contient whatsapp_account_id. url vaut toujours null ici.

Chemin & Requête

session_idstring (uuid)requis
Identifiant de la session d'inscription.

Erreurs

404Introuvable

Aucune session avec cet identifiant dans votre organisation.

Utilisez l'identifiant de la réponse de création ou le paramètre whatsapp_onboarding_session de return_url.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/onboarding-sessions/b2f0c9e4-7a3d-4f1e-9c8b-2d6a5e4f3c21' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "b2f0c9e4-7a3d-4f1e-9c8b-2d6a5e4f3c21",
  "status": "completed",
  "url": null,
  "return_url": "https://app.example.com/whatsapp/connected",
  "state": "customer-8841",
  "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
  "label": "",
  "whatsapp_account_id": "9d2e6b7a-5c1f-4e8a-a2b3-6f7d8e9c0a1b",
  "last_error_code": null,
  "last_error_message": null,
  "expires_at": "2026-10-01T09:00:00Z",
  "completed_at": "2026-09-30T09:04:12Z",
  "created_at": "2026-09-30T09:00:00Z"
}

POST/whatsapp-accounts/embedded-signup

Échanger le code renvoyé par la fenêtre de Meta, quand elle a été ouverte sur un domaine d'Aethex.

Terminer Embedded Signup sur les domaines d'Aethex

Meta ne renvoie le code de la fenêtre qu'à une page d'un domaine autorisé dans l'application Meta, ce qui pour l'application d'Aethex signifie ses propres domaines, comme la plateforme Aethex. Depuis tout autre domaine, créez plutôt un lien d'inscription. Envoyez le code à usage unique avec le WABA et le numéro choisis par le client. Aethex échange le code, enregistre le numéro sur la Cloud API, abonne le WABA aux webhooks, et l'agent associé commence à répondre.

Corps de la requête

codestringrequis
Le code à usage unique de la fenêtre Meta (un identifiant porteur — ne le journalisez jamais).
waba_idstringrequis
Le compte WhatsApp Business du numéro.
phone_number_idstringrequis
L’identifiant Meta du numéro.
default_agent_idstring (uuid)optionnel
L’agent qui répond aux messages et appels sur ce numéro.
labelstringoptionnel
Un nom pour ce numéro dans votre propre tableau de bord. Jamais montré aux clients.

Erreurs

422Requête invalide

Le code a déjà été utilisé, a expiré ou ne couvre pas le numéro.

Un code ne sert qu'une fois, pendant 30 secondes après la fermeture de la fenêtre, et seulement pour l'application Meta qui l'a ouverte : relancez la fenêtre et envoyez le nouveau code aussitôt. Le champ code de l'erreur précise le cas, par exemple whatsapp_signup_code_rejected ou whatsapp_pin_locked.

422Requête invalide

whatsapp_onboarding_unconfigured : l’inscription en libre-service n’est pas configurée sur ce déploiement, le code ne peut donc pas être utilisé.

Connectez les numéros que vous gérez vous-même avec POST /whatsapp-accounts, ou demandez à l’opérateur de configurer l’inscription.

409Conflit

whatsapp_number_already_linked : le numéro est déjà connecté, à cette organisation (y compris par une autre de vos requêtes, terminée la première) ou à une autre organisation Aethex. whatsapp_link_abandoned : cette connexion a été libérée ou a expiré pendant son exécution.

Si cette organisation l’a déjà, GET /whatsapp-accounts le liste et il n’y a rien à reconnecter. Sinon, l’organisation qui l’a doit d’abord le déconnecter. Pour whatsapp_link_abandoned, reconnectez le numéro.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/embedded-signup' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"code": "AQB...", "waba_id": "1613686663727049", "phone_number_id": "1210656312140303", "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94"}'

201 Réponse

json

{
  "id": "account-uuid",
  "waba_id": "1613686663727049",
  "phone_number_id": "1210656312140303",
  "display_phone_number": "+44 7930 308614",
  "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
  "label": "",
  "status": "active",
  "link_method": "embedded_signup",
  "credentials_invalid_since": null,
  "calling_status": "ENABLED",
  "calling_status_checked_at": "2026-08-28T09:00:00Z",
  "calling_enabled": true,
  "outbound_calling_available": true,
  "outbound_calling_unavailable_reason": null,
  "outbound_calling_unavailable_code": null,
  "created_at": "2026-08-28T09:00:00Z",
  "updated_at": "2026-08-28T09:00:00Z"
}

GET/whatsapp-accounts/embedded-signup/config

Les identifiants d'application et de configuration Meta dont votre interface a besoin pour ouvrir la fenêtre d'inscription.

Récupérer les paramètres d'inscription intégrée

Ce qu'une page d'un domaine d'Aethex transmet au SDK JavaScript de Facebook pour ouvrir la fenêtre de Meta : identifiant d'application, identifiant de configuration et version Graph. Sur tout autre domaine, Meta refuse d'ouvrir la fenêtre avec ces identifiants : utilisez POST /whatsapp-accounts/onboarding-sessions. enabled: false signifie qu'Embedded Signup n'est pas configuré sur ce déploiement.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/embedded-signup/config' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "enabled": true,
  "app_id": "1043210987654321",
  "config_id": "982734650192837",
  "graph_version": "v23.0"
}

POST/whatsapp-accounts

Connecter un numéro Cloud API avec un jeton d'utilisateur système de votre propre application Meta, et le secret de cette application.

Connecter un numéro sur votre propre application Meta

Pour un fournisseur technologique Meta disposant de sa propre application Meta, qui connecte un compte WhatsApp Business partagé avec cette application. Avant de stocker quoi que ce soit, Aethex demande à Meta quelle application a émis le jeton (GET /app) et vérifie que app_secret est bien son secret. Ensuite, Aethex abonne le WABA, vérifie que le numéro lui appartient et l'enregistre si vous envoyez registration_pin. Grâce à la redirection par numéro de Meta, les messages et appels du numéro sont dirigés vers webhook_callback_url, une URL qui lui est propre. La réponse affiche webhook_verify_token une seule fois. Votre application doit être abonnée à messages, et à calls pour les appels (voir GET /whatsapp-accounts/:account_id/webhook). Le jeton et le secret sont en écriture seule : stockés chiffrés et jamais renvoyés.

Corps de la requête

waba_idstringrequis
Le compte WhatsApp Business du numéro.
phone_number_idstringrequis
L’identifiant Meta du numéro.
access_tokenstringrequis
Jeton d'utilisateur système longue durée de votre application Meta, avec business_management, whatsapp_business_management et whatsapp_business_messaging. Stocké chiffré, jamais renvoyé.
app_secretstringoptionnel
Secret de l'application Meta qui a émis access_token (App Dashboard > Paramètres de l'app > Général). Obligatoire pour un jeton de votre propre application : chaque appel Graph du numéro est signé avec, et ses webhooks sont vérifiés avec. À omettre seulement pour un jeton émis par l'application d'Aethex. Stocké chiffré, jamais renvoyé.
default_agent_idstring (uuid)optionnel
L’agent qui répond aux messages et appels sur ce numéro.
labelstringoptionnel
Un nom pour ce numéro dans votre propre tableau de bord. Jamais montré aux clients.
registration_pinstringoptionnel
Code PIN à six chiffres de la validation en deux étapes. Fournissez-le pour enregistrer le numéro sur Cloud API dès la connexion.

Erreurs

422Requête invalide

Meta a refusé le jeton (whatsapp_token_invalid, whatsapp_token_rejected), le numéro n'est pas dans ce WABA (whatsapp_number_not_in_waba) ou pas enregistré sur la Cloud API (whatsapp_number_not_registered), ou Meta a refusé une autre étape (whatsapp_meta_rejected, avec les mots de Meta).

Agissez selon le code et le message : émettez un nouveau jeton d'utilisateur système avec les autorisations ci-dessus, vérifiez les deux identifiants dans WhatsApp Manager, ou envoyez registration_pin.

422Requête invalide

whatsapp_app_secret_required : le jeton vient de votre propre application Meta et aucun app_secret n'a été envoyé. whatsapp_app_secret_mismatch : le secret appartient à une autre application.

Envoyez le secret de l'application à laquelle appartient l'utilisateur système.

422Requête invalide

whatsapp_no_signing_secret : aucun app_secret n’a été envoyé et ce déploiement n’a pas de secret de plateforme pour vérifier les webhooks du numéro. whatsapp_webhook_route_failed : Meta a refusé d’envoyer à Aethex les webhooks de votre numéro sur votre propre application.

Envoyez l’app_secret de votre application. En cas de refus de routage, ajoutez le produit WhatsApp à votre application Meta avec un webhook configuré, puis reconnectez le numéro : il reste non connecté tant que le routage n’a pas réussi, et la nouvelle tentative reprend cette connexion.

422Requête invalide

validation_error : le corps n'est pas valide, et fields nomme le champ. Cause fréquente : un default_agent_id qui n'est pas un UUID.

Envoyez l'identifiant d'un agent (listez-les avec GET /agents), ou omettez-le et définissez-le plus tard avec PATCH.

409Conflit

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "waba_id": "1613686663727049",
    "phone_number_id": "1210656312140303",
    "access_token": "EAAG...",
    "app_secret": "your-meta-app-secret",
    "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
    "label": "Clinic main line"
  }'

201 Réponse

json

{
  "id": "account-uuid",
  "waba_id": "1613686663727049",
  "phone_number_id": "1210656312140303",
  "display_phone_number": "+44 7930 308614",
  "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
  "label": "Clinic main line",
  "status": "active",
  "link_method": "byo",
  "meta_app_id": "1043210987654321",
  "webhook_callback_url": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-5c1f-4e8a-a2b3-6f7d8e9c0a1b",
  "webhook_verify_token": "q8Vn...shown once...",
  "credentials_invalid_since": null,
  "calling_status": "ENABLED",
  "calling_status_checked_at": "2026-08-28T09:00:00Z",
  "calling_enabled": true,
  "outbound_calling_available": true,
  "outbound_calling_unavailable_reason": null,
  "outbound_calling_unavailable_code": null,
  "created_at": "2026-08-28T09:00:00Z",
  "updated_at": "2026-08-28T09:00:00Z"
}

GET/whatsapp-accounts/:account_id/webhook

Où Meta envoie les messages du numéro, et ce qu'il manque encore à votre application Meta.

Vérifier le webhook d'un numéro

mode: platform_app : un numéro sur l'application Meta d'Aethex, rien à configurer. mode: own_app : un numéro sur votre propre application. callback_url est l'URL Aethex propre au numéro, et trois champs sont lus en direct chez Meta : meta_routed_to (où Meta envoie les messages du numéro), meta_subscribed_fields (les champs de webhook de votre application) et problems (ce qui manque : messages dirigés ailleurs, champ non souscrit ou aucun webhook). required_fields liste ce dont le numéro a besoin.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/webhook' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "mode": "own_app",
  "callback_url": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-5c1f-4e8a-a2b3-6f7d8e9c0a1b",
  "verified_at": null,
  "required_fields": ["messages", "calls"],
  "meta_routed_to": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-5c1f-4e8a-a2b3-6f7d8e9c0a1b",
  "meta_subscribed_fields": ["messages"],
  "problems": ["Your Meta app does not subscribe to calls: subscribe in App Dashboard > WhatsApp > Configuration, or those events never reach Aethex."]
}

POST/whatsapp-accounts/:account_id/webhook/verify-token

Un nouveau jeton de vérification pour l'URL de webhook propre au numéro, affiché une seule fois.

Renouveler le jeton de vérification du webhook d'un numéro

Pour un numéro sur votre propre application Meta. L'ancien jeton cesse de fonctionner, et Aethex redirige à nouveau le numéro vers callback_url avec le nouveau. Utilisez-le là où vous configurez vous-même un callback. Le callback de votre application dans App Dashboard ne peut pointer vers callback_url que si c'est le seul numéro de l'application, car cette URL ne répond que pour ce numéro. Aethex n'en garde qu'une empreinte.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

409Conflit

Le numéro est sur l'application Meta d'Aethex, dont Aethex reçoit déjà les webhooks.

Rien à configurer pour ce numéro.

422Requête invalide

whatsapp_webhook_route_failed : Meta a refusé d’acheminer le numéro vers son URL avec le nouveau jeton. whatsapp_webhook_unavailable : ce déploiement n’a pas d’hôte d’API public vers lequel l’acheminer.

En cas de refus de routage, vérifiez qu’un webhook est configuré sur votre application Meta, puis renouvelez le jeton : l’ancien reste valable tant qu’aucun renouvellement n’a réussi.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/webhook/verify-token' -H "X-API-Key: YOUR_KEY"

201 Réponse

json

{
  "callback_url": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-5c1f-4e8a-a2b3-6f7d8e9c0a1b",
  "verify_token": "Zr4t...shown once..."
}

GET/whatsapp-accounts

Tous les numéros WhatsApp connectés à votre espace de travail.

Lister vos numéros WhatsApp

Renvoie une ligne par numéro connecté, du plus récent au plus ancien. Surveillez credentials_invalid_since : une valeur non nulle signifie que Meta n'accepte plus notre jeton pour ce numéro et que plus rien ne partira tant que vous n'en fournissez pas un nouveau. calling_enabled indique si les clients peuvent appeler le numéro sur WhatsApp, d'après calling_status tel que Meta l'a signalé en dernier ; GET …/health le lit en direct.

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/whatsapp-accounts' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [{
    "id": "account-uuid",
    "waba_id": "1613686663727049",
    "phone_number_id": "1210656312140303",
    "display_phone_number": "+44 7930 308614",
    "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
    "label": "Clinic main line",
    "status": "active",
    "link_method": "embedded_signup",
    "credentials_invalid_since": null,
    "calling_status": "ENABLED",
    "calling_status_checked_at": "2026-08-28T09:00:00Z",
    "calling_enabled": true,
    "outbound_calling_available": true,
    "outbound_calling_unavailable_reason": null,
    "outbound_calling_unavailable_code": null,
    "created_at": "2026-08-28T09:00:00Z",
    "updated_at": "2026-08-28T09:00:00Z"
  }],
  "total": 1
}

GET/whatsapp-accounts/:account_id

L'enregistrement d'un seul numéro connecté.

Récupérer un numéro WhatsApp

Renvoie la même structure que la liste, pour un seul numéro. Utilisez-le pour relire quel agent répond sur ce numéro (default_agent_id) et si ses identifiants sont toujours valides.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "account-uuid",
  "waba_id": "1613686663727049",
  "phone_number_id": "1210656312140303",
  "display_phone_number": "+44 7930 308614",
  "default_agent_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94",
  "label": "Clinic main line",
  "status": "active",
  "link_method": "embedded_signup",
  "credentials_invalid_since": null,
  "calling_status": "ENABLED",
  "calling_status_checked_at": "2026-08-28T09:00:00Z",
  "calling_enabled": true,
  "outbound_calling_available": true,
  "outbound_calling_unavailable_reason": null,
  "outbound_calling_unavailable_code": null,
  "created_at": "2026-08-28T09:00:00Z",
  "updated_at": "2026-08-28T09:00:00Z"
}

PATCH/whatsapp-accounts/:account_id

Changez l'agent qui répond, renommez le numéro ou remplacez son jeton.

Modifier un numéro WhatsApp

Tous les champs sont facultatifs ; n'envoyez que ce qui change. Passer default_agent_id: null détache le numéro : les messages entrants restent enregistrés dans la boîte de réception, mais aucun agent ne répond. Un access_token de remplacement est vérifié auprès de Meta avant d'être stocké et, s'il fonctionne, remet credentials_invalid_since à null.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

default_agent_idstring (uuid) | nulloptionnel
L'agent qui répond sur ce numéro. null le détache et arrête les réponses automatiques.
labelstringoptionnel
Un nom pour ce numéro dans votre propre tableau de bord. Jamais montré aux clients.
access_tokenstringoptionnel
Jeton d'utilisateur système de remplacement. Vérifié auprès de Meta avant d'être stocké ; en écriture seule.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl -X PATCH 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"default_agent_id": "8a1d4f0b-2c6e-4b9a-b3d7-0e5f9c2a7b61"}'

Réponse 200

json

{
  "id": "account-uuid",
  "display_phone_number": "+44 7930 308614",
  "default_agent_id": "8a1d4f0b-2c6e-4b9a-b3d7-0e5f9c2a7b61",
  "label": "Clinic main line",
  "status": "active",
  "credentials_invalid_since": null,
  "calling_status": "ENABLED",
  "calling_status_checked_at": "2026-08-28T09:00:00Z",
  "calling_enabled": true,
  "outbound_calling_available": true,
  "outbound_calling_unavailable_reason": null,
  "outbound_calling_unavailable_code": null,
  "updated_at": "2026-08-28T10:04:00Z"
}

DELETE/whatsapp-accounts/:account_id

Retirez le numéro de votre espace de travail et arrêtez toute messagerie dessus.

Déconnecter un numéro WhatsApp

Déconnecte le numéro et supprime les identifiants que nous détenons. Les conversations et leur historique sont conservés, ce qui préserve la piste d'audit, mais plus rien n'est envoyé ni reçu. Renvoie 204 sans corps ; supprimer un numéro déjà supprimé renvoie 404.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

POST/whatsapp-accounts/:account_id/templates

Soumettez un modèle à la revue de Meta. L’approbation prend de quelques minutes à une journée.

Créer un modèle de message

Les messages à l’initiative de l’entreprise — tout envoi hors de la fenêtre de 24 heures ouverte par un message client — doivent utiliser un modèle approuvé. Aethex applique les règles structurelles de Meta avant soumission et renvoie un 422 nommant la règle, plutôt qu’un rejet quelques minutes plus tard sans explication.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

namestringrequis
Lettres minuscules, chiffres et tirets bas.
languagestringrequis
Code de langue, ex. en_US, fr, pt_BR.
categorystringrequis
UTILITY, MARKETING ou AUTHENTICATION.
componentsobject[]requis
Le tableau de composants Meta : BODY (obligatoire), HEADER, FOOTER, BUTTONS optionnels. Chaque variable {{n}} nécessite une valeur d’exemple dans example.

Erreurs

422Requête invalide

Une règle que Meta rejetterait : variable en début ou fin, variables hors séquence, variable sans exemple, en-tête de plus de 60 caractères, etc.

Le détail nomme la règle ; corrigez le composant et resoumettez.

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/templates' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "appointment_reminder", "language": "en_US", "category": "UTILITY",
    "components": [{
      "type": "BODY",
      "text": "Hi {{1}}, this is a reminder of your appointment on {{2}}. Reply RESCHEDULE to change it.",
      "example": {"body_text": [["Alex", "Tuesday 3 September at 3:00 pm"]]}
    }]
  }'

201 Réponse

json

{
  "id": "1537408970955655",
  "name": "appointment_reminder",
  "language": "en_US",
  "status": "PENDING",
  "category": "UTILITY",
  "components": [{ "type": "BODY", "text": "Hi {{1}}, this is a reminder of your appointment on {{2}}." }],
  "rejected_reason": null
}

GET/whatsapp-accounts/:account_id/templates

Tous les modèles de ce WABA et l'état de leur validation par Meta.

Lister les modèles

Les modèles sont lus directement chez Meta, donc status est à jour : APPROVED est envoyable, PENDING est encore en cours de validation, REJECTED porte un rejected_reason. La pagination se fait par curseur — lorsque next_cursor n'est pas nul, passez-le en ?after= pour la page suivante.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
limitintegeroptionnel
Nombre de lignes à renvoyer. De 1 à 200, 50 par défaut.
afterstringoptionnel
Curseur issu du next_cursor d'une réponse précédente. À omettre pour la première page.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/templates?limit=50' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [
    { "id": "1537408970955655", "name": "appointment_reminder", "language": "en_US", "status": "APPROVED", "category": "UTILITY", "components": [], "rejected_reason": null },
    { "id": "1537408970955612", "name": "results_ready", "language": "en_US", "status": "REJECTED", "category": "UTILITY", "components": [], "rejected_reason": "INVALID_FORMAT" }
  ],
  "next_cursor": null
}

DELETE/whatsapp-accounts/:account_id/templates/:template_name

Retirez un modèle du WABA par son nom.

Supprimer un modèle

Supprime chez Meta toutes les versions linguistiques du modèle nommé. Les campagnes qui l'utilisent se mettront à échouer : vérifiez d'abord qu'il n'est plus utilisé. Renvoie 204 sans corps.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
template_namestringrequis
Le nom du modèle, exactement tel qu'il a été créé. Pas son identifiant numérique.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

POST/whatsapp-accounts/:account_id/messages

Ouvrir (ou rouvrir) une conversation avec un modèle approuvé.

Envoyer un message modèle

Envoie sous un modèle approuvé, seule façon d’écrire à un client hors de la fenêtre de 24 heures. Renvoie 202 : Meta a accepté le message pour livraison. Les accusés de livraison et de lecture arrivent sur le fil et, si configuré, sur votre webhook en whatsapp.message.status. Chaque message accepté est facturé.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

tostringrequis
Destinataire en E.164, avec ou sans le + initial.
namestringrequis
Un modèle APPROVED sur ce numéro.
languagestringrequis
Le code de langue du modèle.
componentsobject[]optionnel
Les valeurs des variables du modèle, au format des composants Meta.

Erreurs

422Requête invalide

Le modèle est inconnu, non approuvé, ou le nombre de variables ne correspond pas.

Listez les modèles et vérifiez le statut et le corps ; envoyez exactement une valeur par variable.

429Limite atteinte

Le budget d’envoi de l’espace de travail est dépassé.

Respectez Retry-After ; pour les envois en masse, utilisez une campagne, qui se régule elle-même.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/messages' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+447700900123", "name": "appointment_reminder", "language": "en_US",
       "components": [{"type": "body", "parameters": [{"type": "text", "text": "Alex"}, {"type": "text", "text": "Tuesday at 3pm"}]}]}'

202 Réponse

json

{ "message_id": "wamid.HBgM...", "to": "447700900123", "accepted_at": "2026-08-28T09:12:44Z" }

POST/whatsapp-accounts/:account_id/messages/options

Posez une question avec jusqu'à dix réponses que le client tape au lieu d'écrire.

Envoyer des options à taper

Ne fonctionne que dans la fenêtre de 24 heures ouverte par le message d'un client : c'est un message de session, pas un modèle. De une à trois options s'affichent en boutons ; quatre ou plus s'affichent en liste, ouverte par le libellé list_button. Le choix du client arrive sur votre webhook comme sa réponse, porteur de l'id que vous avez défini — c'est sur cet id que vous devez faire la correspondance, pas sur le libellé visible.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

tostringrequis
Destinataire en E.164, avec ou sans le + initial.
bodystringrequis
La question. Jusqu'à 1024 caractères.
optionsobject[]requis
De une à dix options. Trois ou moins s'affichent en boutons, quatre ou plus en liste.
options[].idstringrequis
Votre identifiant de l'option, renvoyé tel quel lorsque le client la choisit. Jusqu'à 200 caractères.
options[].titlestringrequis
Le libellé visible, jusqu'à 24 caractères.
options[].descriptionstringoptionnel
Une seconde ligne sous le libellé. Affichée uniquement en liste (quatre options ou plus).
headerstringoptionnel
Ligne en gras facultative au-dessus de la question, jusqu'à 60 caractères.
footerstringoptionnel
Ligne grise facultative sous les options, jusqu'à 60 caractères.
list_buttonstringoptionnel
Libellé du bouton qui ouvre la liste. Choose par défaut, jusqu'à 20 caractères.

Erreurs

422Refusé par WhatsApp

La fenêtre de 24 heures depuis le dernier message du client est fermée : WhatsApp refuse les messages de session.

Envoyez plutôt un modèle approuvé ; dès que le client répond, la fenêtre se rouvre et les options fonctionnent de nouveau.

422Requête invalide

La liste d'options est vide, dépasse dix entrées, ou une option dépasse ses limites de longueur.

Envoyez entre une et dix options, chacune avec un libellé de 24 caractères maximum.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/messages/options' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900123",
    "body": "When suits you best?",
    "options": [
      {"id": "tue_15", "title": "Tuesday 3pm"},
      {"id": "wed_10", "title": "Wednesday 10am"},
      {"id": "fri_16", "title": "Friday 4pm"}
    ]
  }'

202 Réponse

json

{ "message_id": "wamid.HBgM...", "to": "447700900123", "accepted_at": "2026-08-28T09:13:10Z" }

GET/whatsapp-accounts/:account_id/inbox/summary

Conversations ouvertes, non lues et en attente d'une personne, en un seul appel.

Récupérer les compteurs de la boîte de réception

Les trois chiffres dont un tableau de bord d'opérateur a besoin, sans parcourir les conversations. human compte les conversations ouvertes qu'une personne a reprises et n'a pas encore clôturées — la file à staffer.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

GET/whatsapp-accounts/:account_id/threads

Chaque client du numéro, du plus récent au plus ancien, avec les non-lus et qui répond.

Lister les fils (boîte de réception)

Un fil est un client sur un numéro. mode vaut agent (l’agent répond) ou human (une personne s’en charge ; l’agent se tait). Filtrez sur mode=human pour trouver les conversations en attente d’une personne.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
statusstringoptionnel
open ou closed.
modestringoptionnel
agent ou human.
unreadbooleanoptionnel
Seulement les fils avec des messages client non lus.
qstringoptionnel
Recherche sur le numéro, le nom ou le dernier message.
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.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads?mode=human' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [{
    "id": "thread-uuid", "whatsapp_account_id": "account-uuid",
    "customer": "447700900123", "customer_name": "Alex",
    "status": "open", "mode": "human", "assigned_to": "[email protected]",
    "handoff_reason": "billing dispute", "unread_count": 2, "session_open": true,
    "last_message_preview": "Can I speak to someone about my results?",
    "last_message_direction": "inbound", "last_message_at": "2026-08-28T09:10:02Z"
  }],
  "total": 1, "offset": 0, "limit": 50
}

GET/whatsapp-accounts/:account_id/threads/:thread_id

L'enregistrement complet d'une conversation, fenêtre d'envoi comprise.

Récupérer une conversation

mode indique qui répond : agent pour l'IA, human dès qu'une personne a repris la main. session_open indique ce que vous pouvez envoyer : du texte libre tant qu'il vaut true, un modèle approuvé une fois qu'il vaut false.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.

Erreurs

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "thread-uuid", "whatsapp_account_id": "account-uuid",
  "customer": "447700900123", "customer_name": "Alex",
  "status": "open", "mode": "agent", "assigned_to": null,
  "handoff_reason": null, "handoff_requested_at": null,
  "last_inbound_at": "2026-08-28T09:10:02Z", "last_outbound_at": "2026-08-28T09:10:09Z",
  "unread_count": 0, "session_open": true,
  "created_at": "2026-08-20T11:00:00Z", "updated_at": "2026-08-28T09:10:09Z"
}

PATCH/whatsapp-accounts/:account_id/threads/:thread_id

Clôturez ou rouvrez une conversation, et changez la personne qui en a la charge.

Modifier une conversation

Cet endpoint sert à la gestion de la conversation, pas à son mode : la clôturer la retire de la file des conversations ouvertes, et l'affectation enregistre laquelle de vos personnes s'en occupe. La clôture n'empêche pas le client d'écrire : un nouveau message entrant rouvre la conversation. Pour rendre la main à l'agent, utilisez plutôt l'endpoint de mode.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.

Corps de la requête

statusstringoptionnel
open ou closed. La clôture la retire de la file ouverte ; un nouveau message entrant la rouvre.
assigned_tostringoptionnel
La personne en charge, en général une adresse e-mail. Enregistrée et renvoyée dans assigned_to.
clear_assignmentbooleanoptionnel
Envoyez true pour retirer l'affectation. Prioritaire sur assigned_to.

Erreurs

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl -X PATCH 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"status": "closed", "clear_assignment": true}'

Réponse 200

json

{ "id": "thread-uuid", "status": "closed", "mode": "agent", "assigned_to": null }

GET/whatsapp-accounts/:account_id/threads/:thread_id/messages

La chronologie complète, chats et appels, du plus ancien au plus récent, avec l’état de livraison des envois.

Lire les messages d’un fil

Chaque tour du client avec ce numéro : réponses de l’agent, réponses d’opérateur (author operator:<email>), envois de modèles et appels. Les tours sortants portent l’identifiant de message Meta et delivery_status (sent, delivered, read, failed, ou unknown lorsque la réponse à l’envoi a été perdue et que le message a peut-être été livré malgré tout : ne le renvoyez pas à l’aveugle).

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.
beforestring (ISO 8601)optionnel
Paginer en arrière à partir de cet horodatage.
limitintegeroptionnel
1–200, 50 par défaut.

Erreurs

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id/messages?limit=50' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [
    { "id": "turn-uuid", "role": "user", "author": null, "kind": "text", "text": "hello", "created_at": "2026-08-28T00:17:18Z" },
    { "id": "turn-uuid", "role": "assistant", "author": "agent", "kind": "text", "text": "Hello, this is Aethex Clinic. How can I help you today?", "message_id": "wamid...", "delivery_status": "read", "created_at": "2026-08-28T00:17:19Z" }
  ],
  "has_more": false
}

POST/whatsapp-accounts/:account_id/threads/:thread_id/mode

Changer qui répond. En mode human, l’agent se tait et les messages client augmentent les non-lus.

Confier un fil à une personne, ou le rendre à l’agent

Passer en human arrête les réponses de l’agent sur ce fil ; les nouveaux messages client sont conservés, les non-lus augmentent et whatsapp.message.received est envoyé à votre webhook. Un client qui demande une personne déclenche le même passage automatiquement (avec whatsapp.handoff.requested). Repasser en agent relance l’agent avec tout le contexte.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.

Corps de la requête

modestringrequis
human ou agent.
actorstringoptionnel
Qui prend ou rend le fil (un e-mail) ; enregistré sur le fil.
reasonstringoptionnel
Le motif, affiché dans la boîte de réception.

Erreurs

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id/mode' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "human", "actor": "[email protected]", "reason": "billing dispute"}'

Réponse 200

json

{ "id": "thread-uuid", "mode": "human", "assigned_to": "[email protected]", "handoff_reason": "billing dispute" }

POST/whatsapp-accounts/:account_id/threads/:thread_id/messages

Envoyer du texte libre dans la fenêtre de 24 heures. Au-delà, utilisez un modèle.

Répondre en tant que personne

Envoie un message texte en tant qu’opérateur et l’enregistre dans la chronologie avec l’identité de l’auteur. WhatsApp n’autorise le texte libre que dans les 24 heures suivant le dernier message du client ; au-delà, cette route renvoie 409 et vous devez envoyer un modèle (POST .../threads/{thread_id}/messages/template).

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.

Corps de la requête

textstringrequis
Jusqu’à 4096 caractères.
actorstringoptionnel
La personne qui répond (un e-mail), affichée dans la boîte de réception.

Erreurs

409Fenêtre fermée

Plus de 24 heures depuis le dernier message du client.

Envoyez un modèle approuvé pour rouvrir la conversation.

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id/messages' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Hi Alex, Sam here from the clinic. Your results are in — shall I book a call?", "actor": "[email protected]"}'

202 Réponse

json

{ "message_id": "wamid.HBgM...", "to": "447700900123", "accepted_at": "2026-08-28T09:14:01Z" }

POST/whatsapp-accounts/:account_id/threads/:thread_id/messages/template

Relancez une conversation dont la fenêtre de 24 heures est fermée.

Répondre avec un modèle

Le pendant, côté opérateur, de la réponse en texte libre, lorsque session_open vaut false et que WhatsApp n'accepte plus de texte brut. Envoie un modèle approuvé dans la conversation existante et l'enregistre comme un tour opérateur, pour que la transcription reste au même endroit. L'envoi ne rouvre rien en soi : la fenêtre se rouvre quand le client répond.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.

Corps de la requête

namestringrequis
Le nom du modèle approuvé.
languagestringrequis
Le code de langue du modèle, par exemple en_US.
paramsstring[]optionnel
Les valeurs des variables {{1}}, {{2}} … du modèle, dans l'ordre.
actorstringoptionnel
La personne qui répond (un e-mail), affichée dans la boîte de réception.

Erreurs

422Requête invalide

Le modèle est inconnu, non approuvé, ou le nombre de variables ne correspond pas.

Listez les modèles et vérifiez le statut et le corps ; envoyez exactement une valeur par variable.

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id/messages/template' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name": "appointment_reminder", "language": "en_US", "params": ["Alex", "Tuesday at 3pm"], "actor": "[email protected]"}'

202 Réponse

json

{ "message_id": "wamid.HBgM...", "to": "447700900123", "accepted_at": "2026-08-28T09:15:22Z" }

POST/whatsapp-accounts/:account_id/threads/:thread_id/read

Remet à zéro le compteur de messages non lus.

Marquer une conversation comme lue

Appelez-le quand une de vos personnes ouvre la conversation dans votre propre interface. Cela efface unread_count de notre côté uniquement : aucun accusé de lecture n'est envoyé au client.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.

Erreurs

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/threads/:thread_id/read' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{ "id": "thread-uuid", "unread_count": 0, "status": "open", "mode": "human" }

DELETE/whatsapp-accounts/:account_id/threads/:thread_id

Supprime les messages de ce client, les transcriptions et l'audio de ses appels, et ce que l'agent retient de lui sur ce numéro, pour que son prochain message reparte de zéro.

Effacer une conversation

Supprime le fil, toutes les transcriptions de discussion et d'appel avec ce client sur ce numéro, l'audio des appels, et ce que chaque agent du numéro retient de lui (son résumé et sa mémoire de recherche). Son prochain message ouvre un nouveau fil, traité par un agent qui ne le connaît pas encore. Les fiches d'appel (durée, coût, statut) sont conservées pour la facturation et l'usage, sans transcription ni audio. L'audio ne peut plus être écouté dès l'effacement et disparaît du stockage et de sa sauvegarde sous 30 jours. Cette action est irréversible. Passez actor pour consigner qui a effacé la conversation.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
thread_idstring (uuid)requis
L'identifiant de la conversation.
actorstring (query)optionnel
Opérateur qui efface la conversation, consigné avec l'effacement.

Erreurs

404Introuvable

Aucune conversation portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les conversations du numéro et reprenez un id de la réponse.

409Conflit

L'agent est en train de répondre à ce client, ou un appel avec lui est encore en cours ou son audio est encore en cours d'enregistrement.

Réessayez dans quelques instants (jusqu'à quelques minutes après la fin d'un appel).

POST/whatsapp-accounts/:account_id/campaigns

Un modèle approuvé vers de nombreux clients, régulé, avec le résultat par destinataire.

Créer une campagne

Les destinataires sont validés en amont — chaque ligne doit porter exactement le nombre de variables du modèle, les numéros sont normalisés et dédoublonnés, et la ligne fautive est nommée. Le worker envoie au plus rate_per_minute par minute, enregistre l’identifiant Meta par destinataire, et les accusés alimentent les compteurs livrés et lus. Mettez en pause, reprenez ou annulez avec POST .../campaigns/{campaign_id}/{pause|start|cancel}.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

namestringrequis
Un libellé pour la campagne.
template_namestringrequis
Un modèle APPROVED sur ce numéro.
template_languagestringrequis
Le code de langue du modèle.
recipientsobject[]requis
Des objets {to, params} ; params dans l’ordre des variables du modèle.
rate_per_minuteintegeroptionnel
1–600 envois par minute (60 par défaut).
scheduled_atstring (ISO 8601)optionnel
Démarrer automatiquement à cette heure (avec décalage horaire).
start_nowbooleanoptionnel
Démarrer immédiatement.
webhook_urlstringoptionnel
URL HTTPS qui reçoit un whatsapp.campaign.paused signé si le worker arrête cette campagne de lui-même (aujourd'hui : le compte n'a plus de crédit). Une pause que vous demandez n'est pas signalée. Nécessite le secret webhook de votre compte. Omise, personne n'est prévenu.

Erreurs

422Requête invalide

Une ligne a un mauvais nombre de valeurs ou un numéro invalide, ou le modèle n’est pas approuvé.

Le détail nomme la ligne ; corrigez-la et resoumettez.

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/campaigns' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Tomorrow reminders", "template_name": "appointment_reminder", "template_language": "en_US",
    "recipients": [{"to": "+447700900123", "params": ["Alex", "Tuesday at 3pm"]}, {"to": "+447700900124", "params": ["Sam", "Tuesday at 4pm"]}],
    "rate_per_minute": 60, "start_now": true
  }'

201 Réponse

json

{
  "id": "campaign-uuid", "whatsapp_account_id": "account-uuid",
  "name": "Tomorrow reminders", "template_name": "appointment_reminder", "template_language": "en_US",
  "status": "running", "rate_per_minute": 60,
  "scheduled_at": null, "started_at": "2026-08-28T09:20:00Z", "completed_at": null,
  "total_count": 2, "sent_count": 0, "delivered_count": 0, "read_count": 0, "failed_count": 0,
  "error": null, "webhook_url": null, "created_at": "2026-08-28T09:20:00Z", "updated_at": "2026-08-28T09:20:00Z"
}

GET/whatsapp-accounts/:account_id/campaigns

Toutes les campagnes de ce numéro, de la plus récente à la plus ancienne.

Lister les campagnes

Filtrez avec ?status= pour n'interroger que ce qui est en cours. Les compteurs de chaque ligne (sent_count, delivered_count, read_count, failed_count) évoluent au fil de la campagne : c'est le moyen le moins coûteux de suivre l'avancement sans parcourir les destinataires.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
statusstringoptionnel
Ne renvoie que les campagnes dans cet état : draft, scheduled, running, paused, completed, cancelled ou failed.
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.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

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

Réponse 200

json

{
  "data": [{
    "id": "campaign-uuid", "name": "Tomorrow reminders",
    "template_name": "appointment_reminder", "template_language": "en_US",
    "status": "running", "rate_per_minute": 60,
    "total_count": 2, "sent_count": 1, "delivered_count": 1, "read_count": 0, "failed_count": 0,
    "error": null, "created_at": "2026-08-28T09:20:00Z", "updated_at": "2026-08-28T09:21:00Z"
  }],
  "total": 1, "offset": 0, "limit": 50
}

GET/whatsapp-accounts/:account_id/campaigns/:campaign_id

Statut et compteurs d'une seule campagne.

Récupérer une campagne

La même ligne que dans la liste, pour une campagne. error est renseigné lorsqu'une campagne s'est arrêtée pour une raison que vous pouvez corriger : dès que la reprise est possible, elle se met en pause plutôt qu'en échec.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
campaign_idstring (uuid)requis
L'identifiant de la campagne.

Erreurs

404Introuvable

Aucune campagne portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les campagnes du numéro et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/campaigns/:campaign_id' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "id": "campaign-uuid", "whatsapp_account_id": "account-uuid",
  "name": "Tomorrow reminders", "template_name": "appointment_reminder", "template_language": "en_US",
  "status": "completed", "rate_per_minute": 60,
  "scheduled_at": null, "started_at": "2026-08-28T09:20:00Z", "completed_at": "2026-08-28T09:22:00Z",
  "total_count": 2, "sent_count": 2, "delivered_count": 2, "read_count": 1, "failed_count": 0,
  "error": null, "created_at": "2026-08-28T09:20:00Z", "updated_at": "2026-08-28T09:22:00Z"
}

POST/whatsapp-accounts/:account_id/campaigns/:campaign_id/start

Lancez les envois, ou reprenez une campagne en pause.

Démarrer une campagne

Démarre une campagne draft ou scheduled et reprend une campagne paused là où elle s'était arrêtée — les destinataires déjà traités ne sont pas recontactés. Les envois commencent quelques secondes après la réponse.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
campaign_idstring (uuid)requis
L'identifiant de la campagne.

Erreurs

409Conflit

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

Seule une campagne draft, scheduled ou paused peut être démarrée. Lisez d'abord son statut.

404Introuvable

Aucune campagne portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les campagnes du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/campaigns/:campaign_id/start' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{ "id": "campaign-uuid", "status": "running", "started_at": "2026-08-28T09:20:00Z", "total_count": 2, "sent_count": 0 }

POST/whatsapp-accounts/:account_id/campaigns/:campaign_id/pause

Arrêtez les envois en conservant les destinataires restants pour plus tard.

Mettre une campagne en pause

Arrête le parcours après le message en cours d'envoi. Les destinataires encore en attente le restent : redémarrer la campagne reprend au même endroit. Préférez la pause à l'annulation dès que vous pourriez continuer.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
campaign_idstring (uuid)requis
L'identifiant de la campagne.

Erreurs

409Conflit

La campagne n'est pas en cours : il n'y a rien à mettre en pause.

Seule une campagne running peut être mise en pause.

404Introuvable

Aucune campagne portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les campagnes du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/campaigns/:campaign_id/pause' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{ "id": "campaign-uuid", "status": "paused", "total_count": 200, "sent_count": 48, "failed_count": 1 }

POST/whatsapp-accounts/:account_id/campaigns/:campaign_id/cancel

Abandonnez définitivement les destinataires restants.

Annuler une campagne

Met fin au parcours et abandonne tous les destinataires en attente. L'opération est définitive : une campagne annulée ne peut pas être redémarrée. Les messages déjà acceptés par WhatsApp sont tout de même délivrés.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
campaign_idstring (uuid)requis
L'identifiant de la campagne.

Erreurs

409Conflit

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

Rien à faire : une campagne terminée ou annulée est déjà dans un état définitif.

404Introuvable

Aucune campagne portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les campagnes du numéro et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/campaigns/:campaign_id/cancel' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{ "id": "campaign-uuid", "status": "cancelled", "total_count": 200, "sent_count": 48, "failed_count": 1 }

GET/whatsapp-accounts/:account_id/campaigns/:campaign_id/recipients

Le résultat ligne par ligne pour chaque numéro d'une campagne.

Lister les destinataires d'une campagne

Le détail par destinataire derrière les compteurs de la campagne. Filtrez avec ?status=failed pour n'extraire que les échecs : chaque ligne en échec porte la raison dans error, et chaque ligne envoyée porte le message_id à citer au support WhatsApp ou à rapprocher des webhooks de livraison.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
campaign_idstring (uuid)requis
L'identifiant de la campagne.
statusstringoptionnel
Ne renvoie que les destinataires dans cet état : pending, sending, sent, failed ou skipped.
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.

Erreurs

404Introuvable

Aucune campagne portant cet identifiant n'existe sur ce numéro WhatsApp.

Listez les campagnes du numéro et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/campaigns/:campaign_id/recipients?status=failed' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [
    { "id": "recipient-uuid", "to": "447700900123", "params": ["Alex", "Tuesday at 3pm"], "status": "sent", "message_id": "wamid.HBgM...", "error": null, "sent_at": "2026-08-28T09:20:04Z" },
    { "id": "recipient-uuid", "to": "447700900124", "params": ["Sam", "Tuesday at 4pm"], "status": "failed", "message_id": null, "error": "recipient_not_on_whatsapp", "sent_at": null }
  ],
  "total": 2, "offset": 0, "limit": 50
}

POST/whatsapp-accounts/:account_id/calling

Demander à Meta d'activer les appels pour le numéro, et obtenir sa réponse.

Activer les appels

La connexion d'un numéro demande déjà à Meta d'activer les appels, sauf si quelqu'un les a désactivés dans WhatsApp Manager. Aethex redemande aussi de lui-même quand Meta relève la limite. Utilisez ceci pour redemander plus tôt une fois qu'un numéro refusé par Meta est devenu éligible, ce qui veut le plus souvent dire que sa limite quotidienne de messagerie a atteint 2 000 clients uniques, ou pour un numéro connecté avant que la connexion ne le demande. Un refus de Meta est une réponse, pas une erreur : la réponse est 200 avec calling_enabled: false et la raison dans detail. La réponse est aussi enregistrée sur le numéro dans calling_status. Ce point de terminaison partage le budget par organisation de la connexion des numéros.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

409Conflit

Les appels sont désactivés sur ce déploiement.

Demandez à l'opérateur d'activer les appels WhatsApp (app.whatsapp.callingEnabled dans le chart).

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/calling' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "calling_enabled": false,
  "calling_status": "NOT_SET",
  "detail": "Meta will not switch calling on for this number until its daily messaging limit reaches 2,000 unique customers (it is TIER_250 today); a newly connected number starts at 250. Verify the business in Meta Business Manager and keep messaging from the number, then turn it on with POST /api/v1/whatsapp-accounts/account-uuid/calling."
}

POST/whatsapp-accounts/:account_id/calls/permission

Envoyez la demande que le client doit accepter avant tout appel.

Demander l'autorisation d'appeler

WhatsApp refuse les appels à l'initiative de l'entreprise tant que la personne n'a pas donné son autorisation. Cette route envoie la demande libre, qui ne l'atteint que dans sa fenêtre de 24 heures, et elle ne fait que demander : rien ne l'appelle quand elle accepte. Pour demander *et* appeler dès qu'elle autorise — et pour joindre quelqu'un hors de la fenêtre, avec un modèle — utilisez POST /calls avec permission_template. L'autorisation arrive ensuite sur votre webhook ; un 202 signifie que la demande l'a atteinte, pas qu'elle a accepté.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

tostringrequis
Le numéro du client au format E.164, avec ou sans le + initial.

Erreurs

422Refusé par WhatsApp

WhatsApp a refusé la demande — le plus souvent le numéro n'est pas sur WhatsApp, ou la fenêtre de session de 24 heures est fermée.

Vérifiez que le numéro est bien joignable sur WhatsApp, et demandez l'autorisation dans la fenêtre ouverte par le message du client.

422Appels indisponibles depuis ce numéro

WhatsApp ne permet pas aux entreprises de passer des appels depuis des numéros enregistrés aux États-Unis, au Canada, en Égypte, au Vietnam ou au Nigeria (code: whatsapp_calling_unavailable_in_country). Les personnes peuvent toujours appeler ce numéro.

Appelez depuis un numéro enregistré dans un autre pays. outbound_calling_available sur le numéro l'indique à l'avance.

422Appels désactivés pour ce numéro

Meta a désactivé les appels pour ce numéro (calling_status DISABLED), ou ne les a pas encore activés (NOT_SET, le plus souvent une limite quotidienne de messagerie sous 2 000) (code: whatsapp_calling_off). Personne n'est invité à autoriser un appel qui ne pourrait pas partir.

Activez les appels avec POST /whatsapp-accounts/:account_id/calling (ou dans WhatsApp Manager, sous Numéros de téléphone > Appels). Sous la limite, ils s'activent d'eux-mêmes quand Meta la relève. outbound_calling_available sur le numéro l'indique à l'avance.

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/calls/permission' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+447700900123"}'

202 Réponse

json

{ "message_id": "wamid.HBgM...", "to": "447700900123", "accepted_at": "2026-08-28T09:30:00Z" }

GET/whatsapp-accounts/:account_id/calls/permission

Savoir si vous pouvez appeler quelqu'un maintenant — et sinon, comment demander.

Vérifier l'autorisation d'appel

Interroge WhatsApp, pas un cache : si cette personne a autorisé les appels depuis ce numéro et jusqu'à quand (une autorisation temporaire dure 7 jours), si un appel ou une demande d'appel est permis maintenant au regard des limites de WhatsApp, quand une limite atteinte se libère, et si sa fenêtre de discussion de 24 heures est ouverte — ce qui décide si request_permission peut remplacer un modèle.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
tostringrequis
Le numéro à appeler, au format E.164.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/calls/permission?to=%2B2348030000000' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "to": "+2348030000000", "granted": false, "permanent": false, "expires_at": null,
  "can_call": false, "can_request_permission": true,
  "call_blocked_until": null, "request_blocked_until": null,
  "chat_window_open": false
}

POST/whatsapp-accounts/:account_id/calls

Faites sonner quelqu'un sur WhatsApp maintenant — ou demandez d'abord, et appelez dès qu'il accepte.

Appeler quelqu'un

WhatsApp ne connecte l'appel d'une entreprise qu'à une personne qui l'a autorisée à l'appeler. Si c'est déjà le cas, cette route la fait sonner tout de suite : status vaut ringing, call_id est l'identifiant WhatsApp de l'appel et call_record_id l'enregistrement d'appel Aethex. Sinon, passez permission_template (ou, dans sa fenêtre de 24 heures, request_permission) et une demande d'autorisation d'appel lui est envoyée : status vaut awaiting_permission, request_id désigne la demande, et l'appel part dès qu'elle touche Autoriser. Sans l'un ni l'autre, appeler quelqu'un qui n'a pas donné son accord est refusé plutôt que de lui écrire sans qu'il l'ait demandé. Dans tous les cas, 202 veut dire « ça sonne » ou « c'est demandé », pas « c'est connecté ». Les appels à l'initiative de l'entreprise sont indisponibles depuis des numéros enregistrés aux États-Unis, au Canada, en Égypte, au Vietnam et au Nigeria ; la personne appelée peut se trouver n'importe où.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Corps de la requête

tostringrequis
Le numéro du client au format E.164, avec ou sans le + initial.
agent_idstring (uuid)optionnel
L'agent qui répond quand l'appel aboutit. Par défaut, l'agent associé au numéro.
permission_templateobjectoptionnel
Si la personne n'a pas encore autorisé les appels : un modèle approuvé avec une demande d'autorisation d'appel (name, language et, si besoin, les components d'envoi). Il lui est envoyé, et l'appel part dès qu'elle touche Autoriser. Il l'atteint que sa fenêtre de 24 heures soit ouverte ou non.
request_permissionbooleanoptionnel
Si la personne n'a pas encore autorisé les appels, demander avec le message libre plutôt qu'un modèle. Possible uniquement tant que sa fenêtre de discussion de 24 heures est ouverte.
permission_messagestringoptionnel
La ligne de contexte affichée au-dessus du bouton Autoriser de la demande libre — pourquoi vous voulez appeler.

Erreurs

403Numéro en opposition

to figure sur la liste d'opposition de votre compte. La vérification précède la demande d'autorisation d'appel : la personne n'est donc ni appelée ni contactée par message.

Ne réessayez pas. Retirez le numéro, ou levez l'entrée avec POST /suppressions/{id}/release si elle vous appartient.

422Refusé par WhatsApp

La personne n'a pas autorisé les appels depuis ce numéro et aucun moyen de demander n'a été fourni (detail.code vaut call_permission_required), ou WhatsApp a refusé l'appel.

Passez permission_template (ou request_permission dans sa fenêtre) pour demander et appeler dès l'autorisation. GET /calls/permission indique l'option qui s'applique.

422Requête invalide

Le modèle n'est pas approuvé ou ne contient pas de demande d'autorisation d'appel — ou, avec request_permission, sa fenêtre de 24 heures est fermée.

Utilisez un modèle approuvé dont les composants incluent une demande d'autorisation d'appel. Hors de la fenêtre, un modèle est le seul moyen de demander.

409Conflit

Une demande d'appel à cette personne attend déjà sa réponse.

Attendez sa réponse — detail.request_id désigne la demande — ou retirez-la avec POST /call-requests/:request_id/cancel.

429Limite atteinte

Les limites de WhatsApp sont atteintes pour l'instant : une demande d'appel par personne toutes les 24 heures et deux en 7 jours, ou 100 appels aboutis par jour.

Réessayez après Retry-After, aussi fourni dans detail.retry_at.

404Introuvable

Le numéro n'appartient pas à cet espace de travail, ou aucun agent ne lui est associé.

Renseignez default_agent_id sur le numéro avec PATCH /whatsapp-accounts/:account_id, puis rappelez.

422Appels indisponibles depuis ce numéro

Appelez depuis un numéro enregistré dans un autre pays. outbound_calling_available sur le numéro l'indique à l'avance.

422Appels désactivés pour ce numéro

502Appel abandonné

L'appel a peut-être déjà atteint son téléphone, mais il n'a pas pu être établi de notre côté ; il a donc été raccroché.

Ne réessayez pas tout de suite — cela pourrait l'appeler deux fois, et quatre appels sans réponse d'affilée retirent son autorisation. GET /call-requests et le journal des appels montrent ce qui s'est passé.

503Réessayez

Pas de capacité vocale pour le moment, ou WhatsApp injoignable. Rien n'a été envoyé.

Réessayez après Retry-After secondes ; la même requête peut être renvoyée sans risque.

503Liste d'opposition illisible

La liste d'opposition n'a pas pu être lue : rien n'a été envoyé et aucun appel n'a été passé.

Réessayez après un court délai ; la même requête peut être renvoyée sans risque.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/calls' \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"to": "+2348030000000", "permission_template": {"name": "call_request", "language": "en_US"}}'

202 Réponse

json

// They already allow calls: ringing now.
{ "status": "ringing", "call_id": "wacid.HBgN...", "call_record_id": "call-uuid",
  "request_id": null, "to": "2348030000000", "accepted_at": "2026-09-25T09:31:12Z" }

// They had not: asked, and called the moment they tap Allow.
{ "status": "awaiting_permission", "call_id": null, "call_record_id": null,
  "request_id": "request-uuid", "to": "2348030000000", "accepted_at": "2026-09-25T09:31:12Z" }

GET/whatsapp-accounts/:account_id/call-requests

Toutes les personnes à qui vous avez demandé d'autoriser un appel, et ce qu'est devenue chaque demande.

Lister les demandes d'appel

Les plus récentes d'abord. awaiting_permission — envoyée, en attente de sa réponse ; calling — autorisée, l'appel est en cours de passage ; called — passé, avec call_record_id pour la transcription ; puis declined, expired (pas de réponse à temps : 24 heures, ou le end_at du lot), failed (avec error) ou cancelled. Les demandes envoyées pour un lot portent son batch_id.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
statusstringoptionnel
Uniquement les demandes dans ce statut.
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.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/call-requests?status=awaiting_permission' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "data": [
    { "id": "request-uuid", "to": "+2348030000000", "status": "called",
      "agent_id": null, "batch_id": null, "batch_recipient_index": null,
      "template_name": "call_request", "template_language": "en_US",
      "whatsapp_call_id": "wacid.HBgN...", "call_record_id": "call-uuid", "error": null,
      "expires_at": "2026-09-26T09:31:12Z", "permission_granted_at": "2026-09-25T09:40:02Z",
      "resolved_at": "2026-09-25T09:40:05Z",
      "created_at": "2026-09-25T09:31:12Z", "updated_at": "2026-09-25T09:40:05Z" }
  ],
  "total": 1, "limit": 50, "offset": 0
}

GET/whatsapp-accounts/:account_id/call-requests/:request_id

Une demande d'appel et ce qu'elle est devenue.

Obtenir une demande d'appel

Tout ce que la liste affiche pour une demande : si elle attend encore sa réponse, l'appel qu'elle a passé (call_record_id, pour la transcription), ou pourquoi elle s'est close (error).

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
request_idstring (uuid)requis
L'identifiant de la demande d'appel.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/call-requests/REQUEST_ID' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{ "id": "request-uuid", "to": "+2348030000000", "status": "awaiting_permission",
  "template_name": "call_request", "template_language": "en_US",
  "whatsapp_call_id": null, "call_record_id": null, "error": null,
  "expires_at": "2026-09-26T09:31:12Z", "created_at": "2026-09-25T09:31:12Z" }

POST/whatsapp-accounts/:account_id/call-requests/:request_id/cancel

La retirer : aucun appel ne suit, même si la personne autorise plus tard.

Annuler une demande d'appel

Retire une demande qui attend encore leur réponse. Si la personne touche Autoriser ensuite, rien ne l'appelle — mais son autorisation reste chez WhatsApp, donc un appel ultérieur sonne directement. Une fois autorisée, elle ne peut plus être retirée (409) : l'appel est en cours.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.
request_idstring (uuid)requis
L'identifiant de la demande d'appel.

Erreurs

409Conflit

La personne a déjà autorisé l'appel et il est en cours, ou la demande est déjà passée, refusée, expirée ou annulée.

Il n'y a rien à retirer ; GET /call-requests/:request_id montre ce qu'elle est devenue.

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/call-requests/REQUEST_ID/cancel' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{ "id": "request-uuid", "to": "+2348030000000", "status": "cancelled", "error": "withdrawn" }

GET/whatsapp-accounts/:account_id/health

La vue de Meta sur le numéro plus la nôtre, avec les problèmes expliqués.

État du numéro

quality_rating et messaging_limit_tier viennent de Meta et déterminent si les campagnes sont sûres ; webhook_subscribed confirme que les messages entrants arriveront ; credentials_valid et problems disent quoi corriger, en clair. account_review_status, can_send_message et meta_checks portent le verdict de Meta lui-même : son examen du compte, s'il accepte d'envoyer, et chaque erreur avec la raison, la correction et le code donnés par Meta. Ils sont null ou vides quand Meta n'a pas pu être lu. calling_enabled ne vaut true que si Meta a activé les appels pour le numéro (calling_status, lu en direct à chaque appel) et que ce déploiement autorise les appels ; sinon, problems dit pourquoi.

Chemin & Requête

account_idstring (uuid)requis
L'identifiant du numéro WhatsApp, tel que renvoyé lors de sa connexion.

Erreurs

404Introuvable

Aucun numéro WhatsApp portant cet identifiant n'appartient à votre espace de travail.

Listez vos numéros et reprenez un id de la réponse.

Requête

json

curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/:account_id/health' -H "X-API-Key: YOUR_KEY"

Réponse 200

json

{
  "display_phone_number": "+44 7930 308614", "verified_name": "AethexAI",
  "quality_rating": "GREEN", "messaging_limit_tier": "TIER_1K", "status": "CONNECTED",
  "name_status": "APPROVED", "account_review_status": "APPROVED",
  "platform_type": "CLOUD_API", "throughput_level": "STANDARD",
  "official_business_account": false,
  "webhook_subscribed": true, "credentials_valid": true, "credentials_invalid_since": null,
  "calling_enabled": true, "calling_status": "ENABLED", "open_threads": 12, "waiting_on_human": 1, "undelivered_24h": 0,
  "last_inbound_at": "2026-08-28T09:10:02Z", "last_outbound_at": "2026-08-28T09:10:09Z",
  "can_send_message": "BLOCKED",
  "meta_checks": [
    {
      "entity_type": "WABA", "entity_id": "104882345678901", "can_send_message": "BLOCKED",
      "errors": [
        {
          "code": 141006,
          "description": "There is an error with the payment method. This will block business initiated conversations.",
          "solution": "There was an error with your payment method. Please add a new payment method to the account."
        }
      ],
      "notes": []
    }
  ],
  "checked_at": "2026-08-28T09:31:00Z",
  "problems": [
    "The WhatsApp Business account: There is an error with the payment method. This will block business initiated conversations. There was an error with your payment method. Please add a new payment method to the account. (Meta error 141006)"
  ]
}