Skip to main content
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

​
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. PATCH can’t change status (400 — use publish, start and pause), nor campaign_type once the campaign has started (409).
  • start requires the campaigns:write scope (no admin role needed), at least one recipient (400 otherwise), and the Campaign Engine to be configured (503 otherwise). From draft or published it schedules the run; on a scheduled campaign it is a harmless repeat; on a paused one it resumes. Bound agents must be published.
  • pause stops the campaign starting anything new — no new calls, no new WhatsApp conversations, no reminders. Calls already live finish normally, and replies to recipients who write in are still answered.
  • DELETE removes the campaign and its recipients. Calls already live finish; WhatsApp conversations stop.
  • 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:
  • Voice: pending → calling → completed / no_answer / failed. A retry waits as scheduled until its time, then goes back to calling.
  • WhatsApp: pending → messaged (a conversation is running) → completed / no_response / opted_out / no_call_required / failed. For whatsapp_voice, a recipient who should get a call goes scheduled → calling, then ends like a voice recipient.
  • cancelled means the recipient was beyond max_recipients_per_campaign and was never contacted.
Adding or re-importing a recipient who is already in the campaign updates their variables but never resets their progress — a finished recipient is not contacted again.

​
Scheduling & retries

Campaigns respect a timezone (the top-level timezone, default Asia/Kolkata) and business hours (default Mon–Fri, 09:00–18:00, in that timezone): calls and the first WhatsApp message go out only inside them, except a call the recipient asked for over WhatsApp (now, or at the time they chose). Retries wait for the retry delay, then for business hours. Calls you place through the Calls API go first: while your workspace has API calls waiting, its campaigns don’t start new calls. These keys live under the campaign’s schedule:

​
Endpoints

Campaigns require the Campaign Engine. Without it configured, start returns 503; a brief outage doesn’t — the run starts as soon as the engine is back.

Campaign lifecycle

How a run executes.

WhatsApp

Template + voice-escalation flow.