WhatsApp berichtstatusgebeurtenissen
Bird registreert events voor inkomende en uitgaande WhatsApp-berichten. Een uitgaande tijdlijn toont wat er gebeurde nadat een verzending 202 retourneerde: acceptatie, overdracht aan WhatsApp, bezorging, lezing of fout. Een inkomende tijdlijn registreert wanneer Bird het bericht ontving.
Deze pagina behandelt het uitlezen van die tijdlijn via de API. Wil je dat Bird elke gebeurtenis naar je endpoint pusht zodra die plaatsvindt, zie dan berichtstatus-webhooks. Reacties hebben een eigen historie, beschreven in Reactiegebeurtenissen.
Lifecycle-events
Events verschijnen in chronologische volgorde. Een uitgaand bericht kan stoppen bij whatsapp.failed of whatsapp.rejected, en het whatsapp.read-event verschijnt alleen als de ontvanger het bericht opent. Een inkomende tijdlijn begint met whatsapp.received en kan whatsapp.read registreren nadat je werkruimte het bericht als gelezen markeert.
| Event | Betekenis |
|---|---|
| whatsapp.accepted | Bird heeft het verzendverzoek geaccepteerd. Dit is wat de 202 rapporteerde. |
| whatsapp.sent | Bird heeft het bericht overgedragen aan het WhatsApp-netwerk. |
| whatsapp.delivered | WhatsApp heeft bezorging op het apparaat van de ontvanger bevestigd. |
| whatsapp.read | De ontvanger heeft het bericht geopend. |
| whatsapp.failed | Het bericht is niet bezorgd. error.code geeft aan wat het tegenhield. |
| whatsapp.rejected | Bird heeft het bericht geweigerd vóór verzending. Er zijn geen kosten in rekening gebracht. |
| whatsapp.received | Bird heeft een inkomend bericht van een contact ontvangen. |
Toepasselijke delivered- of read-callbacks kunnen het Meta-aandeel van de prijs activeren. WhatsApp-event-payloads bevatten geen kosten. Lees het bericht terug met GET /v1/whatsapp/messages/{message_id} om te zien wat het kostte. Zie Kosten en facturering.
Een inkomend bericht als gelezen markeren registreert whatsapp.read in de tijdlijn, maar verstuurt geen read-acknowledgement-webhook. Het inkomende bericht behoudt zijn received-status en registreert read_at nadat WhatsApp de bevestiging accepteert.
whatsapp.read verandert de bericht-status niet. Een bezorgd bericht blijft delivered; het bericht registreert de lezing ook in read_at.
whatsapp.delivered kan volledig worden overgeslagen. Wanneer de ontvanger de chat al open heeft op het apparaat, rapporteert Meta de lezing zonder ooit een bezorging te rapporteren, zodat de tijdlijn whatsapp.accepted → whatsapp.sent → whatsapp.read toont zonder whatsapp.delivered ertussen. Behandel read als bewijs van bezorging: een consumer die wacht op delivered voordat hij het bericht als aangekomen beschouwt, blijft hangen bij precies de ontvangers die het het snelst zagen, en een consumer die een bezorgpercentage berekent op basis van alleen delivered rapporteert te laag. De bericht-status blijft in dit geval sent, omdat alleen een bezorgbevestiging deze doorschuift.
Een read-only callback kan alsnog de toepasselijke Meta-kosten activeren. Bird gebruikt één kostenidentiteit voor zowel het bezorgd- als het gelezen-pad; het ontbrekende bezorgevent impliceert geen gratis Meta-component. Zie Kosten en facturering.
De lijst met eventtypen is open: nieuwe typen kunnen in de loop van de tijd worden toegevoegd, dus behandel een niet-herkende waarde als een toekomstig event in plaats van een fout.
Fout-events
whatsapp.failed en whatsapp.rejected zijn terminaal. Een rejection betekent dat Bird het bericht stopte vóór verzending naar WhatsApp, dus er zijn geen kosten in rekening gebracht. Oorzaken zijn onder meer een onderdrukte of uitgeschreven ontvanger, onvoldoende walletsaldo of een bestemming zonder geconfigureerde prijs. Een failure betekent dat het bericht niet is bezorgd, en error.code geeft aan wie dat besliste. De meeste codes bevatten het oordeel van WhatsApp, afgeleid van de gerapporteerde code. internal_error is de uitzondering: het registreert een ontbrekende bruikbare afzendercredential of uitgeputte verwerkingspogingen. Een onzekere transportpoging bewijst niet dat Meta het verzoek nooit heeft ontvangen. meta_error_code bevat de code van WhatsApp indien beschikbaar, en een internal_error-failure heeft er per definitie geen.
Beide events bevatten een error-object met een stabiele Bird code, een leesbare description, een optionele meta_error_code en occurred_at. Het object verschijnt in API-records en webhook-payloads alleen voor deze eventtypen.
Events uitlezen uit de API
GET /v1/whatsapp/messages/{message_id}/events retourneert de tijdlijn in chronologische volgorde. De begrensde lijst is niet gepagineerd. Events uitlezen vereist een API-sleutel met 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"Een bericht dat geaccepteerd, verzonden, bezorgd en gelezen is, retourneert vier events:
Codevoorbeeld
{
"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"
}
]
}Geef type mee om één exact publiek eventtype te retourneren, zoals ?type=whatsapp.failed of ?type=whatsapp.read. Laat het weg voor de volledige tijdlijn.
Dezelfde tijdlijn is wat de WhatsApp-log-pagina toont wanneer je een bericht opent.
Volgende stappen
- Berichtstatus-webhooks: ontvang elke gebeurtenis zodra die plaatsvindt
- Reactie-events: lees de huidige reacties en het reactielog
- Bericht als gelezen markeren: bevestig een inkomend bericht en toon typindicatie
- WhatsApp-log: de weergave per bericht die deze tijdlijn toont
- WhatsApp-berichten verzenden: waar de lifecycle van een bericht begint
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channelBegrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builderOntdek de mogelijkheidWhatsApp
Probeer de oefening en ontvang een implementatieoverzicht