WhatsApp

Fonctionnement

Connectez un numéro WhatsApp Business une fois et associez-le à un agent. Dès lors, l'agent lit et répond à chaque message reçu par le numéro, transcrit les notes vocales, propose des menus de réponse rapide et voit les accusés de réception. Sur un numéro pour lequel Meta autorise les appels, le même agent décroche quand un client appuie sur le bouton d'appel et peut appeler après avoir demandé la permission.Vous disposez aussi d'une boîte de réception partagée où une personne peut reprendre une conversation puis la rendre, de modèles approuvés pour démarrer des conversations, de campagnes vers une liste, et d'une mémoire par client qui couvre ses discussions et ses appels.

Ce qu'il vous faut

Une entreprise Meta. Votre client se connecte avec un compte Facebook qui administre son portefeuille d'entreprise. S'il n'en a pas, la fenêtre de Meta en crée un au passage.Un numéro qui peut recevoir un code de vérification. Meta envoie un code à six chiffres par SMS ou appel vocal. Le numéro ne doit pas être enregistré dans l'application WhatsApp ou WhatsApp Business à ce moment-là. S'il l'est, supprimez d'abord le compte dans l'application, ou utilisez un numéro libre. Un numéro déjà dans un compte WhatsApp Business chez un autre fournisseur peut être choisi dans la fenêtre et passe chez Aethex.Un agent pour répondre. N'importe quel agent de votre organisation, par son identifiant (un UUID comme 3f6c2a1e-8b4d-4c7a-9e2f-5d1b0a7c6e94 ; listez-les avec GET /agents). Vous pourrez le changer avec PATCH /whatsapp-accounts/{id}.Un moyen de paiement, pour les messages à l'initiative de l'entreprise. Votre client l'ajoute à son compte WhatsApp Business dans WhatsApp Manager. Les réponses dans la fenêtre de 24 heures fonctionnent sans.

Connecter un numéro

Il y a deux façons de connecter un numéro, selon l'application Meta sur laquelle il fonctionne.Sur l'application Meta d'Aethex (la plupart des développeurs). La fenêtre d'inscription de Meta, Embedded Signup, ne s'ouvre que sur les domaines autorisés dans l'application Meta concernée, sans caractère générique. Elle ne peut donc pas s'ouvrir sur votre site avec l'application d'Aethex. À la place, vous créez une session d'inscription et envoyez votre client vers son lien. Une page hébergée par Aethex ouvre la fenêtre de Meta, connecte le numéro à votre organisation et renvoie votre client chez vous. Rien à héberger, aucun webhook à brancher, aucun jeton à manipuler. Les étapes ci-dessous décrivent ce parcours.Sur votre propre application Meta. Si vous êtes fournisseur technologique Meta avec votre propre application et gérez déjà les comptes WhatsApp Business de vos clients, connectez les numéros avec vos propres jetons. Voir Utiliser votre propre application Meta.

1. 01

   Créer une session d'inscription

   Depuis votre backend, appelez POST /whatsapp-accounts/onboarding-sessions avec le return_url où revient votre client (HTTPS), un state opaque à vous, comme l'identifiant de votre client, et l'agent qui doit répondre. La réponse contient url, un lien à usage unique valable 24 heures par défaut (expires_in_seconds, de 5 minutes à 7 jours). url n'est renvoyé qu'ici : traitez-le comme un secret jusqu'à ce que votre client l'utilise. Seule une organisation avec un moyen de paiement enregistré ou une offre payante peut créer des liens ; sinon l'appel renvoie 403 whatsapp_hosted_onboarding_requires_billing. Un 503 avec le code whatsapp_hosted_onboarding_unavailable signifie que l'inscription hébergée n'est pas encore disponible sur ce déploiement ; rien n'a été créé.

   bash

   curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts/onboarding-sessions' \
     -H "X-API-Key: $AETHEX_API_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"}'
   
   # {"id": "b2f0c9e4-...", "status": "pending",
   #  "url": "https://api.aethexai.com/whatsapp/onboarding#k3J...", "expires_at": "2026-10-01T09:00:00Z", ...}

2. 02

   Envoyer votre client vers le lien

   Redirigez-le vers url, ou envoyez-le-lui par e-mail. La page nomme votre organisation, ouvre la fenêtre de Meta, où votre client se connecte avec Facebook et choisit ou crée son entreprise et son numéro, et connecte le numéro dès la fermeture de la fenêtre. En cas d'échec, par exemple un numéro verrouillé par le code PIN d'un autre fournisseur, la page en donne la raison et votre client peut réessayer avec le même lien jusqu'à son expiration. Chaque essai rouvre la fenêtre de Meta : son code est ce qui prouve que votre client contrôle le numéro.

