WhatsApp-Nachrichtenstatusereignisse
Bird zeichnet Events für eingehende und ausgehende WhatsApp-Nachrichten auf. Eine ausgehende Timeline zeigt, was nach dem Senden mit Rückgabe von 202 passiert ist: Annahme, Übergabe an WhatsApp, Zustellung, Lesebestätigung oder Fehlschlag. Eine eingehende Timeline erfasst, wann Bird die Nachricht empfangen hat.
Diese Seite behandelt das Auslesen dieser Zeitleiste über die API. Wenn Bird jedes Ereignis beim Eintreten an Ihren Endpunkt senden soll, lesen Sie Nachrichtenstatus-Webhooks. Reaktionen haben eine eigene Historie, beschrieben unter Reaktionsereignisse.
Lifecycle-Events
Events erscheinen in chronologischer Reihenfolge. Eine ausgehende Nachricht kann bei whatsapp.failed oder whatsapp.rejected enden, und das whatsapp.read-Event erscheint nur, wenn der Empfänger die Nachricht öffnet. Eine eingehende Timeline beginnt mit whatsapp.received und kann whatsapp.read aufzeichnen, nachdem Ihr Workspace die Nachricht als gelesen markiert hat.
| Event | Bedeutung |
|---|---|
| whatsapp.accepted | Bird hat die Sendeanfrage angenommen. Das ist, was die 202 gemeldet hat. |
| whatsapp.sent | Bird hat die Nachricht an das WhatsApp-Netzwerk übergeben. |
| whatsapp.delivered | WhatsApp hat die Zustellung an das Gerät des Empfängers bestätigt. |
| whatsapp.read | Der Empfänger hat die Nachricht geöffnet. |
| whatsapp.failed | Die Nachricht wurde nicht zugestellt. error.code gibt an, was sie aufgehalten hat. |
| whatsapp.rejected | Bird hat die Nachricht vor dem Versand abgelehnt. Sie wurde nicht berechnet. |
| whatsapp.received | Bird hat eine eingehende Nachricht von einem Kontakt empfangen. |
Zutreffende delivered- oder read-Callbacks können Metas Preisanteil auslösen. WhatsApp-Event-Payloads enthalten keine Kosten. Lesen Sie die Nachricht mit GET /v1/whatsapp/messages/{message_id} zurück, um die Kosten zu sehen. Siehe Kosten und Abrechnung.
Eine eingehende Nachricht als gelesen markieren zeichnet whatsapp.read in der Timeline auf, löst aber keinen Lesebestätigungs-Webhook aus. Die eingehende Nachricht behält ihren received-Status und zeichnet read_at auf, nachdem WhatsApp die Bestätigung akzeptiert hat.
whatsapp.read ändert den Nachrichten-status nicht. Eine zugestellte Nachricht bleibt delivered; die Nachricht zeichnet die Lesebestätigung zusätzlich in read_at auf.
whatsapp.delivered kann vollständig übersprungen werden. Wenn der Empfänger den Chat bereits auf seinem Gerät geöffnet hat, meldet Meta die Lesebestätigung, ohne jemals eine Zustellung zu melden. Die Timeline lautet dann whatsapp.accepted → whatsapp.sent → whatsapp.read ohne whatsapp.delivered dazwischen. Behandeln Sie read als Zustellnachweis: Ein Consumer, der auf delivered wartet, bevor er die Nachricht als zugestellt betrachtet, blockiert genau bei den Empfängern, die sie am schnellsten gesehen haben, und einer, der die Zustellrate nur aus delivered berechnet, unterschätzt sie. Der Nachrichten-status bleibt in diesem Fall sent, da nur eine Zustellbestätigung ihn weiterschaltet.
Ein reiner Lese-Callback kann trotzdem die zutreffende Meta-Gebühr auslösen. Bird verwendet eine einzige Gebührenidentität über die Zustell- und Lesepfade hinweg; das fehlende Zustellungs-Event bedeutet keine kostenlose Meta-Komponente. Siehe Kosten und Abrechnung.
Die Event-Typ-Liste ist offen: Neue Typen können im Laufe der Zeit hinzukommen. Behandeln Sie einen unbekannten Wert als zukünftiges Event, nicht als Fehler.
Fehlschlag-Events
whatsapp.failed und whatsapp.rejected sind terminal. Eine Ablehnung bedeutet, dass Bird die Nachricht vor dem Versand an WhatsApp gestoppt hat, sodass sie nicht berechnet wurde. Ursachen sind unter anderem ein unterdrückter oder abgemeldeter Empfänger, unzureichendes Wallet-Guthaben oder ein Ziel ohne konfigurierten Preis. Ein Fehlschlag bedeutet, dass die Nachricht nicht zugestellt wurde, und error.code gibt an, wer das entschieden hat. Die meisten Codes enthalten das Urteil von WhatsApp, abgeleitet aus dem gemeldeten Code. internal_error ist die Ausnahme: Es erfasst fehlende nutzbare Absender-Credentials oder erschöpfte Verarbeitungsversuche. Ein unsicherer Transportversuch beweist nicht, dass Meta die Anfrage nie erhalten hat. meta_error_code enthält den Code von WhatsApp, wenn verfügbar, und ein internal_error-Fehlschlag hat konstruktionsbedingt keinen.
Beide Events enthalten ein error-Objekt mit einem stabilen Bird code, einer menschenlesbaren description, einem optionalen meta_error_code und occurred_at. Das Objekt erscheint in API-Einträgen und Webhook-Payloads nur für diese Event-Typen.
Events aus der API lesen
GET /v1/whatsapp/messages/{message_id}/events gibt die Timeline in chronologischer Reihenfolge zurück. Die begrenzte Liste ist nicht paginiert. Das Lesen von Events erfordert einen API-Schlüssel mit whatsapp:read:
const { data } = await bird.whatsapp.listEvents("wa_abc123");
for (const event of data) console.log(event.type, event.occurred_at);events = client.whatsapp.list_events("wa_abc123")
for event in events.data:
print(event.type, event.occurred_at)events, err := client.Whatsapp.ListEvents(context.Background(), "wam_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappListEventsParams{})
if err != nil {
log.Fatal(err)
}
for _, e := range events.Data {
fmt.Println(e.Id, e.Type)
}$events = $bird->whatsapp->listEvents('wamid_01krdgeqcxet5s7t44vh8rt9mg');
foreach ($events->getData() ?? [] as $event) {
echo $event->getType(), ' ', $event->getId(), "\n";
}bird whatsapp list-events <message-id>curl https://us1.platform.bird.com/v1/whatsapp/messages/wam_.../events \
-H "Authorization: Bearer $BIRD_API_KEY"Eine Nachricht, die angenommen, gesendet, zugestellt und gelesen wurde, gibt vier Events zurück:
Codebeispiel
{
"data": [
{
"id": "ev_01ky7q6a1fejfbvs0myn41hj41",
"occurred_at": "2026-07-23T14:48:34.71Z",
"type": "whatsapp.accepted"
},
{
"id": "ev_01ky7q6a2denvtd6jg1vqwmg13",
"occurred_at": "2026-07-23T14:48:35.671Z",
"type": "whatsapp.sent"
},
{
"id": "ev_01ky7q6a2zff9r2qm74mmg1g6z",
"occurred_at": "2026-07-23T14:48:36.642Z",
"type": "whatsapp.delivered"
},
{
"id": "ev_01ky7q6c21frssf0vj8h50qysw",
"occurred_at": "2026-07-23T14:48:38.65Z",
"type": "whatsapp.read"
}
]
}Übergeben Sie type, um genau einen öffentlichen Event-Typ zurückzugeben, z. B. ?type=whatsapp.failed oder ?type=whatsapp.read. Lassen Sie ihn weg, um die vollständige Timeline zu erhalten.
Dieselbe Timeline zeigt die Seite WhatsApp-Protokoll an, wenn Sie eine Nachricht öffnen.
Nächste Schritte
- Nachrichtenstatus-Webhooks: jedes Ereignis beim Eintreten empfangen
- Reaktions-Events: Aktuelle Reaktionen und das Reaktionsprotokoll lesen
- Nachricht als gelesen markieren: Eine eingehende Nachricht bestätigen und Tipp-Indikator anzeigen
- WhatsApp-Protokoll: Die Ansicht pro Nachricht, die diese Timeline darstellt
- WhatsApp-Nachrichten senden: Wo der Lifecycle einer Nachricht beginnt
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten