Métricas de WhatsApp
La página Metrics en el panel de Bird muestra cómo va tu canal WhatsApp: cuántos mensajes llegaron al dispositivo del destinatario, si tu tasa de fallo está subiendo y qué tan rápido se movió todo. Esta guía recorre esa página, qué significa cada número y cuándo actuar.
Las métricas son la vista agregada de todo lo que envía tu espacio de trabajo. Para el ciclo de vida de un mensaje individual (si este número lo recibió y cuándo), consulta el registro de WhatsApp y los eventos.
Lee tus métricas
La página Metrics se encuentra en WhatsApp → Metrics dentro del panel de Bird; es visible para los miembros del espacio de trabajo que tengan los permisos de lectura de WhatsApp y de lectura de Analytics. Todos los números respetan el selector de rango (últimas 24 horas, 7, 30 o 90 días). Los eventos nuevos aparecen tras la agregación y replicación, así que el período más reciente es provisional.
Las tasas de salida usan el momento de aceptación de cada mensaje. Un acuse de entrega que llega hoy para un mensaje aceptado ayer cuenta en el día de ayer, junto con el accepted de ese mensaje. Cada rango sigue los mensajes aceptados en él a medida que llegan las observaciones. Las horas recientes pueden subreportar delivered mientras aún llegan acuses. accepted es el denominador de las tarjetas de tasa de entrega y tasa de fallo.
Los conteos representan mensajes distintos para cada evento observado y pueden ser aproximados a gran escala. No son un embudo obligatorio: un acuse de lectura puede existir sin un acuse de entrega, y las observaciones faltantes pueden dejar huecos entre etapas. Las estadísticas de grupo también cuentan mensajes, no destinatarios; la primera entrega observada a un participante puede incrementar el conteo de entregados antes de que todos los miembros del grupo hayan recibido el mensaje.
Los mosaicos de resumen
La fila de mosaicos en la parte superior es tu verificación rápida de salud:
- Tasa de entrega: mensajes entregados como proporción de los aceptados. El mosaico muestra Healthy por encima de 95 %. En ese valor o por debajo, algo no está llegando a los dispositivos: números inválidos, una ventana de atención expirada o un problema de plantilla. El histograma de causas de fallo (consulta Tasa de fallo y sus causas) te indica cuál.
- Tasa de fallo: la proporción de mensajes aceptados que terminaron failed. El mosaico muestra tu tasa frente a un límite de 5 % con una barra de progreso; alcanzarlo cambia el mosaico a Risk. Una tasa de fallo alta sostenida suele apuntar a la calidad de la lista, una ventana de atención al cliente expirada o una limitación de frecuencia de Meta.
- Aceptados: el conteo bruto de mensajes aceptados en el rango, con la cantidad entregada a la red de WhatsApp (sent).
Los umbrales de 95 % y 5 % son las referencias que usamos para colorear los mosaicos. Son deliberadamente conservadores; un mosaico puede mostrar Healthy y aún tener margen de mejora.
Entregas en el tiempo
El gráfico de entregas traza el volumen de mensajes aceptados, entregados y fallidos a lo largo del rango para que puedas detectar tendencias y picos puntuales: una campaña fallida, una importación de lista de números que salió mal, una plantilla que empezó a ser rechazada. El tamaño del intervalo sigue al rango (por hora para 24 horas, por día para ventanas más largas).
Tasa de fallo y sus causas
Debajo del gráfico de entregas en la página de métricas, una línea de tasa de fallo traza la tasa por intervalo a lo largo del rango, mientras que el mosaico de resumen de tasa de fallo contiene la cifra de toda la ventana. Un histograma desglosa los fallos por código de error normalizado, ordenados por cantidad con la proporción de cada código sobre los mensajes fallidos. Las razones de fallo de WhatsApp son un conjunto abierto, así que el histograma lista los códigos que realmente ocurrieron en el rango en lugar de una lista fija; una barra creciente en un código te lleva directo a la solución.
Latencia de entrega
La tabla de latencia reporta dos etapas en los percentiles p50, p95 y p99:
- Procesamiento: desde la aceptación del mensaje hasta el envío exitoso al proveedor de WhatsApp. Un percentil lento aquí requiere investigar la ruta de envío, incluido el envío al proveedor.
- Total: de extremo a extremo, desde la aceptación del mensaje hasta que WhatsApp confirma la entrega al dispositivo del destinatario. La diferencia entre Total y Procesamiento es la red de WhatsApp y el dispositivo del destinatario, que no controlamos. Un teléfono sin conexión durante una hora estira Total sin modificar Procesamiento.
Usa p95/p99 para detectar los casos más lentos: una mediana sana con un p99 lento suele apuntar a una plantilla o un destino rezagado. La latencia es una cifra de toda la ventana; una etapa o percentil sin datos para el rango muestra un marcador de posición.
Desgloses
El panel Breakdowns divide los mismos números de entrega para que puedas aislar un problema hasta su origen:
- Por número: el volumen de aceptados, entregados y fallidos de cada número de negocio emisor con su tasa de entrega, para que puedas comparar remitentes lado a lado.
- Por plantilla: el mismo desglose por plantilla, para encontrar la plantilla que arrastra una tasa hacia abajo.
- Por categoría de plantilla: el mismo desglose por las categorías de plantilla de Meta, el corte que también determina tu gasto.
- Por etiqueta: las etiquetas que adjuntas a un envío, el corte más flexible: etiqueta una campaña, plantilla o variante de experimento y compáralas directamente.
- Por país: el mismo desglose por país de destino, para ver si un problema de entrega sigue a un mercado en lugar de a un remitente o una plantilla. Un destinatario cuyo país no pueda determinarse (un número que parece un número de teléfono pero no pertenece a ningún país, o un rango internacional como freephone) se cuenta bajo ZZ, el mismo marcador de posición que usa el desglose por país de SMS. Los envíos a grupos se excluyen porque un grupo puede abarcar varios países y no tiene un solo destino. La cobertura histórica por país anterior a la implementación de este desglose puede estar incompleta, con observaciones de entrega o lectura sin conteos de aceptación correspondientes. El historial agregado sobrevive a la ventana de detalle de mensajes de 30 días; esperar 30 días no repara esas cohortes anteriores.
Cada fila también recibe un estado derivado (Healthy, Watching o Throttled) basado en sus propias tasas de entrega y fallo, para que un número o categoría con problemas destaque sin que tengas que leer cada columna. Cada pestaña ordena las filas principales del rango; cuando una dimensión tiene más valores distintos de los que caben, el panel indica "Top N of M".
Acceso programático
Los agregados detrás de esta página también son una API pública. Los métodos tipados están disponibles en los SDKs de TypeScript, Python, PHP y Go bajo bird.whatsapp.stats, la CLI de bird los expone como bird whatsapp stats <verb>, y un agente accede a ellos a través de las herramientas MCP de whatsapp_stats_*. Los esquemas completos de solicitud y respuesta están en la referencia de API.
El agregado y la serie temporal
GET /v1/whatsapp/stats/summary devuelve una fila agregada para la ventana: conteos del ciclo de vida (aceptados, enviados, entregados, fallidos, rechazados) con tasas de entrega y fallo, interacción (read, read_rate) y percentiles de latencia (p50, p95, p99) para tres etapas: procesamiento, entrega y total. /daily y /hourly devuelven los mismos conteos del ciclo de vida y de lectura, una fila por día o por hora del calendario, cada una con sus propios percentiles de latencia; solo las tasas (delivery_rate, failure_rate, read_rate) son cifras de toda la ventana, léelas desde /summary. Los tres aceptan un filtro de dimensión a la vez: template, category, tag o phone_number. Aquí, phone_number restringe a un único remitente de negocio, en formato E.164, no el contacto por el que filtra en el parámetro deprecado phone_number de GET /v1/whatsapp/messages.
La tasa de lectura es read / delivered, mientras que las tasas de entrega y fallo usan accepted. Un denominador cero devuelve null, lo que significa que la tasa no se puede calcular. La tasa de lectura no está limitada a 100 %, así que las observaciones de entrega faltantes pueden producir un valor más alto; esto es un hueco de observación que investigar, no evidencia de que más de la totalidad de destinatarios leyó el mensaje.
Los percentiles de latencia usan muestras registradas. La ausencia de una muestra de latencia de entrega no implica latencia cero, y la latencia total puede estar presente cuando la marca de tiempo intermedia de envío no estaba disponible. No promedies percentiles finalizados de intervalos separados. Los eventos reproducidos pueden afectar las distribuciones de latencia incluso cuando los conteos de mensajes distintos permanecen deduplicados.
Cuando está presente, data_as_of reporta el grado de actualización de la agregación. No prueba que todos los callbacks del proveedor hayan llegado ni que la facturación se haya liquidado. Un valor de actualización null significa que no estaba disponible para esa respuesta.
Elegir la ventana
from y to aceptan un día calendario o un instante RFC 3339, pero las formas que acepta cada endpoint difieren:
| Endpoint | Límites | Ventana máxima |
|---|---|---|
| /summary | Ambos días calendario, o ambos instantes RFC 3339 | 365 días, o 720 horas con instantes |
| /daily | Solo días calendario | 365 días |
| /hourly | Solo instantes RFC 3339 | 720 horas (30 días) |
En /summary, mezclar un límite de día con un límite de instante devuelve 422. Los límites de instante se redondean hacia abajo a la hora en /summary y /hourly, los únicos dos que los aceptan. Establece timezone con un identificador IANA para calcular los límites de día y hora localmente en vez de en UTC; una vez establecido, un desplazamiento numérico UTC como +05:45 en un límite de instante se rechaza. Añade compare=previous_period a /summary para obtener la ventana anterior de igual duración y la variación respecto a ella.
Desgloses
Seis endpoints clasifican los mismos números de entrega por una dimensión, cada uno ya de una sola dimensión, por lo que ninguno acepta un filtro: por número, por plantilla, por categoría de plantilla, por etiqueta y por código de error (solo mensajes fallidos, agrupados por razón de fallo normalizada). Las filas se ordenan por volumen aceptado (conteo de fallos en códigos de error) y se limitan a limit (por defecto 50, máximo 200). Un envío sin valor para una dimensión está ausente de ese desglose: un envío libre no resuelve ninguna plantilla, y un envío sin etiqueta ninguna etiqueta. Un mensaje con varias etiquetas puede aparecer en varias filas de etiqueta, así que sumar esas filas no da el volumen único del espacio de trabajo. Compara un desglose consigo mismo a lo largo del tiempo. Cada fila excepto la de código de error también incluye sus propios percentiles de latency. Un sexto endpoint, por país, agrupa los mismos números por el mercado de destino del destinatario; un destinatario cuyo país no pueda resolverse se cuenta bajo ZZ, y los envíos a grupos están ausentes porque un envío puede abarcar varios países.
Mensajes recibidos
Cuatro endpoints bajo /v1/whatsapp/stats/inbound/ cubren lo que tus números recibieron en lugar de lo que enviaron: resumen, diario, por hora y por número de teléfono. Cada fila lleva solo un conteo de received y sigue el momento de ocurrencia del mensaje entrante. Un mensaje recibido no tiene un ciclo de vida de entrega saliente que desglosar. Estos están anidados bajo bird.whatsapp.stats.inbound en los SDKs y bird whatsapp stats inbound <verb> en la CLI.
Conciliación por mensaje
Los endpoints de estadísticas responden preguntas agregadas; no reemplazan las consultas por mensaje. Para confirmar qué pasó con un mensaje, consume los eventos de webhook a medida que ocurren, o pagina a través de GET /v1/whatsapp/messages y el endpoint de eventos de cada mensaje, cuyos filtros (estado, destinatario, etiqueta, ventana de tiempo) cubren la mayoría de los trabajos de conciliación.
Próximos pasos
- Analíticas de WhatsApp: conecta observaciones de mensajes con resultados confirmados de clientes
- Registro de WhatsApp: la vista por mensaje detrás de los números agregados
- Eventos: el flujo del ciclo de vida por mensaje del que se derivan las métricas
- Envío de mensajes de WhatsApp: categorías, etiquetas y el modelo de costo por mensaje
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación