API WhatsApp et les webhooks : guide pour les plateformes de chatbot IA

Les webhooks de l'API WhatsApp Business sont le mécanisme par lequel Meta pousse en temps réel les événements de messagerie vers votre plateforme : messages entrants, statuts de livraison, mises à jour de compte. Pour une plateforme de chatbot IA, les webhooks ne sont pas une option — ils sont le cœur de l'architecture. Sans webhooks correctement configurés et traités, votre chatbot ne peut pas recevoir les messages des utilisateurs ni savoir si ses réponses ont été délivrées.

La structure des webhooks WhatsApp : ce que Meta envoie

Meta envoie tous les événements vers une seule URL webhook configurée au niveau du WABA. Le payload est un objet JSON avec une structure commune :

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "<WABA_ID>",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "33612345678",
          "phone_number_id": "<PHONE_NUMBER_ID>"
        },
        "contacts": [...],
        "messages": [...],
        "statuses": [...]
      },
      "field": "messages"
    }]
  }]
}

Les trois types d'événements principaux :

Type	Champ	Contenu
Message entrant	messages	Texte, image, audio, vidéo, document, location, réaction, template reply
Statut de message	statuses	sent, delivered, read, failed
Mise à jour compte	account_update	Changement de quality rating, de tier, ban de numéro

Pour un chatbot IA, les événements messages sont critiques. Chaque message entrant contient : l'ID du contact (from), le type de message (type), le contenu, et un context si c'est une réponse à un message spécifique.

Architecture de traitement des webhooks pour un chatbot IA

Les webhooks WhatsApp exigent une réponse HTTP 200 dans les 5 secondes après réception. Si Meta ne reçoit pas de 200 dans ce délai, il réessaie jusqu'à 24 heures. Pour un chatbot IA dont le traitement peut prendre plusieurs secondes (inférence LLM, appel API externe), cette contrainte impose un pattern asynchrone :

Pattern recommandé :

1. Endpoint webhook : reçoit le payload Meta, répond 200 immédiatement, publie l'événement dans une file de messages (Redis, SQS, RabbitMQ, ou équivalent).
2. Worker de traitement : consomme la file, parse le message, appelle le moteur IA, construit la réponse.
3. Envoi de la réponse : le worker appelle l'API WhatsApp pour envoyer le message de réponse au contact.

Ce qu'il ne faut pas faire : appeler le LLM dans l'handler webhook synchrone. Un timeout entraîne des retries Meta, des doublons de messages dans la file, et une dégradation de l'expérience utilisateur.

Idempotence : Meta peut envoyer le même événement plusieurs fois (retries). Votre système doit dédupliquer sur le message_id avant tout traitement. Stocker les IDs traités pendant 24h suffit.

Gestion des types de messages entrants pour un chatbot

Un chatbot IA robuste doit gérer tous les types de messages entrants, pas seulement le texte :

Messages texte (type: text) :

• Contenu dans message.text.body.
• Le cas le plus fréquent — à diriger vers votre pipeline NLP/LLM.

Messages média (type: image, audio, document, video) :

• Contient un media_id à télécharger via l'API Graph avant traitement.
• Pour un chatbot multimodal : envoyer l'image au modèle de vision, transcrire l'audio avant analyse.
• Les médias ne sont disponibles en téléchargement que pendant 30 jours après réception.

Messages interactifs (type: interactive) :

• Réponses à des boutons (button_reply) ou à des listes (list_reply).
• Contient un button_id ou list_reply.id prédéfini — idéal pour les flux guidés sans NLP.

Réactions (type: reaction) :

• Un emoji envoyé en réaction à un message spécifique.
• Peut signaler une satisfaction (🙏, 👍) ou une insatisfaction (👎) — utile pour le scoring de satisfaction.

Messages de localisation (type: location) :

• Coordonnées GPS envoyées par le contact.
• Utile pour les chatbots de livraison, de réservation, ou de recherche de point de vente.

Sécuriser et monitorer les webhooks

Vérification de signature : chaque webhook Meta inclut un header X-Hub-Signature-256 contenant un HMAC-SHA256 du payload signé avec votre app_secret. Valider cette signature à chaque requête est obligatoire pour rejeter les requêtes forgées.

Validation du token : lors de la configuration initiale, Meta envoie un GET sur votre endpoint avec un hub.challenge à retourner. Votre endpoint doit gérer ce handshake.

Monitoring en production :

• Alerter si le taux d'erreurs 5xx sur l'endpoint webhook dépasse 1% (Meta arrête les retries après 24h de failures).
• Monitorer la latence de traitement : un backlog qui s'accumule indique un worker sous-dimensionné.
• Logger tous les message_id reçus et les timestamps de traitement pour debug.

Pour approfondir les aspects d'intégration technique, consultez notre guide complet de l'API WhatsApp Business et notre page sur l'API WhatsApp pour éditeurs.

Whakup expose des webhooks normalisés et fiables, avec retry automatique en cas d'indisponibilité temporaire de votre endpoint. Notre infrastructure EU/RGPD assure que les données de messagerie ne transitent pas hors Europe. Consultez notre comparatif pour évaluer les options de BSP WhatsApp en France.

FAQ

Peut-on configurer plusieurs URLs webhook pour le même WABA ?

Non. Meta accepte une seule URL webhook par application Meta (App ID). Si vous gérez plusieurs clients sur le même App ID, tous leurs événements arrivent sur la même URL — votre système doit router les événements en fonction du phone_number_id ou du waba_id présent dans le payload.

Comment tester les webhooks en développement sans exposer un endpoint public ?

Utilisez un outil de tunnel (ngrok, cloudflared) pour exposer votre endpoint local. Meta propose aussi un mode de test dans le WhatsApp Manager qui permet d'envoyer des messages de test depuis un numéro sandbox sans exposer de numéro réel. Pour les pipelines CI/CD, intégrez un mock webhook dans vos tests unitaires.

Meta renvoie-t-il les webhooks si mon endpoint est en erreur pendant plusieurs heures ?

Oui, Meta réessaie les webhooks en erreur pendant 72 heures avec un backoff exponentiel. Après 72h sans 200, les événements sont abandonnés. Pour les messages importants (transactions, confirmations), prévoir un mécanisme de réconciliation qui interroge l'API Graph pour les messages non reçus.

Comment distinguer un message entrant d'un statut de livraison dans le payload ?

Dans l'objet value, les messages entrants sont dans le tableau messages et les statuts dans le tableau statuses. Les deux peuvent être présents dans le même payload. Votre handler doit traiter les deux tableaux indépendamment, sans supposer qu'un seul est présent.

---

Les webhooks sont la fondation d'un chatbot WhatsApp IA performant. Une architecture bien pensée — réponse immédiate, traitement asynchrone, idempotence — garantit une expérience fluide pour vos utilisateurs finaux et une fiabilité sans défaillance. Whakup fournit l'infrastructure webhook pour que vous puissiez vous concentrer sur la logique IA. Parlons de votre projet chatbot.