La API Pública de Engage proporciona acceso programático a datos de campañas de engagement enviadas a través de canales de WhatsApp. A su vez, permite a los desarrolladores integrar capacidades de reporting, análisis y exportación de datos de campañas en sus aplicaciones y sistemas empresariales.
Características Principales:
- Listado de Campañas: acceso al catálogo completo de campañas dentro de un rango de fechas, con filtros por tipo de ejecución (one-time o recurrent).
- Detalles de Campaña: información granular a nivel de contacto individual, incluyendo estado de entrega, lectura e interacción, con soporte de paginación.
- Resumen de Métricas: estadísticas agregadas por campaña con porcentajes de lectura, interacción y error.
- Estadísticas Globales: métricas consolidadas del bot segmentadas por frecuencia temporal (diaria o semanal).
- Exportación de Datos: descarga de detalle de campañas en formato CSV.
URL Base: https://analytics-engage.agentbot.net
Autenticación: todas las solicitudes a la API requieren dos headers de autenticación.
| Header | Tipo | Descripción |
| X-Token | Token fijo | Identificador del bot (BotID).Determina el contexto de datos a consultar. |
| Authorization |
Bearer JWT | Token JWT de sesión del usuario autenticado (formato Bearer ). |
> Ejemplo de Headers
X-Token: eExNcFRrUmtOVFJsWkRKa01HRTNaalZrT0dGaFl6... |
Nota: El token JWT tiene expiración. Asegúrese de renovarlo antes de que expire para evitar respuestas 401 Unauthorized. El JWT se obtiene mediante autenticación OAuth contra el proveedor de identidad (Auth0).
Formato de Respuesta: las respuestas se devuelven en formato JSON por defecto. El endpoint /campaign/{name}/details soporta además exportación en CSV mediante el parámetro output=csv.
| Formato | Content-Type | Aplica a |
| JSON | application/json | Todos los endpoints (por defecto) |
| CSV | text/csv; charset=utf-8 | /campaign/{name}/details únicamente (con output=csv) |
Parámetros Comunes
Parámetros de Fecha: la mayoría de los endpoints requieren un rango de fechas como query parameters.
| Parámetro | Tipo | Formato | Descripción |
| from | string | YYYY-MM-DD HH:MM:SS (UTC) | Fecha y hora de inicio |
| to | string | YYYY-MM-DD HH:MM:SS (UTC) | Fecha y hora de fin |
> Ejemplo
from=2026-04-01 00:00:00 |
Nota: los valores deben estar URL-encoded en la query string (espacios como , dos puntos como : ).
↗️ Filtros Comunes:
| Parámetro | Tipo | Valores permitidos | Descripción |
| type | string | one-time, recurrent | Filtra campañas por tipo de ejecución |
Endpoints Disponibles:
| Método | Endpoint | Descripción | from/to | Filtros opcional |
| GET | /campaigns | Listado de campañas del bot | Sí | type |
| GET | /campaign/{name}/details | Detalle a nivel de contacto (paginado, exportable CSV) | Sí | type, output, limit, offset |
| GET | /campaign/{name}/summary | Resumen de métricas agregadas de una campaña | Sí | |
| GET | /stats | Estadísticas globales segmentadas por frecuencia | Sí | frequency, type |
Límites de Consulta:
| Endpoint | Restricción |
| /campaign/{name}/details | Rango máximo de 90 días entre from y to |
| /campaign/{name}/details | Límite máximo de 10.000 registros por request |
Códigos de estado HTTP:
Código |
Descripción |
200 |
Solicitud exitosa |
400 |
Solicitud mal formada (parámetros inválidos o faltantes) |
401 |
No autenticado (token inválido o expirado) |
403 |
No autorizado (sin permisos para el recurso solicitado) |
404 |
Recurso no encontrado (campaña inexistente) |
| 500 | Error interno del servidor |
Mediante la API, podrás obtener la información de los campos debajo. Para conocer cómo hacerlo, haz clic en los enlaces de cada respectivo título:
- GETSummary: retorna las métricas agregadas y el resumen estadístico de una campaña dentro de un rango de fechas.
- GET Stats: retorna métricas consolidadas de mensajes para un bot dentro de un rango de fechas. Los datos se segmentan según el parámetro de frecuencia.
- GET Campaigns: retorna el listado de campañas para un bot específico dentro de un rango de fechas.
- GET Details: retorna información granular a nivel de contacto individual para una campaña específica. Soporta paginación y exportación en CSV.