Campañas
Tus campañas de notificaciones programadas y sus ejecuciones, y cómo pausar una campaña.
Las campañas son las campañas de notificaciones programadas que tu cuenta envía por llamada o por WhatsApp. Estos endpoints devuelven la programación y los canales de cada campaña y las ejecuciones que ha lanzado, y te permiten pausar una campaña. Para leer hace falta notifications:read; para pausar, notifications:write.
| Endpoint | Ruta | Permiso |
|---|---|---|
| Listar campañas | GET /v1/campaigns |
notifications:read |
| Una campaña | GET /v1/campaigns/{campaign_id} |
notifications:read |
| Pausar una campaña | PATCH /v1/campaigns/{campaign_id} |
notifications:write |
| Las ejecuciones de una campaña | GET /v1/campaigns/{campaign_id}/runs |
notifications:read |
| Una ejecución | GET /v1/campaigns/{campaign_id}/runs/{run_id} |
notifications:read |
Las campañas son de todo el cliente: una clave limitada a algunos locales recibe 403 insufficient_scope. En los ejemplos, $BASE es https://api.bookline.ai/v1 y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.
Listar campañas
Sección titulada «Listar campañas»GET /v1/campaigns devuelve tus campañas, paginadas.
| Parámetro | Tipo | Por defecto | Reglas |
|---|---|---|---|
enabled |
true | false |
ambas | Solo las campañas que están, o no están, activadas |
limit |
de 1 a 50 | 50 | Campañas por página |
cursor |
texto | ninguno | meta.next_cursor de la página anterior, con los mismos filtros y el mismo limit |
customer_id |
UUID | el cliente de la clave | Consulta qué lee cada clave |
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/campaigns?enabled=true"{ "data": [ { "id": "…", "enabled": true, "frequency": "0 10 * * *", "timezone": "Europe/Madrid", "integration_type": "COVERMANAGER", "channels": ["WHATSAPP"] } ], "meta": { "limit": 50, "next_cursor": null }}| Campo | Qué es |
|---|---|
id |
El identificador de la campaña |
enabled |
Si se ejecuta según su programación |
frequency |
Cuándo se ejecuta, como expresión cron en timezone |
timezone |
Zona IANA de la programación; null en campañas antiguas |
integration_type |
El sistema del que salen sus contactos, p. ej. COVERMANAGER, BOOKLINE_CRM, CLOUDBEDS; pueden aparecer otros |
channels |
Los canales que usan sus pasos, cada uno una vez: CALL, WHATSAPP |
Una campaña
Sección titulada «Una campaña»GET /v1/campaigns/{campaign_id} devuelve los mismos campos, con una cabecera ETag: la versión que tienes que enviar como If-Match al pausarla. Una campaña que no es de tu cliente es 404 not_found.
Pausar una campaña
Sección titulada «Pausar una campaña»PATCH /v1/campaigns/{campaign_id} con {"enabled": false} pausa la campaña: deja de ejecutarse según su programación. Envía su ETag como If-Match (consulta Escribir datos).
curl -s -X PATCH "$BASE/campaigns/<campaign_id>" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H 'If-Match: "<etag>"' \ -d '{"enabled": false}'- Pausar no detiene una ejecución en curso. Los mensajes que una ejecución ya ha puesto en cola se envían igualmente. Para detenerlos, cancela la ejecución en el portal de Bookline.
- Las campañas se activan en el portal, porque activarlas envía mensajes a tus contactos.
{"enabled": true}da 422validation_failed. - Una campaña ya pausada se devuelve tal como está.
Las ejecuciones de una campaña
Sección titulada «Las ejecuciones de una campaña»GET /v1/campaigns/{campaign_id}/runs devuelve las ejecuciones de una campaña, de la más reciente a la más antigua: cada ejecución es un lanzamiento de la campaña.
| Parámetro | Tipo | Por defecto | Reglas |
|---|---|---|---|
limit |
de 1 a 10 | 10 | Ejecuciones por página |
cursor |
texto | ninguno | meta.next_cursor de la página anterior, con el mismo limit |
customer_id |
UUID | el cliente de la clave | Consulta qué lee cada clave |
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/campaigns/<campaign_id>/runs"| Campo | Qué es |
|---|---|
id |
El identificador de la ejecución |
campaign_id |
La campaña a la que pertenece |
status |
SCHEDULED, LAUNCHED, SUCCESS, ERROR o CANCELLED |
started_at, ended_at |
Cuándo empezó y terminó la ejecución |
notification_count |
Contactos para los que la ejecución inició una secuencia de notificaciones |
Las ejecuciones lanzadas mientras paginas nunca hacen que otra se repita o se pierda. GET /v1/campaigns/{campaign_id}/runs/{run_id} devuelve una ejecución; una ejecución de otra campaña es 404 not_found.
Reglas de los datos
Sección titulada «Reglas de los datos»- Solo los campos de esta página. La audiencia, los mensajes y las plantillas, y los contactos y errores de cada ejecución no forman parte de la API.
- Solo pausar. Las campañas se crean, se editan y se activan en el portal.
Relacionado
Sección titulada «Relacionado»- Escribir datos: versiones, reintentos y el límite de escritura.
- Integraciones: los sistemas de los que tus campañas toman los contactos.
