SMS-Statistik-API

Jeder Wert im Metrics-Dashboard stammt aus der SMS-Statistik-API. Verwenden Sie dieselben Aggregatdaten in einem Dashboard, Data Warehouse oder Health Check. Die schreibgeschützten, Workspace-bezogenen Endpunkte erfordern einen API-Schlüssel mit Lesezugriff auf den Scope sms. Eine Antwort stimmt mit dem Dashboard für denselben Zeitraum und dieselben Filter überein.

Typisierte Methoden sind in den TypeScript-, Python-, PHP- und Go-SDKs unter sms.stats verfügbar, die bird CLI stellt sie als bird sms stats bereit, und ein Agent erreicht sie über die sms_stats_* MCP-Tools. Vollständige Request- und Response-Schemas finden Sie in der API-Referenz.

Das Aggregat und die Zeitreihe

Drei Endpunkte decken den oberen Bereich des Dashboards ab:

GET /v1/sms/stats/summary gibt eine einzelne Aggregatzeile für das gesamte Fenster zurück: die Lifecycle-Zähler (accepted, sent, delivered, undelivered, failed, rejected, expired), die abgeleiteten delivery_rate und failure_rate sowie die Latenz-Perzentile für Verarbeitung, Zustellung und Gesamtdauer (p50, p95, p99). Übergeben Sie compare=previous_period, und die Antwort enthält zusätzlich das vorangehende gleichlange Fenster und die Änderung gegenüber diesem.
GET /v1/sms/stats/daily und GET /v1/sms/stats/hourly geben die Lifecycle-Zähler mit einer Zeile pro Tag oder pro Stunde zurück. Raten und Latenz beziehen sich auf das gesamte Fenster, lesen Sie diese daher aus /summary statt pro Bucket.

Raten werden als Dezimalzahlen zurückgegeben, eine delivery_rate von 0.9739 entspricht also 97,39 %. Eine Rate, deren Nenner null ist, ist null. So meldet ein Zeitraum ohne akzeptierte Nachrichten delivery_rate, anstatt 0 anzuzeigen. Die Zahlen verwenden die Sendezeit der Nachricht. Eine heute bestätigte Zustellung für eine gestern akzeptierte Nachricht wird dem gestrigen Tag zugeordnet. Ein aktuelles Fenster unterschätzt daher delivered, solange die Zustellberichte noch eintreffen. Behandeln Sie die letzten Stunden als vorläufig, nicht als endgültig.

Die Zähler schätzen die Anzahl unterschiedlicher Nachrichten. Eine Nachricht kann im Verlauf zu mehr als einem Lifecycle-Status beitragen. Status-Zähler schließen sich daher nicht gegenseitig aus und dürfen nicht als Gesamtzahl der Nachrichten addiert werden. Verwenden Sie akzeptierte Nachrichten als Nenner der Ausgangsrate. Diese operativen Aggregatdaten sind kein Abrechnungsjournal; verwenden Sie die Nachrichten- und Abrechnungsdatensätze für den Abgleich.

Das Fenster wählen

from und to akzeptieren entweder einen Kalendertag (YYYY-MM-DD) oder einen RFC-3339-Zeitpunkt, und die akzeptierten Formate unterscheiden sich je nach Endpunkt:

Endpunkt	Grenzen	Maximales Fenster
/summary	Beides Tage oder beides Zeitpunkte	365 Tage oder 720 Stunden bei Zeitpunkten
/daily	Kalendertage	365 Tage
/hourly	RFC-3339-Zeitpunkte	720 Stunden (30 Tage)

Zeitpunkt-Grenzen haben Stundengranularität, weshalb ein rollendes 24-Stunden-Fenster ein einzelner Request ist. Bei /summary gibt die Kombination eines Tages mit einem Zeitpunkt einen 422 zurück.

Setzen Sie timezone auf einen IANA-Bezeichner wie America/New_York, um Grenzen und ausgelassene Standardwerte in dieser Zeitzone statt in UTC zu berechnen. Wenn timezone gesetzt ist, lehnt Bird numerische UTC-Offsets wie +05:45 in Zeitpunkt-Grenzen ab. Verwenden Sie stattdessen Z-Zeitpunkte oder Kalendertage.

