API WhatsApp pour les plateformes de chatbot IA : tutoriel 2026

Connecter un chatbot IA à l'API WhatsApp Business demande de maîtriser quatre éléments : la réception des webhooks entrants, l'appel au moteur IA, l'envoi de la réponse via l'API REST et la gestion du contexte de session. Ce tutoriel présente chaque étape de façon concrète, dans l'ordre d'implémentation logique.

Les exemples s'appuient sur l'API REST exposée par un Meta Tech Provider certifié — le chemin le plus rapide pour une plateforme qui veut éviter le processus de certification Meta directe.

Étape 1 : configurer le webhook entrant

Le webhook est le point d'entrée de toute l'intégration. Meta envoie une requête POST à votre endpoint à chaque message reçu par le numéro WhatsApp Business.

Vérification initiale (GET)

Meta vérifie votre endpoint au moment de la configuration avec une requête GET contenant trois paramètres :

GET /webhook?hub.mode=subscribe&hub.verify_token=VOTRE_TOKEN&hub.challenge=CHALLENGE_STRING

Votre serveur doit répondre avec hub.challenge si hub.verify_token correspond à votre token configuré, sinon retourner HTTP 403.

Réception d'un message (POST)

Payload simplifié d'un message texte entrant :

{
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "33612345678",
          "id": "wamid.xxx",
          "text": { "body": "Bonjour, j'ai une question" },
          "type": "text",
          "timestamp": "1722700000"
        }],
        "metadata": {
          "phone_number_id": "PHONE_NUMBER_ID"
        }
      }
    }]
  }]
}

Votre endpoint doit répondre HTTP 200 immédiatement. Si vous tardez à répondre, Meta renvoie le webhook et vous risquez de traiter le même message plusieurs fois. Implémentez une file d'attente (queue) pour le traitement asynchrone.

Étape 2 : appeler le moteur IA

Une fois le message reçu et l'accusé HTTP 200 renvoyé, appelez votre LLM avec le contexte de la conversation.

Structure de session minimale

{
  "session_id": "33612345678",
  "last_activity": 1722700000,
  "history": [
    { "role": "user", "content": "Bonjour, j'ai une question" }
  ]
}

Stockez la session en cache (Redis, DynamoDB…) avec un TTL de 24 h — calé sur la fenêtre de conversation WhatsApp. À chaque message entrant, chargez l'historique, ajoutez le nouveau message, appelez le LLM, puis sauvegardez la réponse dans l'historique.

Points de vigilance LLM

• Limitez l'historique injecté dans le contexte (les derniers 10-15 échanges suffisent pour éviter les tokens excessifs).
• Ajoutez un system prompt qui interdit les formats non compatibles WhatsApp (HTML, Markdown standard).
• Gérez les timeouts : si le LLM met plus de 10 secondes, envoyez d'abord un message "Je prépare votre réponse…" avant d'envoyer la vraie réponse.

Pour comprendre les catégories de templates utiles pour les messages hors-fenêtre, consultez l'article sur les catégories de templates WhatsApp.

Étape 3 : envoyer la réponse via l'API REST

L'envoi d'un message texte simple se fait avec une requête POST :

POST https://api.whakup.com/v1/messages
Authorization: Bearer VOTRE_API_KEY
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "33612345678",
  "type": "text",
  "text": {
    "body": "Bonjour ! Je suis votre assistant. Comment puis-je vous aider ?"
  }
}

Formats supportés à connaître

Type	Usage chatbot	Champ principal
text	Réponse texte standard	text.body (max 4096 car.)
interactive	Boutons de choix rapide	interactive.action.buttons (max 3)
interactive (list)	Menu de sélection	interactive.action.sections
image	Envoi d'image avec légende	image.link ou image.id
document	Envoi de PDF	document.link
template	Message hors fenêtre 24 h	template.name + components

Pour un chatbot IA, les messages interactifs (boutons, listes) sont très utiles pour guider l'utilisateur quand le LLM détecte une intention ambiguë. Ils améliorent le taux de résolution sans augmenter le coût de la conversation.

Étape 4 : déploiement multi-tenant

Si votre plateforme sert plusieurs clients, chacun avec son propre numéro WhatsApp, vous devez router les webhooks entrants par phone_number_id.

Architecture recommandée

Webhook unique → Router → File par phone_number_id → Worker → LLM → API envoi

Avec un Meta Tech Provider comme Whakup, chaque client final peut connecter son propre numéro via l'embedded signup intégré à votre interface. Vous récupérez un phone_number_id distinct par client sans gérer vous-même la vérification Meta.

La solution API WhatsApp de Whakup est conçue pour le multi-tenant : isolation des données par numéro, webhooks configurables par tenant, gestion des quotas d'envoi indépendante par client.

Pour aller plus loin sur le choix entre construire votre propre accès API ou passer par un BSP, lisez build vs buy pour l'API WhatsApp.

Étape 5 : tester et monitorer

Avant de passer en production, validez ces scénarios :

• Message texte simple : réponse dans < 5 s
• Message hors fenêtre 24 h : bascule automatique sur template
• Message avec image : traitement correct du type image
• Double webhook : idempotence sur wamid (l'ID de message Meta)
• Timeout LLM : envoi du message d'attente, puis réponse réelle

En production, loguez systématiquement wamid, phone_number_id, le statut d'envoi (delivered/read) et les erreurs de l'API. Meta renvoie des webhooks de statut (delivery receipts) que vous pouvez utiliser pour mesurer le taux de délivrabilité de votre chatbot.

FAQ

Peut-on utiliser le même endpoint webhook pour plusieurs numéros WhatsApp ?

Oui. Un seul endpoint peut recevoir les webhooks de plusieurs phone_number_id. Votre router identifie le numéro destinataire via entry[0].changes[0].value.metadata.phone_number_id et dispatche vers le bon tenant.

Comment tester sans numéro WhatsApp réel ?

Whakup et Meta proposent un environnement sandbox avec un numéro de test. Vous pouvez envoyer et recevoir des messages depuis votre propre numéro personnel vers ce numéro de test sans frais de conversation.

Que se passe-t-il si le LLM renvoie une réponse vide ou une erreur ?

Prévoyez un fallback : si le LLM échoue, envoyez un message standard ("Je rencontre une difficulté technique, un agent va vous répondre.") et déclenchez une alerte interne. Ne laissez jamais le webhook sans réponse côté utilisateur.

Comment éviter les boucles de messages entre deux chatbots ?

Filtrez les messages dont from est identique à votre phone_number_id. Un message envoyé par votre bot ne doit pas déclencher un nouveau traitement LLM. Vérifiez également le champ type : les statuts de livraison (statuses) ne sont pas des messages entrants.

Conclusion

Ce tutoriel couvre les quatre étapes fondamentales pour connecter un chatbot IA à WhatsApp : réception des webhooks, appel LLM avec gestion de session, envoi de la réponse et déploiement multi-tenant. L'implémentation complète représente environ deux semaines de développement pour une équipe backend expérimentée.

Pour aller plus vite, Whakup fournit l'accès API BSP clé en main avec documentation complète. Demandez votre accès à l'API WhatsApp Whakup et connectez votre premier chatbot IA dès cette semaine.