> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp: confirmaciones y totales

> Consulta las confirmaciones de Meta de tu empresa con una sola llamada

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

```bash theme={null}
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

```json theme={null}
{
  "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](/guides/webhooks/delivery) 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.