Campaigns

Outbound programs that call or message many recipients, orchestrated durably.

A campaign runs an agent against many recipients — outbound voice calls, WhatsApp conversations, or WhatsApp-with-voice-escalation. Campaigns are orchestrated durably so they survive restarts, respect business hours, and retry safely.

Types

campaign_type	What it does
voice	Outbound phone calls to each recipient.
whatsapp	WhatsApp text conversations driven by the agent.
whatsapp_voice	Sends a WhatsApp template, then escalates to a voice call when the recipient wants one. See the WhatsApp guide.

Lifecycle

A campaign is a reusable template: you configure it as a draft, publish to lock the config, then start runs against the current recipient list. A finished campaign is terminal — clone it to run again with a fresh recipient set.

• Config PATCH is accepted while a campaign is draft, scheduled, or paused; published, running, and finished campaigns return 409.
• start requires the campaigns:write scope (no admin role needed), at least one recipient (400 otherwise), and the Campaign Engine to be available (503 otherwise). It works from draft, published, scheduled, or paused. Bound agents must be published.
• Finished campaigns (completed / failed / cancelled) are terminal and read-only — re-running in place is disabled so a previous run’s recipients and results can’t be destroyed by accident.
• clone duplicates the config into a new draft (no recipients copied) — the supported way to run a finished campaign again. The clone records its source in cloned_from_campaign_id.

See the Campaign lifecycle guide for the full run mechanics.

Recipients

Recipients are phone numbers (or WhatsApp contacts) plus their per-recipient variables, deduplicated per (campaign, phone). Add them one at a time or bulk-import a CSV or .xlsx file.

Each recipient moves through its own states:

pending → scheduled → calling → completed / no_answer / failed / cancelled

Scheduling & retries

Campaigns respect a timezone and business hours (default Mon–Fri, 09:00–18:00) and apply retry delays between attempts. These keys live under the campaign’s schedule:

Setting	Range / default
max_attempts	1–10
call_timeout_seconds	30–3600 (default 600)
retry_delay_minutes	1–10080 (default 120)
max_recipients_per_campaign	default 10,000, max 50,000

Endpoints

Method	Path	Scope
POST	/campaigns	campaigns:write
GET	/campaigns · /campaigns/{id}	campaigns:read
PATCH · DELETE	/campaigns/{id}	campaigns:write
POST	/campaigns/{id}/recipients · /recipients/import	campaigns:write
GET	/campaigns/{id}/recipients · /attempts · /events	campaigns:read
POST	/campaigns/{id}/publish · /start · /pause · /clone	campaigns:write

Campaigns require the campaign worker and Campaign Engine to be running. Without them, start/pause return 503.

Campaign lifecycle

How a run executes.

WhatsApp

Template + voice-escalation flow.