Webhooks WhatsApp

Bird envoie l'activité WhatsApp à votre endpoint en temps réel, ce qui vous évite de l'interroger. Abonnez-vous depuis la page Webhooks ou avec POST /v1/webhooks. Le guide Webhooks couvre les endpoints, la vérification de signature et les réessais.

É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, to, tags et metadata. Les événements de réaction, de suppression et de groupe ne concernent pas un message : chacun a 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 sont null quand l'envoi n'en comportait pas.
• 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 : charges utiles de livraison et d'échec
• Webhooks de message entrant : la charge utile whatsapp.received
• Webhooks de réaction : le payload whatsapp.reacted
• Guide des webhooks : points de terminaison, signatures, réessais et catalogue complet des événements