WhatsApp: confirmaciones y totales

Consulta GET /api/v1/whatsapp/events con tu llave habitual y el permiso whatsapp_events:read. Actívalo en Configuración → Integraciones → Llaves API, al crear o editar la llave. Las llaves existentes no lo reciben automáticamente. La empresa se obtiene de la llave. El reporte incluye confirmaciones de todos sus orígenes: recordatorios automáticos, envíos desde Cobrix y otras integraciones, siempre que exista evidencia exacta de pertenencia. No necesitas enviar companyId, firma HMAC ni idempotencia.

Primera consulta

curl --get 'https://api.cobrix.co/api/v1/whatsapp/events' \
  --header "Authorization: Bearer $COBRIX_API_KEY" \
  --data-urlencode 'dateFrom=2026-09-08T00:00:00-04:00' \
  --data-urlencode 'dateTo=2026-09-08T23:59:59.999-04:00' \
  --data-urlencode 'limit=20'

En sandbox usa https://sandbox-api.cobrix.co/api/v1/whatsapp/events. Cada despliegue consulta su propia base de datos.

Leer el resultado

{
  "events": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "messageId": "wamid.example",
      "status": "delivered",
      "recipientPhone": "584121234567",
      "receivedAt": "2026-09-08T14:30:00.000Z",
      "errorCode": null,
      "errorTitle": null
    }
  ],
  "summary": {
    "total": 1,
    "sent": 0,
    "delivered": 1,
    "read": 0,
    "failed": 0
  },
  "page": 1,
  "limit": 20,
  "totalPages": 1,
  "coverage": {
    "status": "partial",
    "unit": "events",
    "attribution": "confirmed"
  },
  "report": {
    "timezone": "America/Caracas",
    "summary": {
      "sent": 0,
      "delivered": 1,
      "read": 0,
      "failed": 0
    },
    "daily": [
      {
        "date": "2026-09-08",
        "sent": 0,
        "delivered": 1,
        "read": 0,
        "failed": 0,
        "source": "events"
      }
    ],
    "history": {
      "availability": "no_data",
      "sent": 0,
      "delivered": 0
    }
  }
}

report.summary alimenta las tarjetas y report.daily el gráfico y la tabla por día. El histórico y la actividad disponible ya están combinados.
events contiene la página solicitada; el summary original cuenta los eventos almacenados de todo el resultado filtrado.
status, phone, dateFrom y dateTo se aplican también a los totales. Al filtrar delivered, los demás estados quedan en cero.
Los eventos se ordenan por recepción descendente y luego por identificador descendente. page empieza en 1; limit vale 20 por defecto y admite hasta 100.
Una página fuera del resultado devuelve events: [] y conserva los totales. Sin eventos individuales, el summary original y totalPages son cero; report puede seguir incluyendo histórico agregado.
Las fechas filtran receivedAt, el instante en que Cobrix recibió la confirmación, con límites inclusivos. Incluye segundos y zona horaria; un rango invertido se rechaza. Sin fechas se consulta el histórico disponible.
phone busca una coincidencia parcial y admite hasta 64 caracteres. Usa --data-urlencode para conservar signos como +.

Cada respuesta usa una misma instantánea para página, totales y reporte. Entre solicitudes pueden llegar eventos o incorporarse nueva evidencia; la paginación no es una exportación congelada del histórico. Para guardar registros, deduplica por id y vuelve a consultar períodos recientes.

Semana, mes y fechas personalizadas

Usa dateFrom y dateTo para todas estas opciones; la API no recibe period, week ni month. Tu tablero calcula los límites en la zona horaria elegida. Para días completos de Caracas, usa 00:00:00-04:00 y 23:59:59.999-04:00. Consulta los ejemplos de semana, mes y rango. El histórico agregado sólo se incluye para días completos y sin filtro de teléfono; admite estados sent y delivered. Con phone, read o failed se consultan las confirmaciones individuales disponibles. report.history.availability explica las exclusiones. Paginar el detalle no cambia report.summary ni report.daily.

