SMS stats API
Chaque valeur du tableau de bord Metrics provient de l'API de statistiques SMS. Utilisez les mêmes agrégats dans un tableau de bord, un entrepôt de données ou un bilan de santé. Les endpoints en lecture seule, limités à l'espace de travail, nécessitent une clé API avec un accès en lecture au scope sms. Une réponse correspond au tableau de bord pour la même plage et les mêmes filtres.
Des méthodes typées sont disponibles dans les SDK TypeScript, Python, PHP et Go sous sms.stats, le bird CLI les expose en tant que bird sms stats, et un agent y accède via les outils MCP sms_stats_*. Les schémas complets de requête et de réponse se trouvent dans la référence API.
L'agrégat et la série temporelle
Trois endpoints couvrent le haut du tableau de bord :
- GET /v1/sms/stats/summary renvoie une ligne agrégée unique pour l'ensemble de la fenêtre : les compteurs de cycle de vie (accepted, sent, delivered, undelivered, failed, rejected, expired), les delivery_rate et failure_rate dérivés, et les percentiles de latence de traitement, de livraison et totale (p50, p95, p99). Passez compare=previous_period et la réponse inclut également la fenêtre précédente de même durée ainsi que la variation par rapport à celle-ci.
- GET /v1/sms/stats/daily et GET /v1/sms/stats/hourly renvoient les compteurs de cycle de vie à raison d'une ligne par jour ou par heure. Les taux et la latence sont des chiffres sur l'ensemble de la fenêtre : lisez-les depuis /summary plutôt que par intervalle.
Les taux sont renvoyés sous forme décimale : un delivery_rate de 0.9739 correspond donc à 97,39 %. Un taux dont le dénominateur est zéro vaut null, ce qui permet à une période sans message accepté d'afficher delivery_rate plutôt que 0. Les chiffres utilisent l'heure d'envoi du message. Une livraison confirmée aujourd'hui pour un message accepté hier est comptabilisée sur la journée d'hier. Une fenêtre récente sous-estime donc delivered tant que ses accusés de livraison arrivent encore : considérez les dernières heures comme provisoires et non définitives.
Les compteurs utilisent une agrégation approximative de messages distincts. Un message peut contribuer à plusieurs statuts de cycle de vie au fur et à mesure de sa progression : les compteurs par statut ne sont donc pas mutuellement exclusifs et ne doivent pas être additionnés comme un total de messages. Utilisez les messages acceptés comme dénominateur du taux sortant. Ces agrégats opérationnels ne constituent pas un relevé de facturation ; utilisez les enregistrements de messages et de facturation pour la réconciliation.
Choisir la fenêtre
from et to acceptent soit un jour calendaire (YYYY-MM-DD), soit un instant RFC 3339, et les formats acceptés varient selon l'endpoint :
| Endpoint | Bornes | Fenêtre maximale |
|---|---|---|
| /summary | Deux jours, ou deux instants | 365 jours, ou 720 heures en instants |
| /daily | Jours calendaires | 365 jours |
| /hourly | Instants RFC 3339 | 720 heures (30 jours) |
Les bornes en instants sont à la granularité horaire, ce qui permet d'obtenir une fenêtre glissante de 24 heures en une seule requête. Sur /summary, mélanger un jour avec un instant renvoie une 422.
Définissez timezone sur un identifiant IANA tel que America/New_York pour calculer les bornes et les valeurs par défaut omises dans ce fuseau horaire au lieu d'UTC. Lorsque timezone est défini, Bird rejette les décalages UTC numériques tels que +05:45 dans les bornes en instants. Utilisez des instants Z ou des jours calendaires à la place.
Ventilations
Sept endpoints découpent les mêmes chiffres de livraison selon une dimension :
- Où c'est allé : /countries (le pays de destination) et /carriers (l'opérateur qui l'a acheminé).
- Ce que vous avez envoyé : /originators (l'adresse d'expéditeur utilisée), /categories et /tags.
- Comment ça s'est terminé : /statuses (une ligne par statut de cycle de vie avec activité) et /error-codes.
Tous se trouvent sous /v1/sms/stats/. Les lignes par pays, opérateur, expéditeur, catégorie, tag et code d'erreur sont classées par sort et limitées par limit (50 par défaut, 200 maximum). Leurs réponses incluent total, le nombre de valeurs distinctes dans la fenêtre, ce qui vous permet de détecter un résultat tronqué. Les lignes dont la métrique de tri est un taux avec un dénominateur nul apparaissent en dernier. La ventilation par statut comporte au plus sept lignes et n'a pas de paramètres sort ou limit.
Les six ventilations classées peuvent aussi renvoyer une courte série par ligne. Définissez include_trend=true et choisissez trend_grain=daily ou hourly. Les tendances nécessitent un limit de 50 ou moins et une fenêtre de 90 jours maximum pour les intervalles journaliers ou de 720 heures pour les intervalles horaires.
sort est par défaut accepted sur les ventilations par volume et failed sur /error-codes. L'endpoint /error-codes regroupe par raison d'échec normalisée de Bird plutôt que par code opérateur brut. Sa valeur fonctionne aussi avec le filtre error_code sur GET /v1/sms/messages, reliant une ligne à ses messages.
/tags ne compte que les messages tagués, et un message portant plusieurs tags est compté une fois sous chacun. Ses lignes ne totalisent donc pas le total de la période. Réconciliez un résultat /tags avec un autre au lieu d'utiliser /summary.
/statuses renvoie un statut et un compteur plutôt que le bloc de livraison complet. Chaque ligne compte les messages observés dans ce statut de cycle de vie ; un message peut apparaître dans plusieurs lignes.
Messages reçus
Six endpoints supplémentaires sous /v1/sms/stats/inbound/ comptent ce que vos numéros ont reçu plutôt que ce que vous avez envoyé : /summary, /daily et /hourly pour les totaux et les séries, et /countries, /operators et /numbers pour les ventilations. Ils acceptent les mêmes paramètres de fenêtre et de fuseau horaire que leurs homologues sortants.
Deux points diffèrent de la famille sortante. Chaque ligne porte un simple compteur received, sans bloc de livraison ni taux, car un message entrant n'a pas de cycle de vie de livraison à agréger. L'endpoint /operators exclut les messages dont l'opérateur d'envoi n'a pas été signalé par l'opérateur chargé de l'acheminement : ses lignes peuvent donc totaliser moins que /inbound/summary pour la même période. Utilisez le résumé comme total de l'espace de travail ; les lignes par opérateur ne couvrent que les messages avec un opérateur signalé.
Étapes suivantes
Analytique SMS relie ce reporting à l'analyse de campagne et à l'investigation de livraison.
- Metrics : consultez le tableau de bord que ces valeurs alimentent.
- Journal SMS : consultez les messages derrière les agrégats.
- Events : consommez le flux d'événements derrière les agrégats.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Comprendre le conceptWhat does a delivery receipt tell you?Suivre le parcours d'apprentissageOperate messaging reliably
Obtenir un guide d'implémentation