Webhooks de statut de message WhatsApp

Chaque changement de statut d'un message sortant peut être envoyé à votre endpoint au moment où il se produit. Chaque payload utilise l'enveloppe d'événement WhatsApp et contient les champs communs à tous les événements de message.

Événements de livraison

whatsapp.accepted, whatsapp.sent, whatsapp.delivered et whatsapp.read ne contiennent que les champs communs à tous les événements de message. Événements de cycle de vie explique la signification de chacun et quand whatsapp.delivered est ignoré.

Exemple de code

{
  "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"
}

whatsapp.failed et whatsapp.rejected contiennent également un objet error avec un Bird code stable, un description lisible, un meta_error_code optionnel et occurred_at. Consultez les événements d'échec pour comprendre ce qui distingue les deux. Lors d'un échec signalé par WhatsApp, description est l'explication propre à WhatsApp. Un message de service dont la fenêtre de service client s'est fermée entre l'acceptation et l'envoi échoue de cette façon :

Exemple de code

{
  "data": {
    "direction": "outbound",
    "error": {
      "code": "service_window_expired",
      "description": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
      "meta_error_code": "131047",
      "occurred_at": "2026-07-23T14:51:40.201Z"
    },
    "from": { "phone_number": "+13124495569" },
    "metadata": null,
    "tags": null,
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:40.201Z",
  "type": "whatsapp.failed"
}

Marquer un message entrant comme lu enregistre whatsapp.read dans la chronologie du message, mais ne déclenche pas de webhook.

Étapes suivantes

Webhooks de message entrant : le payload whatsapp.received pour un message qu'un contact vous envoie
Webhooks de réaction : les réactions d'un contact arrivent séparément
Événements de statut de message : consultez la chronologie d'un message via l'API

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

Essayez la pratique et obtenez un guide d'implémentation