3. 03

   Récupérer le résultat

   Une fois terminé, votre client est envoyé vers return_url avec whatsapp_onboarding_session, status (completed, ou cancelled s'il a choisi de revenir), whatsapp_account_id et votre state. L'URL ne contient aucun secret. Deux confirmations ne dépendent pas du navigateur. Le webhook de l'agent reçoit un événement signé whatsapp.onboarding.completed avec les mêmes identifiants. GET /whatsapp-accounts/onboarding-sessions/{id} renvoie pending (avec la dernière erreur si une tentative a échoué), completed ou expired.

   bash

   # Your customer lands on:
   # https://app.example.com/whatsapp/connected?whatsapp_onboarding_session=b2f0c9e4-...
   #   &status=completed&whatsapp_account_id=9d2e6b7a-...&state=customer-8841
   
   curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/onboarding-sessions/b2f0c9e4-...' -H "X-API-Key: $AETHEX_API_KEY"
   
   # {"status": "completed", "whatsapp_account_id": "9d2e6b7a-...", "state": "customer-8841", ...}

4. 04

   Vérifier le numéro

   GET /whatsapp-accounts/{id}/health lit la vision qu'a Meta du numéro : statut, note de qualité, limite d'envoi, abonnement aux webhooks, et tout problème en clair. Interrogez-le après la connexion et montrez-le à vos utilisateurs.

   bash

   curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/9d2e6b7a-.../health' -H "X-API-Key: $AETHEX_API_KEY"
   
   # {"status": "CONNECTED", "quality_rating": "GREEN", "messaging_limit_tier": "TIER_250",
   #  "webhook_subscribed": true, "calling_enabled": false, "calling_status": "NOT_SET",
   #  "problems": ["Meta will not switch calling on for this number until its daily
   #   messaging limit reaches 2,000 unique customers (it is TIER_250 today); ..."]}

Utiliser votre propre application Meta

Pour un fournisseur technologique Meta qui a sa propre application Meta, avec laquelle ses clients partagent leurs comptes WhatsApp Business. Aethex utilise le numéro avec le jeton de votre application, signe chaque appel avec son secret, et reçoit les messages et appels du numéro sur une URL qui lui est propre. Votre application continue de recevoir tout le reste.

1. 01

   Créer un jeton d'utilisateur système

   Dans Meta Business Manager, créez un utilisateur système dans votre entreprise avec accès au compte WhatsApp Business du client, et générez un jeton pour votre application. Choisissez sans expiration, avec business_management, whatsapp_business_management et whatsapp_business_messaging. Copiez le secret de votre application dans App Dashboard > Paramètres de l'app > Général.

2. 02

   Connecter le numéro avec votre jeton et le secret de l'application

   Appelez POST /whatsapp-accounts avec waba_id, phone_number_id, access_token et app_secret, et registration_pin (six chiffres) si le numéro n'est pas encore enregistré sur la Cloud API. Aethex demande à Meta quelle application a émis le jeton et vérifie que le secret est bien le sien avant de stocker quoi que ce soit. Un mauvais secret échoue avec whatsapp_app_secret_mismatch, et un jeton de votre application envoyé sans son secret échoue avec whatsapp_app_secret_required. Aethex abonne ensuite votre application au compte WhatsApp Business et dirige les messages et appels du numéro vers webhook_callback_url, une URL propre à ce numéro. La réponse affiche webhook_verify_token une seule fois ; Aethex n'en garde qu'une empreinte.

   bash

   curl -X POST 'https://api.aethexai.com/api/v1/whatsapp-accounts' \
     -H "X-API-Key: $AETHEX_API_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"}'
   
   # {"id": "9d2e6b7a-...", "status": "active", "link_method": "byo", "meta_app_id": "1043210987654321",
   #  "webhook_callback_url": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-...",
   #  "webhook_verify_token": "q8Vn...", ...}

3. 03

   Abonner votre application aux messages et aux appels

   Meta n'envoie un webhook que pour un champ auquel votre application est abonnée. Dans App Dashboard > WhatsApp > Configuration, votre application doit avoir un webhook et un abonnement à messages, plus calls si le numéro reçoit des appels. Le callback de votre application reste votre propre serveur : la route posée par Aethex ne concerne que ce numéro. Si votre application n'a pas encore de webhook et que c'est son seul numéro, vous pouvez utiliser webhook_callback_url avec le jeton de vérification de la réponse de connexion, ou un nouveau obtenu avec POST /whatsapp-accounts/{id}/webhook/verify-token. Cette URL ne répond que pour ce numéro : une application avec plusieurs numéros a besoin de son propre callback.

