WhatsApp API-bericht niet afgeleverd: de oorzaken, in volgorde
Een geaccepteerd WhatsApp API-bericht is nog niet afgeleverd: Meta meldt de uitkomst later in een statuswebhook, verzonden, afgeleverd, gelezen of mislukt, met een foutcode. Controleer in deze volgorde: de mislukte status en zijn code, het 24-uursvenster (131047), de betaalmethode (131042), het template (132001, 132015), de ontvanger (131026, 131049, 131050), en daarna de limieten en verbinding van het nummer.
easyCoexistence controleert elk verbonden nummer dag en nacht, stuurt je een e-mail wanneer Meta stopt met afleveren, de verbinding verliest of de kwaliteit daalt, en stuurt de statuswebhooks van Meta ongewijzigd door naar je systeem.
sent (één vinkje), delivered (twee), read (twee blauwe) en failed (een rode foutdriehoek), zoals statuswebhooks ze melden.
Er zijn meer dan 24 uur verstreken sinds de ontvanger voor het laatst heeft gereageerd; Meta adviseert dan een template te sturen.
Niet te bezorgen: het nummer staat niet op WhatsApp, de ontvanger heeft de nieuwe voorwaarden niet geaccepteerd, of gebruikt een oude WhatsApp-versie.
Standaardtijd waarin WhatsApp een niet-afgeleverd utility- of marketingtemplate opnieuw probeert voordat het wordt weggegooid; authenticatietemplates staan standaard op 10 minuten.
Vaste doorvoersnelheid van een nummer dat zowel in de WhatsApp Business-app als in de Cloud API wordt gebruikt.
Waarom komt een geaccepteerd bericht toch niet aan?
Omdat het antwoord van de API en de aflevering twee afzonderlijke gebeurtenissen zijn. Bij het verzenden geeft Meta direct een message id terug zodra het verzoek is geaccepteerd; of het bericht de telefoon van de klant bereikt, volgt later, in een statuswebhook op het veld messages. sent betekent dat het de servers van Meta heeft verlaten (één vinkje), delivered dat het het apparaat heeft bereikt (twee), read dat het is geopend (twee blauwe), en failed dat het niet kon worden verzonden of afgeleverd. Dit wordt je getoond met een errors-array: code, title en error_data.details. Begin dus nooit met gissen: zoek de mislukte status bij dat message id en lees de code. Zonder webhook-endpoint wordt dit nergens vastgelegd.
Wat zijn de oorzaken, in de volgorde om ze te controleren?
Van de meest voorkomende op een pas verbonden nummer tot de zeldzaamste. Elke regel noemt de code van Meta, zodat de mislukte status aangeeft in welke je zit:
- Venster gesloten: 131047, meer dan 24 uur sinds de klant voor het laatst schreef. Berichten in vrije tekst hebben een open venster nodig; stuur een template.
- Betaling: 131042, of templates die stilzwijgend worden weggegooid. Sinds 1 oktober 2026 stoppen servicemessages ook zodra er 1.000 per maand zijn gebruikt zonder betaalmethode.
- Template: 132001 niet goedgekeurd of verkeerde taal, 132000 verkeerd aantal variabelen, 132012 verkeerd formaat, 132015 gepauzeerd, 132016 uitgeschakeld.
- Ontvanger: 131026 niet op WhatsApp, oude versie of voorwaarden niet geaccepteerd; 131050 marketingberichten gestopt; 131049 tegengehouden om een gezonde betrokkenheid te behouden; marketingtemplates naar Amerikaanse nummers worden niet afgeleverd.
- Limieten: 131048 beperkt na spamsignalen, 131056 te veel berichten naar één persoon, 130429 doorvoer, 20 berichten per seconde op een Coexistence-nummer.
- Account: 131031 of 368, het WhatsApp Business-account is beperkt of uitgeschakeld wegens een schending van het beleid.
- Verbinding: het nummer is niet meer gekoppeld, bijvoorbeeld na 14 dagen zonder de WhatsApp Business-app te openen.
Hoe ga je om met de codes aan de kant van de ontvanger?
Anders, omdat sommige een nieuwe poging verdienen en sommige nooit. 131050 betekent dat de persoon heeft gekozen om geen marketingberichten meer van jou te ontvangen: Meta zegt niet opnieuw te proberen, en de user_preferences-webhook laat je zien wanneer ze stoppen of hervatten. 131049 is Meta die een marketingbericht tegenhoudt om de betrokkenheid gezond te houden, vaak een limiet per gebruiker op marketingtemplates: Meta adviseert minstens 24 uur te wachten voordat je opnieuw verstuurt, want eerder opnieuw sturen geeft alleen dezelfde fout terug. 131026 geldt voor nummers die niet op WhatsApp staan, gebruikers die de huidige voorwaarden van WhatsApp niet hebben geaccepteerd en zeer oude appversies; controleer eerst het formaat en de landcode van het nummer en vraag de klant daarna via een ander kanaal.
Hoe lang blijft WhatsApp proberen af te leveren?
Zolang de levensduur van het bericht (time to live, TTL) dat toelaat. Als een telefoon uit staat of buiten bereik is, probeert WhatsApp de aflevering opnieuw in plaats van direct te mislukken: standaard 30 dagen voor utility- en marketingtemplates en 10 minuten voor authenticatietemplates. Een bedrijf kan dit per template verkorten met message_send_ttl_seconds, van 30 seconden tot 12 uur voor utility en van 30 seconden tot 15 minuten voor authenticatie. Een bericht dat binnen zijn TTL niet kan worden afgeleverd, wordt weggegooid. Een bericht met de status sent en na uren geen delivered-status wacht dus meestal op de telefoon van de klant en is niet verloren. Stel een korte TTL in voor codes en tijdgevoelige meldingen, zodat een late aflevering nooit iemand in verwarring brengt.
Wat betekent dit voor AI-antwoorden en automatiseringen?
Lees eerst de run, dan de status. In het tabblad Runs verstuurt een Skipped-run niets en zegt hij waarom: "Meer dan 24 uur sinds het laatste bericht van de klant", "Je hebt dit gesprek recent vanaf je telefoon beantwoord" of "Limiet voor AI-antwoorden in dit gesprek is dit uur bereikt". Een Done-run betekent dat Meta elk antwoord heeft geaccepteerd, wat geen bewijs van aflevering is. easyCoexistence slaat berichtstatussen niet op: met automatiseringen aan gaan ze naar je forward-URL als je die instelt, en in de directe modus gaan ze rechtstreeks naar je eigen endpoint. Vraag vanuit ChatGPT of Claude je AI om get_number_health uit te voeren: het geeft de live status, de kwaliteitsbeoordeling en de laatste 15 monitoringgebeurtenissen, inclusief een sending-blok met de foutcode van Meta.
Zo stel je het in
- Find the statusLook up the message id in your webhook log and read the latest status: delivered, read, sent only, or failed with an error code.
- Match the codeLook up the failed status's code in the list of causes above and in Meta's error codes reference.
- Check the accountConfirm the WhatsApp Business Account has a default payment method, a currency and a time zone in Billing & payments.
- Check the templateIf it was a template, confirm it is APPROVED in that language and the variables match its definition.
- Check the numberAsk your AI to run get_number_health, or open the number in the dashboard, to see the connection and any sending block.
Veelgemaakte fouten
- Opnieuw proberen bij een 131050. De persoon heeft marketingberichten van jou gestopt; extra pogingen worden nooit afgeleverd en voegen alleen negatieve signalen toe.
- Een message id lezen als afgeleverd. Meta accepteert eerst en meldt fouten later, dus een workflow die stopt bij het id mist elk geweigerd bericht.
- Een antwoord in vrije tekst een dag later sturen. Na 24 uur zonder bericht van de klant wordt alleen een template geaccepteerd.
- Draaien zonder webhook-endpoint. Mislukte statussen komen alleen binnen als webhook, dus zonder endpoint gaat de reden verloren waarom een bericht niet aankwam.
Je AI kan een nummer vanuit ChatGPT of Claude controleren met get_number_health. US$ 9 tot US$ 0.75 per nummer per maand, dalend naarmate je meer nummers toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Waarom toonde het bericht urenlang één vinkje?
Eén vinkje is de status sent: Meta heeft het verstuurd, maar de telefoon heeft het niet ontvangen, meestal omdat die uit staat of offline is. WhatsApp blijft opnieuw proberen tot de time to live van het template verstrijkt, standaard 30 dagen voor utility en marketing.
Waarom komen antwoorden wel aan, maar templates niet?
Meestal een betaalprobleem op het WhatsApp Business-account. Meta levert servicemessages binnen het gratis maandelijkse tegoed van het nummer zonder betaalmethode, maar levert templates niet af. Voeg een kaart toe bij Billing & payments.
Kan ik mislukte berichten zien in de WhatsApp Business-app?
Niet betrouwbaar. Op een Coexistence-nummer verschijnen berichten die via de API zijn verstuurd in de chatthread van de app, maar de reden van een mislukt bericht staat alleen in de foutcode van de statuswebhook.
Rekent Meta voor berichten die niet zijn afgeleverd?
Nee. Meta rekent alleen voor afgeleverde berichten, en pogingen met een gepauzeerd template worden ook niet gerekend.
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