SMS stats API
Elke waarde op het Metrics-dashboard komt uit de SMS stats API. Gebruik dezelfde aggregaten in een dashboard, datawarehouse of health check. De alleen-lezen, werkruimte-gebonden endpoints vereisen een API-sleutel met leestoegang tot het sms-bereik. Een antwoord komt overeen met het dashboard voor hetzelfde bereik en dezelfde filters.
Getypeerde methoden zitten in de TypeScript-, Python-, PHP- en Go-SDK's onder sms.stats, de bird CLI biedt ze aan als bird sms stats, en een agent bereikt ze via de sms_stats_* MCP tools. Volledige request- en responseschema's staan in de API-referentie.
Het aggregaat en de tijdreeks
Drie endpoints bestrijken de bovenkant van het dashboard:
- GET /v1/sms/stats/summary geeft één aggregaatrij terug voor het hele venster: de lifecycletellingen (accepted, sent, delivered, undelivered, failed, rejected, expired), de afgeleide delivery_rate en failure_rate, en de verwerkings-, bezorgings- en totale latentiepercentielen (p50, p95, p99). Geef compare=previous_period mee en het antwoord bevat ook het voorafgaande venster van gelijke lengte en de verandering ten opzichte daarvan.
- GET /v1/sms/stats/daily en GET /v1/sms/stats/hourly geven de lifecycletellingen terug met één rij per dag of per uur. Percentages en latentie zijn cijfers over het hele venster, dus lees die uit /summary in plaats van per bucket.
Elke ratio komt terug als een decimaal getal, dus een delivery_rate van 0.9739 is 97,39%. Een ratio waarvan de noemer nul is, is null. Zo rapporteert een periode zonder geaccepteerde berichten delivery_rate in plaats van 0 te tonen. Cijfers gebruiken de verzendtijd van het bericht. Een bezorging die vandaag bevestigd is voor een bericht dat gisteren geaccepteerd werd, telt mee bij gisteren. Een recent venster rapporteert delivered daarom te laag zolang de bezorgingsrapporten nog binnenkomen, dus beschouw de laatste paar uur als voorlopig in plaats van definitief.
Tellingen gebruiken benaderende unieke-berichtaggregatie. Een bericht kan bijdragen aan meer dan één lifecyclestatus naarmate het vordert, dus statustellingen sluiten elkaar niet uit en mogen niet bij elkaar opgeteld worden als berichttotaal. Gebruik geaccepteerde berichten als noemer voor de uitgaande ratio. Deze operationele aggregaten zijn geen facturatieoverzicht; gebruik de bericht- en facturatierecords voor afstemming.
Het venster kiezen
from en to accepteren een kalenderdag (YYYY-MM-DD) of een RFC 3339-tijdstip, en welke vormen een endpoint accepteert verschilt:
| Endpoint | Grenzen | Maximaal venster |
|---|---|---|
| /summary | Beide dagen, of beide tijdstippen | 365 dagen, of 720 uur bij tijdstippen |
| /daily | Kalenderdagen | 365 dagen |
| /hourly | RFC 3339-tijdstippen | 720 uur (30 dagen) |
Tijdstipgrenzen hebben uurgranulariteit, waardoor een rollend 24-uursvenster één enkel request is. Bij /summary levert het combineren van een dag met een tijdstip een 422 op.
Stel timezone in op een IANA-identificatie zoals America/New_York om grenzen en weggelaten standaardwaarden in die tijdzone te berekenen in plaats van UTC. Wanneer timezone is ingesteld, weigert Bird numerieke UTC-offsets zoals +05:45 in tijdstipgrenzen. Gebruik in plaats daarvan Z-tijdstippen of kalenderdagen.
Uitsplitsingen
Zeven endpoints splitsen dezelfde bezorgingscijfers uit op één dimensie:
- Waar het naartoe ging: /countries (het bestemmingsland) en /carriers (de carrier die het afhandelde).
- Wat je verstuurde: /originators (het afzenderadres waarmee het werd verzonden), /categories en /tags.
- Hoe het eindigde: /statuses (één rij per lifecyclestatus met activiteit) en /error-codes.
Ze vallen allemaal onder /v1/sms/stats/. Land-, carrier-, originator-, categorie-, tag- en foutcoderijen worden gerangschikt op sort en begrensd door limit (standaard 50, maximaal 200). Hun antwoorden bevatten total, het aantal unieke waarden in het venster, zodat je een begrensd resultaat kunt detecteren. Rijen waarvan de sorteermetriek een percentage met noemer nul is, verschijnen als laatste. De statusuitsplitsing heeft maximaal zeven rijen en heeft geen sort- of limit-parameters.
De zes gerangschikte uitsplitsingen kunnen ook een korte reeks per rij teruggeven. Stel include_trend=true in en kies trend_grain=daily of hourly. Trends vereisen een limit van 50 of minder en een venster van maximaal 90 dagen voor dagelijkse buckets of 720 uur voor buckets per uur.
sort is standaard accepted bij volume-uitsplitsingen en failed bij /error-codes. Het /error-codes-endpoint groepeert op de genormaliseerde faalreden van Bird in plaats van een ruwe carriercode. De waarde werkt ook met het error_code-filter op GET /v1/sms/messages, waarmee je een rij aan zijn berichten koppelt.
/tags telt alleen getagde berichten, en een bericht met meerdere tags wordt één keer per tag geteld. De rijen tellen daarom niet op tot het periodetotaal. Vergelijk het ene /tags-resultaat met het andere in plaats van /summary te gebruiken.
/statuses geeft een status en telling terug in plaats van het volledige bezorgingsblok. Elke rij telt berichten die in die lifecyclestatus zijn waargenomen; een bericht kan in meerdere rijen voorkomen.
Ontvangen berichten
Zes extra endpoints onder /v1/sms/stats/inbound/ tellen wat je nummers ontvingen in plaats van wat je verstuurde: /summary, /daily en /hourly voor de totalen en de reeks, en /countries, /operators en /numbers voor de uitsplitsingen. Ze accepteren dezelfde venster- en tijdzoneparameters als hun uitgaande tegenhangers.
Twee dingen wijken af van de uitgaande familie. Elke rij bevat een gewone received-telling, zonder bezorgingsblok of ratio’s, omdat een inkomend bericht geen bezorgingslevenscyclus heeft om te aggregeren. Het /operators-endpoint sluit berichten uit waarvan de carrier de verzendende operator niet rapporteerde, waardoor de rijen lager kunnen uitvallen dan /inbound/summary voor dezelfde periode. Gebruik de samenvatting als werkruimtetotaal; operatorrijen dekken alleen berichten met een gerapporteerde operator.
Volgende stappen
SMS analytics verbindt deze rapportage met campagnebeoordeling en bezorgingsonderzoek.
- Metrics: bekijk het dashboard dat deze waarden weergeeft.
- SMS-log: bekijk de berichten achter de aggregaten.
- Events: consumeer de eventstream achter de aggregaten.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.