4. 04

   Vérifier le branchement

   GET /whatsapp-accounts/{id}/webhook lit chez Meta où partent réellement les messages du numéro, et à quels champs votre application est abonnée. problems indique ce qui manque. L'endpoint de santé liste les mêmes problèmes.

   bash

   curl 'https://api.aethexai.com/api/v1/whatsapp-accounts/9d2e6b7a-.../webhook' -H "X-API-Key: $AETHEX_API_KEY"
   
   # {"mode": "own_app", "callback_url": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-...",
   #  "required_fields": ["messages", "calls"], "meta_routed_to": "https://api.aethexai.com/whatsapp/webhook/9d2e6b7a-...",
   #  "meta_subscribed_fields": ["messages"], "problems": ["Your Meta app does not subscribe to calls: ..."]}

Ce que vous obtenez

Un seul agent pour la voix et WhatsApp. Il répond aux messages, répond aux appels et en passe lorsque le numéro le permet, et transfère à une personne quand on le lui demande. Le point de terminaison de santé vous donne la vision qu'a Meta du numéro : statut, note de qualité, limite de messagerie actuelle, et tout problème en clair, comme un jeton d'accès rejeté, une note de qualité rouge ou un webhook non abonné.

Messagerie

Réponses. Quand un client écrit, l'agent répond en son nom ; rien n'est requis de votre côté. Meta autorise les réponses libres pendant 24 heures après le dernier message du client. Au-delà, seul un modèle approuvé peut l'atteindre ; c'est ainsi qu'une conversation se démarre plutôt qu'elle ne se poursuit.Les notes vocales sont transcrites et traitées comme du texte. Menus : quand l'agent propose des choix, ils s'affichent comme des boutons de réponse rapide, et POST /whatsapp-accounts/{id}/messages/options vous permet d'en envoyer un vous-même. Accusés : envoyé, distribué et lu sont enregistrés par message et transmis à votre webhook sous whatsapp.message.status.Ce que vous voyez. Chaque conversation est lisible via les points de terminaison de boîte de réception ci-dessous, et votre webhook reçoit whatsapp.message.status pour les accusés, whatsapp.handoff.requested quand un client demande une personne, whatsapp.template.status quand Meta statue sur un modèle, et whatsapp.onboarding.completed quand un client termine un lien d'inscription.Désinscription. Il n'existe pas encore de mot-clé STOP automatique. Un client qui demande à ne plus être contacté est pris en charge par l'agent dans la conversation, et c'est à vous de le retirer des listes de campagne.

Boîte de réception et transfert humain

Chaque client a un fil par numéro. GET /whatsapp-accounts/{id}/threads les liste avec les non-lus et GET …/threads/{thread_id}/messages donne toute la chronologie, discussions et appels compris, dans un seul ordre.Pour qu'une personne reprenne la main, POST …/threads/{thread_id}/mode avec human : l'agent se tait, les nouveaux messages du client sont conservés et signalés par whatsapp.message.received, et votre opérateur répond avec POST …/threads/{thread_id}/messages (texte libre dans la fenêtre de 24 heures) ou …/messages/template à tout moment. Repassez le mode à agent pour reprendre avec tout le contexte. Un client qui demande une personne, avec les formules configurées sur le déploiement, est transféré automatiquement et whatsapp.handoff.requested arrive sur votre webhook.

Modèles et campagnes

Les modèles sont des messages approuvés à l'avance par Meta, avec des variables que vous remplissez à l'envoi. Créez-en un avec POST /whatsapp-accounts/{id}/templates ; listez et supprimez avec GET et DELETE sur le même chemin. La décision de Meta arrive sous whatsapp.template.status, et un modèle approuvé s'envoie avec POST /whatsapp-accounts/{id}/messages, dans ou hors de la fenêtre de 24 heures.Les campagnes envoient un modèle approuvé à une liste. POST /whatsapp-accounts/{id}/campaigns vérifie chaque ligne de destinataire par rapport aux variables du modèle avant tout envoi, l'envoi respecte le rate_per_minute que vous fixez, et vous pouvez mettre en pause, reprendre ou annuler entre deux messages. Chaque destinataire porte son propre statut de distribution. Les campagnes peuvent être planifiées.

Appels

