WhatsApp-webhook-statussen: verzonden, bezorgd, gelezen en mislukt
Statuswebhooks melden wat er met een bericht is gebeurd dat een bedrijf via de WhatsApp Cloud API heeft verstuurd. Ze komen binnen op het veld messages, met een statuses-array in plaats van een messages-array: verzonden (één vinkje), bezorgd (twee vinkjes), gelezen (twee blauwe vinkjes), afgespeeld bij spraakberichten, en mislukt met een errors-array. Koppel statuses[].id aan de wamid die je verzendverzoek heeft teruggegeven.
easyCoexistence koppelt het WhatsApp Business-app-nummer dat je al gebruikt aan Meta's Cloud API via Coexistence.
Statuswaarden die Meta verstuurt: sent, delivered, read, played (eerste keer afspelen van spraakberichten) en failed.
Afzonderlijke statuswebhooks die één uitgaand bericht kan opleveren: sent, delivered en read.
Vanaf deze Graph API-versie vervalt het conversation-object, behalve voor berichten binnen het vrije entry point-venster.
API's om oude webhook-data op te halen bestaan niet; Meta vraagt je payloads op te slaan zodra ze binnenkomen.
De X-EC-Event-header op een doorgestuurde status: statussen reizen mee in messages-events, onder value.statuses.
Waar komen WhatsApp-statuswebhooks binnen?
Op hetzelfde veld messages dat ook berichten van klanten draagt, in dezelfde object-, entry- en changes-structuur. Het verschil zit in value: een inkomend bericht heeft een messages-array, een status heeft een statuses-array. Een handler die alleen value.messages leest, laat elke status vallen zonder foutmelding. metadata.phone_number_id geeft aan welk van je nummers het bericht verstuurde. Er komt ook een contacts-array mee met de profielnaam van de klant, wa_id en BSUID, behalve bij mislukte statussen en bij de sent-status van groepsberichten. Dit is het voorbeeld van Meta van een marketing-template dat Meta's servers verliet:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}Wat betekent elke statuswaarde?
Elke waarde komt overeen met een vinkje dat de klant in WhatsApp ziet. Een status geldt als gelezen pas nadat het bezorgd is. Wanneer een klant een bericht ontvangt terwijl de chat al open staat, stuurt Meta read zonder eerst een delivered-webhook, als interne optimalisatie. Een tracker moet dus read accepteren ook als delivered nooit kwam, en moet statussen op volgorde van voortgang verwerken, in plaats van ze één voor één in een vaste reeks te verwachten.
Welke velden heeft een statusobject?
Minder dan een bericht, en meerdere zijn voorwaardelijk. De referentie van Meta geeft aan wanneer elk veld aanwezig is:
- id: de wamid van het verzonden bericht, de sleutel om op te koppelen.
- status en timestamp: de waarde en de Unix-tijd waarop de webhook werd geactiveerd, als string.
recipient_id: het telefoonnummer of het groeps-id, weggelaten wanneer je naar een BSUID stuurde en het nummer niet beschikbaar is.recipient_user_id: de BSUID van de klant, weggelaten bij een mislukte status wanneer je naar een telefoonnummer stuurde.recipient_typeenrecipient_participant_id: alleen bij berichten naar een groep.biz_opaque_callback_data: alleen wanneer je die instelde in het verzendverzoek.- pricing: alleen bij sent en bij precies één van delivered of read. errors: alleen bij failed.
Hoe koppel je een status aan het bericht dat je verstuurde?
Op de wamid. Het verzendverzoek antwoordt met messages[0].id, en elke status voor dat bericht draagt dezelfde waarde in statuses[].id. Sla die op naast je eigen record wanneer je verstuurt, en werk het record bij wanneer statussen binnenkomen, waarbij je de hoogste bereikte status bewaart, zodat een late delivered een read niet overschrijft. Een status waarvan je de wamid niet kent, is verstuurd door iets anders op het nummer, zoals een automatisering, en mag worden genegeerd of gelogd.
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}Wat verandert er bij een Coexistence-nummer?
Statussen beschrijven wat via de API is verzonden: antwoorden van je automatiseringen, berichten die je AI via een MCP-connector stuurde, en alles wat je eigen code verstuurde. Wat de eigenaar typt in de WhatsApp Business-app, bereikt software op een andere manier, als smb_message_echoes. Meta documenteert die als de spiegel van in de app verzonden berichten. Berichten die bij de eenmalige geschiedenisimport zijn overgekomen, dragen hun eigen status binnen de history-webhook, met waarden zoals delivered, read, played, pending en error.
Statussen gaan waarheen het messages-veld van het nummer gaat. Bij een directe bestemming post Meta ze rechtstreeks naar je endpoint, omdat messages een veld is dat Meta een bestemming laat overschrijven. Met automatiseringen aan en een Forward URL ingesteld, komen ze op die URL aan als messages-events.
Hoe weet je AI of automatisering of een bericht is bezorgd?
Via je bestemming, niet via het verzenden. Wanneer een assistent send_template of send_message aanroept, bevat het toolresultaat de wamid en meldt dat Meta het bericht heeft aanvaard. Bezorging wordt later bevestigd, op het apparaat van de klant, en als status gemeld. easyCoexistence bewaart geen statushistorie om in te zoeken, en geen MCP-tool leest statussen. Een agent die bezorgbevestiging nodig heeft, moet dus via je eigen systeem verzenden of de statussen lezen die je Forward URL ontvangt.
Hetzelfde geldt voor automatiseringen: een run in het tabblad Runs toont de antwoordstap als voltooid zodra Meta het bericht heeft aanvaard. Een achteraf gemelde fout verschijnt alleen als mislukte status op je bestemming.
Veelgemaakte fouten
- Zoeken naar een apart statuses-veld. Statussen komen op messages binnen, dus een handler die alleen value.messages leest, verliest ze zonder enige fout.
- Eisen dat delivered voor read komt. Meta slaat de delivered-webhook over wanneer het bericht meteen bij aankomst wordt gelezen.
- Het antwoord op het verzendverzoek als bezorging zien. Een wamid betekent dat Meta het verzoek heeft aanvaard; een fout kan minuten later volgen als mislukte status.
- Klanten alleen op recipient_id sleutelen. Dat veld wordt weggelaten wanneer je naar een BSUID stuurde en het telefoonnummer niet beschikbaar is; recipient_user_id bevat de BSUID.
Statussen van wat je automatiseringen, je AI of je code verzenden, gaan naar je server: rechtstreeks van Meta in de directe modus, of doorgestuurd naar je Forward URL en ondertekend met X-EC-Signature wanneer automatiseringen aan staan. Ze worden standaard niet opgeslagen. US$ 9 tot US$ 0,75 per nummer per maand, dalend naarmate je nummers toevoegt, met een gratis proefperiode van 3 dagen.
Veelgestelde vragen
Bevatten statuswebhooks de tekst van het bericht?
Nee. Een status bevat de wamid, de status, de ontvanger, tijdstempels en, waar van toepassing, pricing en errors. Bewaar een eigen kopie van wat je verstuurde, gekoppeld aan de wamid, als je het naast de status wilt tonen.
Kan ik eerdere statussen later bij Meta opvragen?
Nee. De webhookgids van Meta zegt dat er geen API's zijn om historische webhook-data op te halen. Een status die je endpoint niet heeft vastgelegd, is dus weg zodra Meta stopt met opnieuw proberen, na maximaal 7 dagen.
Waar dient biz_opaque_callback_data voor?
Het is een tekst die je instelt bij het verzenden, zoals je eigen bestel- of ticket-id. Meta geeft die terug in de statuses van dat bericht, zodat je een status aan je record kunt koppelen zonder eerst de wamid op te zoeken.
Moet ik statuswebhooks met 200 beantwoorden?
Ja, zoals elke webhook-POST. Meta behandelt elk ander antwoord als mislukte bezorging en probeert het opnieuw. Zo bereikt dezelfde status je soms twee keer.
Lees verder
Klaar om te beginnen?
Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.
Start je gratis proefperiodeGeverifieerd op