WhatsApp-Nachrichtenstatus-Webhooks

Jede Änderung im Status einer ausgehenden Nachricht kann in Echtzeit an Ihren Endpoint gepusht werden. Jeder Payload verwendet den WhatsApp-Event-Envelope und enthält die Felder, die jedes Nachrichten-Event mitführt.

Zustellungs-Events

whatsapp.accepted, whatsapp.sent, whatsapp.delivered und whatsapp.read enthalten nur die Felder, die jedes Nachrichten-Event enthält. Der Leitfaden Nachrichtenstatus-Events erklärt die Bedeutung jedes Events und wann whatsapp.delivered übersprungen wird.

{
  "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 und whatsapp.rejected enthalten zusätzlich ein error-Objekt mit einem stabilen Bird code, einem lesbaren description, einem optionalen meta_error_code und occurred_at. Unter Failure-Events erfahren Sie, worin sich beide unterscheiden. Bei einem gemeldeten Failure WhatsApp ist description die eigene Erklärung von WhatsApp. Eine Service-Nachricht, deren Kundenservice-Fenster zwischen Annahme und Versand geschlossen wurde, schlägt so fehl:

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

Eine eingehende Nachricht als gelesen markieren erfasst whatsapp.read in der Timeline der Nachricht, löst aber keinen Webhook aus.

Nächste Schritte

• Webhooks für eingehende Nachrichten: verarbeiten Sie Nachrichten Ihrer Kontakte
• Reaktions-Webhooks: verarbeiten Sie die Emoji-Reaktionen eines Kontakts
• Webhooks-Leitfaden: konfigurieren Sie Endpunkte, prüfen Sie Signaturen und verarbeiten Sie erneute Zustellversuche