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
}

events contiene la página solicitada; summary cuenta 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 coincidencias, todos los totales y totalPages son cero.
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 y totales. 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.

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`.

Se cuentan 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 el identificador exacto del mensaje. 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.

​Primera consulta

​Leer el resultado

​Interpretar los estados

​Límites y errores

​Diferencia con los webhooks salientes

Primera consulta

Leer el resultado

Interpretar los estados

Límites y errores

Diferencia con los webhooks salientes