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 contiennent uniquement les champs communs à tous les événements de message. Le guide Événements de statut des messages explique leur signification et dans quels cas whatsapp.delivered est omis.

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

{
  "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 messages entrants: traitez les messages de vos contacts
• Webhooks de réactions: traitez les réactions emoji d’un contact
• Guide des webhooks: configurez les endpoints, vérifiez les signatures et gérez les nouvelles tentatives