Interpretar los estados

Estado	Significado
`sent`	Meta informó que el mensaje salió; no confirma entrega.
`delivered`	Meta confirmó la entrega al destinatario.
`read`	Meta confirmó una lectura.
`failed`	Meta informó un error; consulta `errorCode` y `errorTitle`.

El summary original cuenta eventos almacenados, no mensajes únicos: un mismo messageId puede tener varios estados. No se incluyen pendientes, envíos en proceso ni otros estados almacenados fuera de estos cuatro valores. Sólo se exponen registros con una empresa de origen confirmada mediante evidencia exacta del mensaje o un emisor exclusivo verificado. Se excluyen coincidencias por teléfono, atribuciones ambiguas y eventos sin evidencia. El histórico puede ampliarse cuando se incorpore evidencia. La ausencia de un evento no demuestra fallo ni ausencia de envío. Para comparar con el panel, selecciona la misma empresa, fechas y filtros, y Sólo empresa confirmada.

Límites y errores

El límite independiente es de 60 solicitudes por minuto por llave, en ventanas fijas compartidas entre réplicas. Las respuestas autorizadas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (Unix, segundos). Un 429 incluye Retry-After; espera ese número de segundos.

HTTP	Motivo
`401`	Llave inválida, revocada, vencida o integrador inactivo.
`403`	Falta `whatsapp_events:read` o la empresa está inactiva.
`422`	Filtro inválido, desconocido o rango invertido.
`429`	Límite de solicitudes alcanzado.
`500` / `503`	Error interno o limitador temporalmente no disponible.

Los errores usan el formato compacto message, code, code_name y, cuando corresponde, errors. La auditoría guarda metadatos operativos sin consultas, teléfonos, credenciales ni contenido de los eventos.

Diferencia con los webhooks salientes

Este endpoint consulta confirmaciones de WhatsApp recibidas de Meta. La entrega de webhooks de Cobrix describe las llamadas de Cobrix al servidor del integrador. Una respuesta HTTP exitosa de ese servidor no demuestra que WhatsApp entregó o leyó el mensaje.

Cobertura del reporte

La respuesta incluye coverage: { "status": "partial", "unit": "events", "attribution": "confirmed" }. El summary original representa confirmaciones almacenadas con empresa acreditada, no el total de envíos ni mensajes únicos. coverage describe ese detalle; el alcance del histórico agregado se indica en report.history. Un resultado vacío no demuestra que no hubo envíos. La recuperación de evidencia histórica puede incorporar eventos que antes no tenían atribución. Los estados de aceptación en el servicio de envío y los recordatorios del calendario son medidas diferentes. Para comparar API y panel, usa la misma empresa, fechas de recepción y «Sólo empresa confirmada». Las confirmaciones de emisores que no hayan llegado a Cobrix no se pueden reconstruir a partir de una respuesta de aceptación de Meta.

Tablero diario e histórico

La misma respuesta de GET /api/v1/whatsapp/events incluye report.summary para las tarjetas y report.daily para el gráfico y la tabla. Combina el histórico importado y las confirmaciones disponibles sin duplicar el mismo emisor y día. El detalle events, su summary y la paginación conservan su contrato. Consulta el ejemplo de tablero. Los valores read y failed de report pueden ser null si el histórico incluido no tiene esas métricas. Muestra «No disponible»; no los conviertas a cero. Un período nuevo basado en confirmaciones individuales tiene conteos numéricos, sujetos a las confirmaciones recibidas. Si lo combinas con histórico incompleto, el total de la métrica desconocida sigue siendo null.

​Primera consulta

​Leer el resultado

​Semana, mes y fechas personalizadas

​Interpretar los estados

​Límites y errores

​Diferencia con los webhooks salientes

​Cobertura del reporte

​Tablero diario e histórico