Entrants. Quand les appels sont actifs, les clients voient un bouton d'appel dans la discussion. Une pression fait sonner l'agent, qui répond avec la même voix qu'au téléphone.Sortants. WhatsApp ne connecte l'appel d'une entreprise qu'à une personne qui l'a autorisée à l'appeler, et POST /whatsapp-accounts/{id}/calls gère les deux étapes. Si elle autorise déjà les appels, elle sonne tout de suite. Sinon, passez permission_template — un modèle approuvé avec une demande d'autorisation d'appel — et la demande lui est envoyée ; l'appel part dès qu'elle touche Autoriser. Dans sa fenêtre de 24 heures, request_permission: true demande avec le message libre à la place. Pour appeler toute une liste, envoyez POST /calls/batch avec whatsapp_params. Meta n'autorise pas les appels à l'initiative de l'entreprise depuis des numéros enregistrés au Nigeria, aux États-Unis, au Canada, en Égypte ou au Vietnam ; la personne appelée peut se trouver n'importe où, et les appels entrants fonctionnent partout. Un numéro dont les appels sont désactivés chez Meta est lui aussi refusé d'emblée (whatsapp_calling_off), avant que quiconque soit invité à autoriser un appel qui ne pourrait pas partir.Activer les appels. Les appels sont un interrupteur que Meta garde pour chaque numéro, et Aethex demande à Meta de l'activer dès que le numéro est connecté. Meta n'accepte qu'une fois que la limite quotidienne de messagerie du numéro a atteint 2 000 clients uniques. Un numéro nouvellement connecté démarre à 250 et progresse à mesure que l'entreprise est vérifiée et que le numéro continue d'écrire : sur un nouveau numéro, la connexion réussit, la messagerie fonctionne, et calling_enabled sur le numéro vaut false tant que la limite n'a pas progressé ; le point de terminaison de santé dit pourquoi. Quand Meta relève la limite à 2 000 ou plus, Aethex active de lui-même les appels sur chaque numéro qui ne les a jamais eus ; un numéro où quelqu'un les a désactivés le reste. Pour redemander plus tôt, utilisez POST /whatsapp-accounts/{id}/calling : la réponse de Meta revient aussitôt.

Une seule mémoire pour les discussions et les appels

L'agent se souvient de chaque client d'un numéro à travers tout ce qu'il a fait avec lui, à l'écrit comme à l'oral. Un appel s'ouvre dans la continuité de la discussion, et un message envoyé pendant ou juste après un appel voit ce qui s'y est dit, y compris le résultat de ce que l'agent a réservé. La mémoire est propre à un agent et à un numéro : pointer le numéro vers un autre agent repart de zéro, et la même personne sur deux de vos numéros compte pour deux clients.

Ce que Meta contrôle

Trois choses relèvent de Meta, pas d'Aethex.La vérification de l'entreprise dans Meta Business Manager relève la limite d'envoi et conditionne les appels. La limite actuelle figure dans la réponse de santé.Un moyen de paiement sur le compte WhatsApp Business. Meta facture directement chaque entreprise ; sans moyen de paiement, les modèles et campagnes sont refusés, et la réponse de santé l'indique dans problems comme erreur Meta 141006. Aethex, en tant que fournisseur technologique Meta, n'a pas de ligne de crédit à partager : chaque entreprise ajoute le sien dans WhatsApp Manager.La note de qualité, que Meta déduit des réactions des clients. Une note rouge abaisse la limite et apparaît comme problème dans la réponse de santé.

Code PIN de vérification en deux étapes

Chaque numéro WhatsApp Business porte un code PIN de vérification en deux étapes à six chiffres, et Meta le demande à chaque enregistrement du numéro.Quand Aethex connecte un numéro, il définit ce code PIN et le conserve, chiffré, même après la déconnexion du numéro. Votre organisation peut déconnecter un numéro et le reconnecter sans aucune étape supplémentaire.Le code PIN reste sur le numéro quand il part, et Aethex ne transmet jamais le code PIN d'une organisation à une autre. Si le numéro a été connecté en dernier par une autre organisation ou un autre fournisseur, ou si quelqu'un a défini le code PIN dans WhatsApp Manager, la connexion échoue avec un message qui renvoie ici.Pour corriger cela, le propriétaire du numéro désactive la vérification en deux étapes. Dans WhatsApp Manager, depuis Meta Business Manager, ouvrez Numéros de téléphone, sélectionnez le numéro, ouvrez Vérification en deux étapes, puis désactivez-la. Connectez ensuite le numéro à nouveau : Aethex définit un nouveau code PIN pendant la connexion. Changer le code PIN ne suffit pas, car Aethex connecte le numéro avec son propre code PIN. Meta l'exige chaque fois qu'un numéro change d'entreprise ou de fournisseur, et seul le propriétaire peut le faire.

Dépannage

La plupart des problèmes sont visibles sur la page du numéro, dans la section santé. problems liste d'abord les raisons données par Meta, chacune avec la correction proposée par Meta et son code d'erreur, puis ce qu'Aethex vérifie lui-même ; meta_checks donne le même détail par entité (numéro, compte WhatsApp Business, entreprise). Voici les cas les plus fréquents.

Référence API

Pour les appels de connexion, de modèles, de messagerie, de boîte de réception, d'appels et de campagnes, voir la référence API WhatsApp. Les événements émis par le canal sont listés sous Webhooks.