SMS stats API
Todo valor no painel Metrics vem dos SMS stats API. Use os mesmos agregados em um painel, data warehouse ou verificação de integridade. Os endpoints somente leitura, com escopo de espaço de trabalho, exigem uma chave API com acesso de leitura ao escopo sms. A resposta corresponde ao painel para o mesmo intervalo e filtros.
Métodos tipados estão disponíveis nos SDKs TypeScript, Python, PHP e Go em sms.stats, a bird CLI os expõe como bird sms stats, e um agente os acessa pelas sms_stats_* ferramentas MCP. Os esquemas completos de requisição e resposta estão na referência API.
O agregado e a série temporal
Três endpoints cobrem o topo do painel:
- GET /v1/sms/stats/summary retorna uma linha agregada para toda a janela: as contagens de ciclo de vida (accepted, sent, delivered, undelivered, failed, rejected, expired), as taxas derivadas delivery_rate e failure_rate, e os percentis de latência de processamento, entrega e total (p50, p95, p99). Passe compare=previous_period e a resposta também inclui a janela anterior de mesmo comprimento e a variação em relação a ela.
- GET /v1/sms/stats/daily e GET /v1/sms/stats/hourly retornam as contagens de ciclo de vida com uma linha por dia ou por hora. Taxas e latência são valores da janela inteira, então leia esses dados de /summary em vez de por bucket.
As taxas são retornadas em formato decimal, então um delivery_rate de 0.9739 equivale a 97,39%. Uma taxa cujo denominador é zero é null, que é como um período que não aceitou nada reporta delivery_rate em vez de exibir 0. Os valores usam o horário de envio da mensagem. Uma entrega confirmada hoje para uma mensagem aceita ontem é contabilizada em ontem. Uma janela recente portanto sub-reporta delivered enquanto seus relatórios de entrega ainda estão chegando, então trate as últimas horas como provisórias e não como definitivas.
As contagens usam agregação aproximada de mensagens distintas. Uma mensagem pode contribuir para mais de um status de ciclo de vida à medida que progride, então as contagens de status não são mutuamente exclusivas e não devem ser somadas como total de mensagens. Use as mensagens aceitas como denominador da taxa de envio. Esses agregados operacionais não são um registro de faturamento; use os registros de mensagens e faturamento para reconciliação.
Escolhendo a janela
from e to aceitam um dia do calendário (YYYY-MM-DD) ou um instante RFC 3339, e os formatos aceitos diferem por endpoint:
| Endpoint | Limites | Janela máxima |
|---|---|---|
| /summary | Ambos dias, ou ambos instantes | 365 dias, ou 720 horas com instantes |
| /daily | Dias do calendário | 365 dias |
| /hourly | Instantes RFC 3339 | 720 horas (30 dias) |
Limites por instante têm granularidade de hora, o que permite que uma janela móvel de 24 horas seja uma única requisição. Em /summary, misturar um dia com um instante retorna um 422.
Defina timezone com um identificador IANA como America/New_York para calcular limites e valores padrão omitidos nesse fuso em vez de UTC. Quando timezone está definido, Bird rejeita offsets numéricos de UTC como +05:45 nos limites de instante. Use instantes Z ou dias do calendário.
Detalhamentos
Sete endpoints segmentam os mesmos números de entrega por uma dimensão:
- Para onde foi: /countries (o país de destino) e /carriers (a operadora que processou).
- O que você enviou: /originators (o endereço do remetente usado no envio), /categories e /tags.
- Como terminou: /statuses (uma linha por status de ciclo de vida com atividade) e /error-codes.
Todos ficam em /v1/sms/stats/. As linhas de país, operadora, originador, categoria, tag e código de erro são classificadas por sort e limitadas por limit (padrão 50, máximo 200). Suas respostas incluem total, o número de valores distintos na janela, para que você possa detectar um resultado truncado. Linhas cuja métrica de ordenação é uma taxa com denominador zero aparecem por último. O detalhamento de status tem no máximo sete linhas e não possui os parâmetros sort ou limit.
Os seis detalhamentos classificados também podem retornar uma série curta por linha. Defina include_trend=true e escolha trend_grain=daily ou hourly. Tendências exigem limit de 50 ou menos e uma janela de no máximo 90 dias para buckets diários ou 720 horas para buckets horários.
sort tem como padrão accepted nos detalhamentos de volume e failed em /error-codes. O endpoint /error-codes agrupa pelo motivo de falha normalizado de Bird em vez de um código bruto da operadora. Seu valor também funciona com o filtro error_code em GET /v1/sms/messages, vinculando uma linha às suas mensagens.
/tags conta apenas mensagens com tags, e uma mensagem com várias tags é contada uma vez em cada uma. Suas linhas portanto não somam o total do período. Reconcilie um resultado de /tags com outro em vez de usar /summary.
/statuses retorna um status e uma contagem em vez do bloco completo de entrega. Cada linha conta mensagens observadas naquele status de ciclo de vida; uma mensagem pode aparecer em várias linhas.
Mensagens recebidas
Mais seis endpoints em /v1/sms/stats/inbound/ contam o que seus números receberam em vez do que você enviou: /summary, /daily e /hourly para os totais e a série, e /countries, /operators e /numbers para os detalhamentos. Eles aceitam os mesmos parâmetros de janela e fuso horário que seus equivalentes de envio.
Duas coisas diferem da família de envio. Cada linha traz uma contagem simples de received, sem bloco de entrega ou taxas, porque uma mensagem recebida não tem ciclo de vida de entrega para agregar. O endpoint /operators exclui mensagens cuja operadora de envio não foi informada pela operadora que encaminhou a mensagem, então suas linhas podem somar menos que /inbound/summary para o mesmo período. Use o resumo como total do espaço de trabalho; as linhas de operadora cobrem apenas mensagens com operadora informada.
Próximos passos
Analytics SMS conecta esses relatórios à análise de campanhas e investigação de entregas.
- Metrics: inspecione o painel que esses valores renderizam.
- Log SMS: inspecione as mensagens por trás dos agregados.
- Events: consuma o fluxo de eventos por trás dos agregados.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Entenda o conceitoWhat does a delivery receipt tell you?Siga o percurso de aprendizagemOperate messaging reliably
Obtenha um resumo de implementação