WhatsApp-statistieken
De Metrics-pagina in het Bird-dashboard laat zien hoe je WhatsApp-kanaal presteert: hoeveel berichten het toestel van de ontvanger bereikten, of je faalpercentage aan het stijgen is en hoe snel alles ging. Deze gids loopt de pagina door, legt uit wat elk getal betekent en wanneer je actie moet ondernemen.
Statistieken zijn het geaggregeerde overzicht van alles wat je werkruimte verstuurt. Voor de levenscyclus van een enkel bericht (heeft dit nummer het ontvangen, en wanneer), zie het WhatsApp-log en events.
Je statistieken lezen
De Metrics-pagina vind je onder WhatsApp → Metrics in het Bird-dashboard; hij is zichtbaar voor werkruimteleden die zowel de WhatsApp read- als de Analytics read-rechten hebben. Elk getal volgt de bereikkiezer (laatste 24 uur, 7, 30 of 90 dagen). Nieuwe events verschijnen na aggregatie en replicatie, dus de meest recente periode is voorlopig.
Uitgaande percentages gebruiken het acceptatiemoment van elk bericht. Een bezorgbevestiging die vandaag binnenkomt voor een bericht dat gisteren is geaccepteerd, telt mee bij gisteren, samen met de eigen accepted van dat bericht. Elk bereik volgt dus de berichten die erin zijn geaccepteerd naarmate waarnemingen binnenkomen. Recente uren kunnen delivered te laag rapporteren zolang er nog bevestigingen binnenkomen. accepted is de noemer voor de bezorg- en faalpercentagekaarten.
Tellingen vertegenwoordigen unieke berichten per waargenomen event en kunnen bij grote volumes benaderingen zijn. Ze vormen geen verplichte funnel: een leesbevestiging kan bestaan zonder bezorgbevestiging, en ontbrekende waarnemingen kunnen gaten laten tussen fasen. Groepsstatistieken tellen ook berichten, niet ontvangers; de eerste waargenomen deelnemersbezorging kan de bezorgde teller verhogen voordat elk groepslid het bericht heeft ontvangen.
De samenvattingstegels
De rij tegels bovenaan is je snelle gezondheidscheck:
- Bezorgpercentage: bezorgde berichten als aandeel van geaccepteerde. De tegel toont Healthy boven 95%. Op of onder die waarde bereikt iets de toestellen niet: ongeldige nummers, een verlopen klantenservicevenster of een templateprobleem. Het histogram met faaloorzaken (zie Faalpercentage en oorzaken) laat zien welke.
- Faalpercentage: het aandeel geaccepteerde berichten dat eindigde op failed. De tegel toont je percentage tegen een limiet van 5% met een voortgangsbalk; bij het bereiken ervan schakelt de tegel naar Risk. Een aanhoudend hoog faalpercentage wijst meestal op lijstkwaliteit, een verlopen klantenservicevenster of een Meta-beperking.
- Geaccepteerd: het totale aantal berichten geaccepteerd in het bereik, met het aantal dat is doorgegeven aan het WhatsApp-netwerk (sent).
De drempels van 95% en 5% zijn de vangrails die we gebruiken om de tegels te kleuren. Ze zijn bewust conservatief; een tegel kan Healthy tonen en nog steeds ruimte voor verbetering hebben.
Bezorgingen over tijd
De bezorggrafiek toont geaccepteerd, bezorgd en mislukt volume over het bereik zodat je trends en eenmalige pieken kunt herkennen: een slechte campagne, een nummerlijstimport die fout ging, een template dat werd afgewezen. De bucketgrootte volgt het bereik (per uur voor 24 uur, per dag voor langere vensters).
Faalpercentage en oorzaken
Onder de bezorggrafiek op de Metrics-pagina toont een faalpercentagelijn het faalpercentage per bucket over het bereik, terwijl de samenvattingstegel het cijfer voor het hele venster bevat. Een histogram splitst de fouten uit op genormaliseerde foutcode, gerangschikt op aantal met het aandeel van elke code in de mislukte berichten. De faaloorzaken van WhatsApp zijn een open set, dus het histogram toont welke codes daadwerkelijk voorkwamen in het bereik in plaats van een vaste lijst; een stijgende balk bij één code wijst je direct naar de oplossing.
Bezorglatentie
De latentietabel rapporteert twee fasen op de p50-, p95- en p99-percentielen:
- Verwerking: vanaf het accepteren van een bericht tot succesvolle indiening bij de WhatsApp-provider. Een traag percentiel hier vraagt om onderzoek van het verzendpad, inclusief providerindiening.
- Totaal: van begin tot eind, van het accepteren van het bericht tot WhatsApp de bezorging op het toestel van de ontvanger bevestigt. Het verschil tussen Totaal en Verwerking is het WhatsApp-netwerk en het toestel van de ontvanger, waar we geen controle over hebben. Een telefoon die een uur offline is, rekt Totaal op terwijl Verwerking ongewijzigd blijft.
Gebruik p95/p99 om de trage staart te vangen: een gezonde mediaan met een trage p99 wijst meestal op één template of bestemming die achterblijft. Latentie is een cijfer voor het hele venster; een fase of percentiel zonder data voor het bereik toont een tijdelijke aanduiding.
Uitsplitsingen
Het Breakdowns-paneel splitst dezelfde bezorgcijfers uit zodat je een probleem kunt isoleren tot de bron:
- Op nummer: het geaccepteerde, bezorgde en mislukte volume per zakelijk verzendnummer met het bijbehorende bezorgpercentage, zodat je verzenders naast elkaar kunt vergelijken.
- Op template: dezelfde uitsplitsing per template, om het ene template te vinden dat een percentage omlaag trekt.
- Op templatecategorie: dezelfde uitsplitsing over Meta's templatecategorieën, de indeling die ook je kosten bepaalt.
- Op tag: de tags die je aan een verzending koppelt, de meest flexibele indeling: tag een campagne, template of experimentvariant en vergelijk ze direct.
- Op land: dezelfde uitsplitsing per bestemmingsland, om te zien of een bezorgprobleem een markt volgt in plaats van een verzender of template. Een ontvanger van wie het land niet kan worden bepaald (een nummer dat eruitziet als een telefoonnummer maar bij geen land hoort, of een internationaal bereik zoals freephone) wordt geteld onder ZZ, dezelfde tijdelijke aanduiding die de SMS-landuitsplitsing gebruikt. Groepsverzendingen worden weggelaten omdat een groep meerdere landen kan omvatten en geen enkele bestemming heeft. Historische landdekking van vóór de introductie van deze uitsplitsing kan onvolledig zijn, inclusief bezorgde of gelezen waarnemingen zonder bijbehorende geaccepteerde tellingen. Geaggregeerde historie overleeft het 30-dagenvenster voor berichtdetails; 30 dagen wachten herstelt die oudere cohorten niet.
Elke rij krijgt ook een afgeleide status (Healthy, Watching of Throttled) op basis van zijn eigen bezorg- en faalpercentages, zodat een nummer of categorie met problemen opvalt zonder dat je elke kolom hoeft te lezen. Elk tabblad rangschikt de bovenste rijen voor het bereik; als een dimensie meer unieke waarden heeft dan er passen, vermeldt het paneel "Top N of M".
Programmatische toegang
De aggregaten achter deze pagina zijn ook een publieke API. Getypeerde methoden zijn beschikbaar in de TypeScript-, Python-, PHP- en Go-SDK's onder bird.whatsapp.stats, de bird CLI stelt ze beschikbaar als bird whatsapp stats <verb>, en een agent bereikt ze via de whatsapp_stats_* MCP tools. Volledige request- en responseschema's staan in de API-referentie.
Het aggregaat en de tijdreeks
GET /v1/whatsapp/stats/summary retourneert één geaggregeerde rij voor het venster: levenscyclustellingen (accepted, sent, delivered, failed, rejected) met bezorg- en faalpercentages, engagement (read, read_rate) en latentiepercentielen (p50, p95, p99) voor drie fasen: verwerking, bezorging en totaal. /daily en /hourly retourneren dezelfde levenscyclus- en leestellingen met één rij per kalenderdag of uur, elk met eigen latentiepercentielen; alleen de percentages (delivery_rate, failure_rate, read_rate) zijn cijfers voor het hele venster, lees die uit /summary. Alle drie accepteren één dimensiefilter tegelijk: template, category, tag of phone_number. Hier beperkt phone_number tot één zakelijke verzender in E.164-formaat, niet het contact waarop het filtert bij de verouderde phone_number-param van GET /v1/whatsapp/messages.
Het leespercentage is read / delivered, terwijl bezorg- en faalpercentages accepted gebruiken. Een noemer van nul retourneert null, wat betekent dat het percentage niet berekend kan worden. Het leespercentage is niet begrensd op 100%, dus ontbrekende bezorgwaarnemingen kunnen een hogere waarde opleveren; dit is een waarnemingsgat om te onderzoeken, geen bewijs dat meer dan elke ontvanger het bericht heeft gelezen.
Latentiepercentielen gebruiken geregistreerde samples. Een ontbrekend bezorglatentiesample betekent niet nul latentie, en totaallatentie kan aanwezig zijn als het tussenliggende sent-tijdstempel niet beschikbaar was. Middel geen gefinaliseerde percentielen uit afzonderlijke buckets. Opnieuw afgespeelde events kunnen latentieverdelingen beïnvloeden, ook als tellingen van unieke berichten gededupliceerd blijven.
Wanneer aanwezig rapporteert data_as_of de versheid van de aggregatie. Het bewijst niet dat alle providercallbacks zijn binnengekomen of dat de facturering is afgerond. Een null-versheidswaarde betekent dat deze niet beschikbaar was voor dat antwoord.
Het venster kiezen
from en to accepteren een kalenderdag of een RFC 3339-instant, maar welke vormen een endpoint accepteert verschilt:
| Endpoint | Grenzen | Maximaal venster |
|---|---|---|
| /summary | Beide kalenderdagen, of beide RFC 3339-instants | 365 dagen, of 720 uur bij instants |
| /daily | Alleen kalenderdagen | 365 dagen |
| /hourly | Alleen RFC 3339-instants | 720 uur (30 dagen) |
Bij /summary retourneert het mixen van een daggrens met een instantgrens 422. Instantgrenzen worden naar beneden afgerond op het uur op /summary en /hourly, de enige twee die ze accepteren. Stel timezone in op een IANA-identifier om dag- en uurgrenzen lokaal te berekenen in plaats van in UTC; zodra dit is ingesteld, wordt een numerieke UTC-offset zoals +05:45 in een instantgrens afgewezen. Voeg compare=previous_period toe aan /summary voor het voorgaande venster van gelijke lengte en de verandering ten opzichte daarvan.
Uitsplitsingen
Zes endpoints rangschikken dezelfde bezorgcijfers op één dimensie, elk al per dimensie zodat geen ervan een filter accepteert: op nummer, op template, op templatecategorie, op tag en op foutcode (alleen mislukte berichten, gegroepeerd op genormaliseerde faalreden). Rijen worden gerangschikt op geaccepteerd volume (foutaantal bij foutcodes) en begrensd op limit (standaard 50, maximum 200). Een verzending zonder waarde voor een dimensie ontbreekt in die uitsplitsing: een bericht met vrij geformuleerde inhoud heeft geen template, en een niet-getagde verzending geen tag. Een bericht met meerdere tags kan in meerdere tagrijen voorkomen, dus het optellen van die rijen levert niet het unieke werkruimtevolume op. Vergelijk een uitsplitsing met zichzelf over tijd. Elke rij behalve een foutcoderij draagt ook eigen latency-percentielen. Een zesde, op land, groepeert dezelfde cijfers op de bestemmingsmarkt van de ontvanger; een ontvanger van wie het land niet kan worden bepaald telt onder ZZ, en groepsverzendingen ontbreken omdat één verzending meerdere landen kan omvatten.
Ontvangen berichten
Vier endpoints onder /v1/whatsapp/stats/inbound/ dekken wat je nummers ontvingen in plaats van verzonden: samenvatting, dagelijks, per uur en per telefoonnummer. Elke rij bevat alleen een received-telling en volgt het voorvalmoment van het inkomende bericht. Een ontvangen bericht heeft geen uitgaande bezorglevenscyclus om verder uit te splitsen. Deze zijn genest onder bird.whatsapp.stats.inbound in de SDK's en bird whatsapp stats inbound <verb> in de CLI.
Reconciliatie per bericht
De stats-endpoints beantwoorden geaggregeerde vragen; ze vervangen geen lookups per bericht. Om te bevestigen wat er met één bericht is gebeurd, consumeer je webhook-events zodra ze binnenkomen, of blader je door GET /v1/whatsapp/messages en het events-endpoint van elk bericht, waarvan de filters (status, ontvanger, tag, tijdvenster) de meeste reconciliatietaken dekken.
Volgende stappen
- WhatsApp-analytics: koppel berichtwaarnemingen aan bevestigde klantresultaten
- WhatsApp-log: de weergave per bericht achter de geaggregeerde cijfers
- Events: de levenscyclusstream per bericht waarvan de statistieken zijn afgeleid
- WhatsApp-berichten verzenden: categorieën, tags en het kostenmodel per bericht
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