Skip to content

Campaigns

Your scheduled notification campaigns and their runs, and how to pause a campaign.

Campaigns are the scheduled notification campaigns your account sends by call or WhatsApp. These endpoints return each campaign’s schedule and channels and the runs it launched, and let you pause a campaign. Reading needs notifications:read; pausing needs notifications:write.

Endpoint Route Scope
List campaigns GET /v1/campaigns notifications:read
One campaign GET /v1/campaigns/{campaign_id} notifications:read
Pause a campaign PATCH /v1/campaigns/{campaign_id} notifications:write
A campaign’s runs GET /v1/campaigns/{campaign_id}/runs notifications:read
One run GET /v1/campaigns/{campaign_id}/runs/{run_id} notifications:read

Campaigns belong to the whole customer: a key limited to some venues gets 403 insufficient_scope. In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.

GET /v1/campaigns returns your campaigns, paged.

Parameter Type Default Rules
enabled true | false both Only the campaigns that are, or are not, enabled
limit 1 to 50 50 Campaigns per page
cursor string none meta.next_cursor of the previous page, with the same filters and the same limit
customer_id UUID the key’s customer See what each key reads
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 }
}
Field What it is
id The campaign’s identifier
enabled Whether it runs on its schedule
frequency When it runs, as a cron expression in timezone
timezone IANA zone of the schedule; null for older campaigns
integration_type The system its contacts come from, e.g. COVERMANAGER, BOOKLINE_CRM, CLOUDBEDS; others may appear
channels The channels its steps use, each once: CALL, WHATSAPP

GET /v1/campaigns/{campaign_id} returns the same fields, with an ETag header: the version to send as If-Match when you pause it. A campaign that is not your customer’s is 404 not_found.

PATCH /v1/campaigns/{campaign_id} with {"enabled": false} pauses the campaign: it stops running on its schedule. Send its ETag as If-Match (see Writing data).

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}'
  • Pausing does not stop a run in progress. Messages a run has already queued are still sent. To stop them, cancel the run in the Bookline portal.
  • Enabling a campaign is done in the portal, since it sends messages to your contacts. {"enabled": true} is 422 validation_failed.
  • A campaign already paused is answered as it is.

GET /v1/campaigns/{campaign_id}/runs returns the runs of one campaign, newest first: each run is one launch of the campaign.

Parameter Type Default Rules
limit 1 to 10 10 Runs per page
cursor string none meta.next_cursor of the previous page, with the same limit
customer_id UUID the key’s customer See what each key reads
Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/campaigns/<campaign_id>/runs"
Field What it is
id The run’s identifier
campaign_id The campaign it belongs to
status SCHEDULED, LAUNCHED, SUCCESS, ERROR or CANCELLED
started_at, ended_at When the run started and ended
notification_count Contacts the run started a notification sequence for

Runs launched while you page never make another run repeat or go missing. GET /v1/campaigns/{campaign_id}/runs/{run_id} returns one run; a run of another campaign is 404 not_found.

  • Only the fields on this page. The audience, the messages and templates, and each run’s contacts and errors are not part of the API.
  • Pausing only. Creating, editing and enabling campaigns is done in the portal.