Webhooks WhatsApp

Bird envoie l'activité WhatsApp à votre endpoint dès qu'elle se produit, ce qui vous évite de l'interroger régulièrement. Abonnez-vous depuis la page Webhooks ou avec POST /v1/webhooks. Le guide Webhooks couvre les endpoints, la vérification de signature et les nouvelles tentatives.

Événements auxquels vous pouvez vous abonner

Chaque événement renvoie vers son payload.

La liste des types d'événements est ouverte : de nouveaux types peuvent apparaître au fil du temps. Traitez une valeur non reconnue comme un événement futur plutôt que comme une erreur.

L'enveloppe d'événement

Chaque événement WhatsApp utilise l'enveloppe webhook standard : un type, un timestamp et un objet data propre au type.

{
  "data": {
    "direction": "outbound",
    "from": { "phone_number": "+13124495569" },
    "metadata": { "session_id": "sess_4821" },
    "tags": [{ "name": "flow", "value": "login-otp" }],
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:39.913Z",
  "type": "whatsapp.delivered"
}

Champs présents dans tout événement de message

Chaque payload webhook WhatsApp pour un message contient whatsapp_id, workspace_id, direction, from et to. Les événements de réaction, de suppression et de groupe ne concernent pas un message : chacun a donc sa propre structure, décrite sur sa page.

• Adresses : from et to peuvent inclure un phone_number E.164, un identifiant utilisateur à portée business Meta dans bsuid, ou les deux. Un message reçu d'un utilisateur WhatsApp contient aussi le profil qu'il publie, dans username et display_name.
• tags et metadata apparaissent sur chaque événement d'un message que vous avez envoyé. Ils reprennent les valeurs de la requête d'envoi et valent null quand celle-ci n'en comportait pas. Un payload whatsapp.received ne contient ni l'un ni l'autre, car un message reçu n'a pas de requête d'envoi.
• in_reply_to_message_id apparaît sur chaque événement sortant d'un message envoyé en réponse, de whatsapp.accepted à whatsapp.read, whatsapp.failed ou whatsapp.rejected, en nommant le message auquel il répond.

Les payloads d'événement ne contiennent pas de coût. Récupérez le message avec GET /v1/whatsapp/messages/{message_id} pour voir ce qu'il a coûté.

Étapes suivantes

• Webhooks de statut de message : payloads de livraison et d'échec
• Webhooks de message entrant : le payload whatsapp.received
• Webhooks de réaction : le payload whatsapp.reacted
• Guide Webhooks : endpoints, signatures, nouvelles tentatives et catalogue complet des événements