API per le statistiche SMS
Ogni valore nella dashboard Metrics proviene dall’API per le statistiche SMS. Usa gli stessi aggregati in una dashboard, un data warehouse o un health check. Gli endpoint in sola lettura, con scope sullo spazio di lavoro, richiedono una chiave API con accesso in lettura allo scope sms. Una risposta corrisponde alla dashboard per lo stesso intervallo e gli stessi filtri.
I metodi tipizzati sono disponibili negli SDK TypeScript, Python, PHP e Go sotto sms.stats, la bird CLI li espone come bird sms stats e un agente li raggiunge tramite gli strumenti MCP sms_stats_*. Gli schemi completi di richiesta e risposta sono nella documentazione di riferimento API.
L'aggregato e la serie temporale
Tre endpoint coprono la parte superiore della dashboard:
- GET /v1/sms/stats/summary restituisce una singola riga aggregata per l'intera finestra: i conteggi del ciclo di vita (accepted, sent, delivered, undelivered, failed, rejected, expired), i valori derivati delivery_rate e failure_rate, e i percentili di latenza di elaborazione, consegna e totale (p50, p95, p99). Passa compare=previous_period e la risposta include anche la finestra precedente di pari durata e la variazione rispetto a essa.
- GET /v1/sms/stats/daily e GET /v1/sms/stats/hourly restituiscono i conteggi del ciclo di vita una riga per giorno o per ora. Tassi e latenza sono cifre sull'intera finestra, quindi leggili da /summary anziché per singolo bucket.
Ogni tasso viene restituito come valore decimale, quindi un delivery_rate di 0.9739 corrisponde al 97,39%. Un tasso il cui denominatore è zero è null, che è il modo in cui un periodo senza messaggi accettati riporta delivery_rate invece di leggere 0. Le cifre usano l’ora di invio del messaggio. Una consegna confermata oggi per un messaggio accettato ieri viene attribuita a ieri. In una finestra recente, delivered resta sotto il valore finale finché arrivano nuovi report di consegna. Considera provvisorie le ultime ore.
I conteggi usano un'aggregazione approssimativa per messaggi distinti. Un messaggio può contribuire a più di uno stato del ciclo di vita man mano che avanza, quindi i conteggi per stato non si escludono a vicenda e non vanno sommati come totale dei messaggi. Usa i messaggi accettati come denominatore del tasso in uscita. Questi aggregati operativi non sono un registro di fatturazione; usa i record dei messaggi e di fatturazione per la riconciliazione.
Scelta della finestra
from e to accettano un giorno di calendario (YYYY-MM-DD) o un istante RFC 3339, e i formati accettati variano a seconda dell'endpoint:
| Endpoint | Limiti | Finestra massima |
|---|---|---|
| /summary | Entrambi giorni, o entrambi istanti | 365 giorni, o 720 ore con istanti |
| /daily | Giorni di calendario | 365 giorni |
| /hourly | Istanti RFC 3339 | 720 ore (30 giorni) |
I limiti istantanei hanno granularità oraria, il che permette di ottenere una finestra mobile di 24 ore con una sola richiesta. Su /summary, mescolare un giorno con un istante restituisce un 422.
Imposta timezone su un identificatore IANA come America/New_York per calcolare i limiti e i valori predefiniti omessi in quel fuso orario invece di UTC. Quando timezone è impostato, Bird rifiuta gli offset UTC numerici come +05:45 nei limiti istantanei. Usa invece istanti Z o giorni di calendario.
Breakdown
Sette endpoint suddividono gli stessi numeri di consegna per una dimensione:
- Dove è andato: /countries (il paese di destinazione) e /carriers (l'operatore che lo ha gestito).
- Cosa hai inviato: /originators (l'indirizzo mittente usato per l'invio), /categories e /tags.
- Come è finito: /statuses (una riga per ogni stato del ciclo di vita con attività) e /error-codes.
Tutti risiedono sotto /v1/sms/stats/. Le righe per paese, operatore, originator, categoria, tag e codice di errore sono ordinate per sort e limitate da limit (predefinito 50, massimo 200). Le risposte includono total, il numero di valori distinti nella finestra, per individuare un risultato troncato. Le righe la cui metrica di ordinamento è un tasso con denominatore zero appaiono per ultime. Il breakdown per stato ha al massimo sette righe e non ha i parametri sort o limit.
I sei breakdown ordinati possono anche restituire una breve serie per riga. Imposta include_trend=true e scegli trend_grain=daily o hourly. I trend richiedono limit pari a 50 o meno e una finestra di al massimo 90 giorni per bucket giornalieri o 720 ore per bucket orari.
sort usa come predefinito accepted nei breakdown per volume e failed su /error-codes. L'endpoint /error-codes raggruppa per il motivo di errore normalizzato di Bird anziché per un codice operatore grezzo. Il suo valore funziona anche con il filtro error_code su GET /v1/sms/messages, collegando una riga ai relativi messaggi.
/tags conta solo i messaggi taggati e un messaggio con più tag viene contato una volta per ciascuno. Le sue righe quindi non sommano al totale del periodo. Riconcilia un risultato /tags con un altro invece di usare /summary.
/statuses restituisce uno stato e un conteggio anziché il blocco di consegna completo. Ogni riga conta i messaggi osservati in quello stato del ciclo di vita; un messaggio può apparire in più righe.
Messaggi ricevuti
Sei ulteriori endpoint sotto /v1/sms/stats/inbound/ contano ciò che i tuoi numeri hanno ricevuto anziché ciò che hai inviato: /summary, /daily e /hourly per i totali e la serie, e /countries, /operators e /numbers per i breakdown. Accettano gli stessi parametri di finestra e fuso orario delle controparti in uscita.
Due aspetti differiscono dalla famiglia in uscita. Ogni riga contiene un semplice conteggio received, senza blocco di consegna o tassi, perché un messaggio in entrata non ha un ciclo di vita di consegna da aggregare. L'endpoint /operators esclude i messaggi per i quali l'operatore mittente non è stato riportato dall'operatore di rete, quindi le sue righe possono sommare a meno di /inbound/summary per lo stesso periodo. Usa il riepilogo come totale dello spazio di lavoro; le righe per operatore coprono solo i messaggi con un operatore riportato.
Passaggi successivi
Le analisi SMS collegano questi report alla revisione delle campagne e all’analisi delle consegne.
- Metrics: esamina la dashboard che questi valori alimentano.
- SMS log: esamina i messaggi dietro gli aggregati.
- Events: consuma il flusso di eventi dietro gli aggregati.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Comprendi il concettoWhat does a delivery receipt tell you?Segui il percorso di apprendimentoOperate messaging reliably
Ottieni un brief di implementazione