Aufschlüsselungen

Sieben Endpunkte gliedern dieselben Zustellzahlen nach jeweils einer Dimension:

Wohin es ging: /countries (das Zielland) und /carriers (der Carrier, der die Nachricht verarbeitet hat).
Was Sie gesendet haben: /originators (die Absenderadresse, über die es versendet wurde), /categories und /tags.
Wie es endete: /statuses (eine Zeile pro Lifecycle-Status mit Aktivität) und /error-codes.

Alle befinden sich unter /v1/sms/stats/. Zeilen für Land, Carrier, Absender, Kategorie, Tag und Fehlercode werden nach sort sortiert und durch limit begrenzt (Standard 50, Maximum 200). Die Antworten enthalten total, die Anzahl der unterschiedlichen Werte im Fenster, sodass Sie ein begrenztes Ergebnis erkennen können. Zeilen, deren Sortiermetrik eine Rate mit einem Nenner von null ist, erscheinen zuletzt. Die Status-Aufschlüsselung hat maximal sieben Zeilen und besitzt keine Parameter sort oder limit.

Die sechs sortierten Aufschlüsselungen können auch eine kurze Zeitreihe pro Zeile zurückgeben. Setzen Sie include_trend=true und wählen Sie trend_grain=daily oder hourly. Trends erfordern einen limit von 50 oder weniger und ein Fenster von maximal 90 Tagen für tägliche Buckets oder 720 Stunden für stündliche Buckets.

sort ist bei Volumen-Aufschlüsselungen standardmäßig accepted und bei /error-codes standardmäßig failed. Der Endpunkt /error-codes gruppiert nach dem normalisierten Fehlergrund von Bird anstelle eines rohen Carrier-Codes. Sein Wert funktioniert auch mit dem Filter error_code auf GET /v1/sms/messages, um eine Zeile mit ihren Nachrichten zu verknüpfen.

/tags zählt nur getaggte Nachrichten, und eine Nachricht mit mehreren Tags wird unter jedem einmal gezählt. Die Zeilen ergeben daher nicht die Gesamtzahl des Zeitraums. Gleichen Sie ein /tags-Ergebnis mit einem anderen ab, anstatt /summary zu verwenden.

/statuses gibt einen Status und einen Zähler zurück, nicht den vollständigen Zustellblock. Jede Zeile zählt Nachrichten, die in diesem Lifecycle-Status beobachtet wurden; eine Nachricht kann in mehreren Zeilen erscheinen.

Empfangene Nachrichten

Sechs weitere Endpunkte unter /v1/sms/stats/inbound/ zählen, was Ihre Nummern empfangen haben, statt was Sie gesendet haben: /summary, /daily und /hourly für die Gesamtwerte und die Zeitreihe, sowie /countries, /operators und /numbers für die Aufschlüsselungen. Sie akzeptieren dieselben Fenster- und Zeitzonenparameter wie ihre ausgehenden Gegenstücke.

Zwei Dinge unterscheiden sich von der ausgehenden Familie. Jede Zeile enthält einen einfachen received-Zähler ohne Zustellblock oder Raten, da eine eingehende Nachricht keinen Zustelllebenszyklus zur Aggregation hat. Der Endpunkt /operators schließt Nachrichten aus, deren sendenden Betreiber der Carrier nicht gemeldet hat, sodass seine Zeilen für denselben Zeitraum weniger als /inbound/summary ergeben können. Verwenden Sie die Zusammenfassung als Workspace-Gesamtwert; Betreiberzeilen decken nur Nachrichten mit einem gemeldeten Betreiber ab.

Nächste Schritte

Die SMS-Analysen verbinden diese Berichte mit der Kampagnenauswertung und der Untersuchung von Zustellungen.

Metrics: Sehen Sie sich das Dashboard an, das diese Werte darstellt.
SMS-Log: Sehen Sie sich die Nachrichten hinter den Aggregatdaten an.
Events: Konsumieren Sie den Event-Stream hinter den Aggregatdaten.