WhatsApp-Webhooks

Bird sendet WhatsApp-Aktivität in Echtzeit an Ihren Endpunkt, sodass Sie nicht danach abfragen müssen. Abonnieren Sie über die Seite Webhooks oder mit POST /v1/webhooks. Der Webhooks-Leitfaden behandelt Endpunkte, Signaturverifizierung und Wiederholungsversuche.

Events, die Sie abonnieren können

Jedes Event verlinkt auf seinen Payload.

Die Liste der Event-Typen ist offen: Neue Typen können im Laufe der Zeit hinzukommen. Behandeln Sie einen unbekannten Wert als zukünftiges Event und nicht als Fehler.

Der Event-Umschlag

Jedes WhatsApp-Event verwendet den Standard-Webhook-Umschlag: ein type, ein timestamp und ein typspezifisches data-Objekt.

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

Felder, die jedes Nachrichten-Event enthält

Jeder WhatsApp-Webhook-Payload für eine Nachricht enthält whatsapp_id, workspace_id, direction, from, to, tags und metadata. Die Reaktions-, Unterdrückungs- und Gruppen-Events beziehen sich nicht auf eine Nachricht und haben jeweils eine eigene Struktur, die auf ihrer Seite beschrieben ist.

• Adressen: from und to können eine E.164-phone_number, eine Meta-Business-scoped User ID in bsuid oder beides enthalten. Eine Nachricht von einem WhatsApp-Nutzer enthält außerdem das veröffentlichte Profil in username und display_name.
• tags und metadata sind null, wenn beim Senden keine angegeben wurden.
• in_reply_to_message_id erscheint bei jedem ausgehenden Event einer als Antwort gesendeten Nachricht, von whatsapp.accepted über whatsapp.read, whatsapp.failed oder whatsapp.rejected, und benennt die Nachricht, auf die geantwortet wird.

Event-Payloads enthalten keine Kosten. Rufen Sie die Nachricht mit GET /v1/whatsapp/messages/{message_id} ab, um die Kosten einzusehen.

Nächste Schritte

• Nachrichtenstatus-Webhooks: Zustellungs- und Fehler-Payloads
• Eingehende-Nachrichten-Webhooks: der whatsapp.received-Payload
• Reaktions-Webhooks: der whatsapp.reacted-Payload
• Webhooks-Leitfaden: Endpunkte, Signaturen, Wiederholungsversuche und der vollständige Event-Katalog