API de estadísticas de SMS
Cada valor del panel Metrics proviene de la API de estadísticas de SMS. Usa los mismos agregados en un panel, almacén de datos o comprobación de estado. Los endpoints de solo lectura, con alcance de espacio de trabajo, requieren una clave API con acceso de lectura al scope sms. Una respuesta coincide con el panel para el mismo rango y filtros.
Los métodos tipados se incluyen en los SDKs de TypeScript, Python, PHP y Go bajo sms.stats, la bird CLI los expone como bird sms stats, y un agente accede a ellos a través de las herramientas MCP sms_stats_*. Los esquemas completos de solicitud y respuesta están en la referencia de API.
El agregado y la serie temporal
Tres endpoints cubren la parte superior del panel:
- GET /v1/sms/stats/summary devuelve una fila agregada para toda la ventana: los conteos del ciclo de vida (accepted, sent, delivered, undelivered, failed, rejected, expired), las tasas derivadas delivery_rate y failure_rate, y los percentiles de latencia de procesamiento, entrega y total (p50, p95, p99). Pasa compare=previous_period y la respuesta también incluye la ventana precedente de igual duración y el cambio respecto a ella.
- GET /v1/sms/stats/daily y GET /v1/sms/stats/hourly devuelven los conteos del ciclo de vida con una fila por día o por hora. Las tasas y la latencia son cifras de toda la ventana, así que léelas de /summary en lugar de por intervalo.
Las tasas se devuelven en forma decimal, así que un delivery_rate de 0.9739 es 97,39 %. Una tasa cuyo denominador es cero es null, que es como un período sin mensajes aceptados reporta delivery_rate en lugar de mostrar 0. Las cifras usan la hora de envío del mensaje. Una entrega confirmada hoy para un mensaje aceptado ayer se atribuye al día de ayer. En una ventana reciente, delivered queda por debajo del valor final mientras siguen llegando informes de entrega. Trata las últimas horas como provisionales.
Los conteos usan agregación aproximada de mensajes distintos. Un mensaje puede contribuir a más de un estado del ciclo de vida a medida que avanza, así que los conteos por estado no son mutuamente excluyentes y no deben sumarse como total de mensajes. Usa los mensajes aceptados como denominador de la tasa de salida. Estos agregados operativos no son un registro de facturación; usa los registros de mensajes y facturación para la conciliación.
Elegir la ventana
from y to aceptan un día calendario (YYYY-MM-DD) o un instante RFC 3339, y las formas que acepta cada endpoint difieren:
| Endpoint | Límites | Ventana máxima |
|---|---|---|
| /summary | Ambos días, o ambos instantes | 365 días, o 720 horas con instantes |
| /daily | Días calendario | 365 días |
| /hourly | Instantes RFC 3339 | 720 horas (30 días) |
Los límites con instantes tienen granularidad horaria, lo que permite hacer una ventana móvil de 24 horas en una sola solicitud. En /summary, mezclar un día con un instante devuelve un 422.
Establece timezone con un identificador IANA como America/New_York para calcular los límites y los valores predeterminados omitidos en esa zona en lugar de UTC. Cuando timezone está definido, Bird rechaza offsets numéricos UTC como +05:45 en los límites de instante. Usa instantes Z o días calendario en su lugar.
Desgloses
Siete endpoints dividen las mismas cifras de entrega por una dimensión:
- Adónde fue: /countries (el país de destino) y /carriers (el operador que lo gestionó).
- Qué enviaste: /originators (la dirección de remitente con la que salió), /categories y /tags.
- Cómo terminó: /statuses (una fila por estado del ciclo de vida con actividad) y /error-codes.
Todos residen bajo /v1/sms/stats/. Las filas de país, operador, originador, categoría, etiqueta y código de error se ordenan por sort y se limitan con limit (predeterminado 50, máximo 200). Sus respuestas incluyen total, el número de valores distintos en la ventana, para que puedas detectar un resultado recortado. Las filas cuya métrica de ordenación es una tasa con denominador cero aparecen al final. El desglose por estado tiene como máximo siete filas y no tiene parámetros sort ni limit.
Los seis desgloses ordenados también pueden devolver una serie corta por fila. Establece include_trend=true y elige trend_grain=daily o hourly. Las tendencias requieren un limit de 50 o menos y una ventana de como máximo 90 días para intervalos diarios o 720 horas para intervalos horarios.
sort toma por defecto accepted en desgloses de volumen y failed en /error-codes. El endpoint /error-codes agrupa por la razón de fallo normalizada de Bird en lugar de un código de operador sin procesar. Su valor también funciona con el filtro error_code en GET /v1/sms/messages, vinculando una fila con sus mensajes.
/tags cuenta solo mensajes etiquetados, y un mensaje con varias etiquetas se cuenta una vez bajo cada una. Sus filas por tanto no suman el total del período. Concilia un resultado de /tags con otro en lugar de usar /summary.
/statuses devuelve un estado y un conteo en lugar del bloque de entrega completo. Cada fila cuenta los mensajes observados en ese estado del ciclo de vida; un mensaje puede aparecer en varias filas.
Mensajes recibidos
Seis endpoints más bajo /v1/sms/stats/inbound/ cuentan lo que tus números recibieron en lugar de lo que enviaste: /summary, /daily y /hourly para los totales y la serie, y /countries, /operators y /numbers para los desgloses. Aceptan los mismos parámetros de ventana y zona horaria que sus equivalentes de salida.
Dos cosas difieren de la familia de salida. Cada fila lleva un conteo simple received, sin bloque de entrega ni tasas, porque un mensaje entrante no tiene ciclo de vida de entrega que agregar. El endpoint /operators excluye los mensajes cuyo operador de envío el carrier no reportó, así que sus filas pueden sumar menos que /inbound/summary para el mismo período. Usa el resumen como total del espacio de trabajo; las filas de operador cubren solo mensajes con un operador reportado.
Próximos pasos
Analíticas de SMS conectan estos informes con la revisión de campañas y la investigación de entregas.
- Metrics: consulta el panel que muestra estos valores.
- Log de SMS: inspecciona los mensajes detrás de los agregados.
- Events: consume el flujo de eventos detrás de los agregados.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Comprender el conceptoWhat does a delivery receipt tell you?Seguir la ruta de aprendizajeOperate messaging reliably
Obtener un resumen de implementación