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.
List campaigns
Section titled “List campaigns”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 |
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 |
One campaign
Section titled “One campaign”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.
Pause a campaign
Section titled “Pause a campaign”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).
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 422validation_failed. - A campaign already paused is answered as it is.
A campaign’s runs
Section titled “A campaign’s runs”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 |
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.
Data rules
Section titled “Data rules”- 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.
Related
Section titled “Related”- Writing data: versions, retries and the write limit.
- Integrations: the systems your campaigns take contacts from.
