Ir al contenido

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.

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
Ventana de terminal
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

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.

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

Ventana de terminal
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 422 validation_failed.
  • Una campaña ya pausada se devuelve tal como está.

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
Ventana de terminal
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.

  • 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.
  • Escribir datos: versiones, reintentos y el límite de escritura.
  • Integraciones: los sistemas de los que tus campañas toman los contactos.