Skip to main content
Usa GET /api/v1/whatsapp/events con la llave de la empresa y el permiso whatsapp_events:read. Esta única respuesta contiene el reporte completo y su detalle paginado. Cobrix obtiene la empresa de la llave; no necesitas un token de Meta ni enviar companyId.

Primera consulta

Construye el tablero

  • Tarjetas: report.summary.sent, delivered, read y failed.
  • Gráfico y tabla diaria: report.daily, ordenado por fecha ascendente.
  • Detalle de confirmaciones: events, con page, limit y totalPages.
El reporte incluye las estadísticas importadas de Meta y las confirmaciones disponibles en una sola serie. No necesitas combinar fuentes ni consultar otro endpoint. report.history indica la disponibilidad y las cifras del histórico incluido, como respaldo del reporte.

Ejemplo: tablero de una empresa con histórico

Para el período 14 de agosto a 10 de septiembre de 2026, el siguiente ejemplo muestra 4.256 enviados y 4.198 entregados. Usa la llave de la empresa correspondiente; son cifras de ejemplo para ese período, no totales actuales de todas las empresas. Respuesta completa del mismo endpoint:
events: [] no contradice las tarjetas. En este ejemplo hay estadísticas históricas agregadas, pero no confirmaciones individuales recuperadas para ese período. El summary original cuenta ese detalle y permanece en cero; las tarjetas usan report.summary. No sumes summary ni report.history a report.summary: el reporte ya está combinado.

Contrato y significado de las cifras

El summary original sigue contando eventos almacenados, incluidos callbacks repetidos. Paginar no cambia sus totales. report.summary cuenta una observación por messageId y estado dentro del filtro, más el histórico que corresponda. Un mensaje puede tener varios estados: no sumes enviados y entregados como mensajes distintos. Para evitar duplicar cifras, un día importado sustituye las observaciones de envío y entrega del mismo número emisor y empresa. Se utiliza la fecha del estado informada por Meta para detectar la superposición, o la recepción si falta esa fecha. Las observaciones de otros emisores o empresas se conservan. Una estadística histórica no crea destinatarios, messageId ni eventos ficticios. Los días observados se agrupan por recepción en Cobrix. Los importados corresponden al día estadístico de Meta. Ambos se muestran en America/Caracas; source identifica events, meta_analytics o mixed. La serie contiene días con datos; un día ausente no prueba que no hubo envíos. null significa información no disponible. Si el histórico no incluye lecturas o fallos, esos totales permanecen null; no se presentan como cero. Las entregas diarias pueden superar los envíos por entregas de mensajes anteriores. La diferencia entre ambas cifras no demuestra fallos.

Esta semana, este mes o un rango de fechas

La API recibe dateFrom y dateTo. Los botones «Esta semana» y «Este mes» son opciones del tablero: tu aplicación calcula las fechas y las envía. No existen parámetros week, month ni period. Por ejemplo, si hoy fuera 12 de septiembre de 2026, con semanas de lunes a domingo y calendario de America/Caracas: El final de semana o mes puede ser posterior a hoy: la respuesta sólo contiene datos disponibles al consultar. Para un período hasta hoy, usa el final del día actual; para cortar en este instante, usa su fecha y hora exactas, teniendo en cuenta la exclusión de días históricos parciales.
Para consultar el mes, reemplaza ambas fechas por las de «Este mes». Para un rango personalizado, usa las fechas del selector. Se admite enviar sólo uno de los límites; el extremo omitido queda sin restricción. Usa --data-urlencode o URLSearchParams para codificar correctamente las fechas y teléfonos.

Filtros

Conserva los filtros y errores originales: dateFrom, dateTo, phone, status, page y limit. Las fechas requieren zona horaria y los límites son inclusivos sobre la recepción de los eventos. Sin fechas, consulta el histórico disponible. La página sólo afecta al detalle; el reporte cubre todo el resultado. El histórico sólo permite días completos y estados enviados o entregados. Con phone, read o failed, el reporte utiliza las confirmaciones individuales disponibles y marca report.history.availability: "unsupported_filter". Un estado seleccionado deja los demás contadores del reporte en cero. Para incluir un día histórico completo, consulta desde 00:00:00-04:00 hasta 23:59:59.999-04:00. Los días históricos parciales se omiten y se indica partial_days_excluded; las confirmaciones individuales dentro del intervalo permanecen disponibles. no_data indica que no hay histórico importado para ese filtro. La página, los totales y el reporte se obtienen de la misma instantánea de lectura. El límite sigue siendo 60 solicitudes por minuto por llave; respeta Retry-After ante 429. Las confirmaciones se distinguen de la entrega de webhooks de Cobrix al integrador. Ninguna cifra de este reporte representa pagos recibidos.

Cómo mostrar lecturas y fallos

  • null → «—» o «No disponible»: el histórico incluido no proporciona esa métrica. No conviertas null a cero.
  • 0 → «0»: no hay confirmaciones de ese estado en el resultado disponible; no garantiza que se hayan recibido todas las confirmaciones de Meta.
  • Número positivo: conteo disponible para el filtro seleccionado.
Si un día histórico tiene lecturas o fallos desconocidos, el total de esa métrica también queda en null, aunque haya confirmaciones recientes. La tabla diaria permite ver cuáles días sí tienen el dato. Con un filtro de estado, los otros estados se ponen en cero porque están excluidos del resultado. Desde que los envíos estén asociados a la empresa y sus confirmaciones lleguen a Cobrix, un período nuevo sin histórico incompleto permite contar enviados, entregados, leídos y fallidos. Una confirmación puede llegar después del envío. No leer un mensaje, no recibir una lectura o no tener confirmación de entrega no equivale a un fallo.

Ejemplo de integración del tablero

Este ejemplo de JavaScript en el servidor recibe las fechas del selector, realiza una llamada y prepara los campos del tablero. Guarda COBRIX_API_KEY en el servidor y resuelve la llave desde la empresa autorizada en tu aplicación; no la incluyas en JavaScript público ni en la URL.
Al cambiar fechas, empresa, estado o teléfono, vuelve a page=1 y consulta de nuevo. Cancela o descarta respuestas anteriores para que una consulta lenta no reemplace el filtro actual. No sustituyas un error HTTP por tarjetas en cero. Para actualización periódica, una consulta por minuto mientras el tablero está visible es suficiente como punto de partida. Coordina las consultas que compartan la misma llave, evita solicitudes superpuestas y ante 429 espera los segundos de Retry-After antes de reintentar. El ejemplo realiza una sola consulta; no crea un temporizador automáticamente. Los datos cambian cuando llegan nuevas confirmaciones o se incorpora evidencia. Para seguimiento de detalle, deduplica por id y vuelve a consultar fechas recientes: la paginación entre llamadas no congela el conjunto de datos. No se garantiza la reconstrucción de confirmaciones históricas no recibidas.