Campaigns

Download .md

Campaigns, their previews, their recipients, what they cost, a round’s results and the next round. How-to: Run a campaign.

Generated from /openapi/v1.json; interactive version: API reference.

Endpoints

method	path	what it does	success
`GET`	`/v1/campaigns`	List campaigns, newest first	`200`
`POST`	`/v1/campaigns`	Create a campaign (and start it)	`201`, `202`
`GET`	`/v1/campaigns/{id}`	Read a campaign and its counts	`200`
`PATCH`	`/v1/campaigns/{id}`	Edit a draft or paused campaign	`200`
`DELETE`	`/v1/campaigns/{id}`	Delete a campaign that never sent anything	`200`
`POST`	`/v1/campaigns/{id}/previews`	Preview a draft: who gets it, who is skipped, what it costs	`201`
`GET`	`/v1/campaigns/{id}/previews/{preview_id}`	Read a preview	`200`
`POST`	`/v1/campaigns/{id}/start`	Start a draft	`200`
`POST`	`/v1/campaigns/{id}/pause`	Pause a running campaign	`200`
`POST`	`/v1/campaigns/{id}/resume`	Resume a paused campaign	`200`
`POST`	`/v1/campaigns/{id}/cancel`	Cancel a campaign	`200`
`GET`	`/v1/campaigns/{id}/recipients`	List a campaign’s recipients and what happened to each	`200`
`GET`	`/v1/campaigns/{id}/usage`	Read what a campaign cost so far	`200`
`GET`	`/v1/campaigns/{id}/recipients/{recipient_id}`	Read one recipient of a campaign	`200`
`GET`	`/v1/campaigns/{id}/results`	Read how an AI-call campaign round went, in counts	`200`
`POST`	`/v1/campaigns/{id}/clone`	Clone an AI-call campaign into its next round	`200`, `201`, `202`

Rules

The rules that span several fields. The task guide is Run a campaign; what each code means is on Errors → Campaigns.

Channel fields

A field of another channel’s campaigns is 400 field_not_for_channel, on create and on PATCH (where the campaign’s own channel decides), before any other check of the body: param names it, fields lists every such field the body has, and hint lists the campaign’s own.

channel	its own fields
SMS	`content.text`, `content.media`, `content.track_links`, `content.show_in_conversations`, `limits.spend_cap_credits`
WhatsApp	`content.template`
voice	`content.agent`, `content.mission`, `content.voicemail_drop`, `limits.max_concurrent_calls`, `retry`, `call_settings`; AI calls also `limits.spend_cap_credits` (a voicemail drop refuses it)

from must send on the campaign’s channel: a number with SMS for SMS, the WhatsApp number for WhatsApp, a number with a voice channel for voice. A WhatsApp channel’s id on a voice campaign, say, is 400 invalid_from.
A draft may leave out audience, and a voice draft may leave out agent, mission or content itself; a start needs them. An SMS draft needs content.text and a WhatsApp draft content.template.
content.show_in_conversations (SMS) is on by default up to 1,000 recipients. A read answers the value in effect: as you set it, or once the campaign has started the default it took; on a draft where you did not set it, null, which means that default.
content.template names an approved template by id (wt-… or UUID) or by name and language, read on the from number. language is required when the name exists in more than one language. A template of another number is 422 template_not_on_sender on create and on PATCH (changing the template, or from, alone). A template that is not approved is 422 template_not_approved on create, on PATCH and on start. An id sent with a name or language that is not that template’s is 400 invalid_request (param: "content.template.name" or "content.template.language"), and the message names the template’s own name and language: send the id alone, or name and language alone.
Responses show content.template as { "id": "wt-…", "name", "language" }, content.agent as ag-…, and variables in the same form as you send them.
An id of another kind (a sg-… as audience.list, an ag-… as content.template.id, a cl-… as content.agent) is 400 invalid_request: param names the field, the message the prefix it takes, and the hint the route that lists them.

Audience

Exactly one of list, segment, contacts or csv; two of them is 400 invalid_request.

contacts rows must hold E.164 numbers, as on a single send. A CSV is read more loosely: a number may be written in any common way, and one without a leading + is read as a US or Canada number. A CSV row whose number cannot be read is dropped, counted in audience.import.invalid_rows and named in audience.import.errors.
contacts and csv are imported when the campaign is created, a draft included: new contacts are made and existing ones updated even if the draft is never started, or is deleted. To try a campaign without touching your contacts, use a list or segment, or no audience yet.
A row whose number a contact already holds, on any channel, reuses that contact, is counted in matched_existing, and no second contact is made: first the contact that holds the number on the campaign’s channel, else the oldest one that holds it exclusively on another phone channel. Records split before October 2026 (one number held by two contacts on different channels) are not merged by an import: merge them in the dashboard under Contacts → Duplicates. A reused contact’s company, labels and attributes are updated from the row; its name only when it has none.
An imported audience becomes a new contact list, so the campaign reads as { "type": "list", "id": "cl-…" } (and GET /v1/lists lists it). A draft with no audience reads { "type": null, "id": null }.
Only the create answer carries audience.import:

"audience": { "type": "list", "id": "cl-0000000002",
              "import": { "source": "csv", "received": 3, "imported": 1, "matched_existing": 1,
                          "invalid_rows": 1, "duplicate_in_file": 0, "skipped_rows": 0,
                          "race_lost": 0, "errors": [ { "row": 3, "message": "…" } ], "warnings": [] } }

received is the rows sent (blank CSV lines go to skipped_rows), imported the contacts made, invalid_rows the rows dropped (each named in errors), duplicate_in_file the rows that repeated a number, and race_lost the rows whose number another import added at the same moment: they are in your contacts but not in this campaign’s list (usually 0). warnings says how a CSV was read (two columns claiming one field, a repeated header).

Variables

A variables value is one reference, "{{contact.<field>}}" or "{{contact.<field>|fallback}}", or plain text used for everyone. "Hi {{contact.first_name}}" mixes both and is 400 invalid_variable: the surrounding text belongs in the message. A field name is letters, digits, _ and -. The standard fields are first_name, last_name, full_name, email, phone and id (the contact’s own id; SMS campaigns only: on a WhatsApp or AI-call campaign {{contact.id}} is 400 invalid_variable on that variable, so keep the id in a custom field instead); any other name reads the contact’s custom field. Plain text, a field name and a fallback are each at most 200 characters; a longer one is 400 invalid_variable with part (text, field or fallback) and its length.

Names and blanks follow one model on every channel:

A name that the content has no placeholder for is 400 unknown_variable on create and PATCH, with a did-you-mean, and is not stored. A PATCH that changes the content checks the stored names too. One exception: a voice draft with no agent yet stores its names as sent, because they may fill the agent’s own placeholders and there is no agent to check them against. The PATCH that sets content.agent then refuses any stored name that fills nothing, with the same did-you-mean (suggestion), and a preview names it too.
Every bad name or value is reported at once: problems has one entry per variable (field, param, message, hint, and suggestion for a misspelled name), ordered by param; the first is the error’s own.
A placeholder nothing fills (no entry, no |fallback, no built-in) does not stop a draft from being saved. Its preview fails with one unmapped_variable entry per placeholder, and a start, or a create that starts, is 422 unmapped_variable. When the placeholder can be a contact field, hint is a variables entry that would fill it; a position (1, button.0.1) or a copy code has no hint.
A recipient whose own value is missing ({{contact.shoe_size}} for a contact without that field) and that has no |fallback is skipped, on every channel: the preview counts them under skipped_by_reason as missing_variable:<name> (the first such variable), and the recipient reads skipped. Nobody is ever sent, or called with, a blank.

How placeholders are written depends on the channel:

SMS: in content.text, {{name}} or {{name|fallback}}. {{first_name}}, {{last_name}}, {{full_name}}, {{email}} and {{phone}} fill from the contact by themselves, and the campaign then answers variables with the built-in it filled in (removed again when the text stops using it), with the text’s own |fallback when the text gives one ({{first_name|friend}} answers "{{contact.first_name|friend}}"). A recipient with no value gets the variable’s own fallback first, then the text’s. A missing value skips the recipient as missing_variable:<placeholder>.
WhatsApp: fill every key in the template’s variable_keys (GET /v1/templates): body variables by name or number, header.<name>, button.<i>.<name> and button.<i>.copy_code, where i is the button’s index. Nothing fills by itself. A copy code is at most 15 characters (its text, or its |fallback); a contact’s own longer code fails the preview. A quick-reply payload cannot be set in a campaign: the button is sent as approved. Fill a template maps each part to its key. A missing value skips the recipient as missing_variable:<key> (missing_variable:header.order). When variable_keys is [], the template takes no values: omit variables or send {}.
Voice: in content.mission, {{name}} or {{name|fallback}}, each mapped in variables: nothing in a mission fills by itself, not even {{first_name}}. The agent’s greeting fills {{first_name}}, {{last_name}}, {{email}} and {{phone}} from the contact. variables may also fill placeholders in the agent’s own instructions. Only a variable the mission uses skips a call when the contact’s value is missing (missing_variable:<name>); one the greeting or the agent’s instructions use is left blank there, and the greeting’s own {{first_name}} never skips anyone. Only the double-brace form is a placeholder: {name} is read out as written.

Schedule

start_at and end_at read a local time without offset in tz, across daylight saving. A start that has already passed, or a local time the clocks skip, is 400 invalid_schedule. Both are read back as instants with the offset tz has then (2026-10-20T09:00 reads "2026-10-20T09:00:00-07:00"), with the fraction of a second as you wrote it, up to the microsecond: more than six fractional digits is 400 invalid_schedule. end_at must be at least a millisecond after start_at.
At end_at, a pending retry is dropped (the recipient keeps its last call’s result) and the campaign completes with completed_reason: "schedule_ended" only when someone was left out. A paused campaign stays paused until you resume it, then completes the same way; a PATCH of a paused campaign’s end_at applies when it resumes. A start after end_at has passed is 400 invalid_schedule on schedule.end_at. Applies to every channel.
hours are up to 8 windows in tz. end may be 24:00, the end of the day. A start later than its end is an overnight window (22:00–06:00), and days is checked against the day it is at each moment, so the hours after midnight need the next day in days too. Windows are wall-clock time on a daylight-saving day. Outside them the campaign waits (it is not paused).

Limits and retries

limits.spend_cap_credits (SMS and AI calls; whole credits, 1 to 10,000,000) pauses the campaign with paused_reason spend_cap when reached. limits.max_concurrent_calls (voice): 0 is no limit.
An AI-call campaign’s cap is checked before every call: the call starts only when the credits billed so far, plus the calls under way, plus one more call fit (each call under way and the next one at a median call’s price for the campaign’s agent). Calls under way always finish, and calls that start at the same moment see the same spend, so a campaign can end above its cap by about max_concurrent_calls calls: for a small cap, set a low limits.max_concurrent_calls too. Its untouched recipients stay queued; GET /v1/campaigns/{id}/usage shows spend_cap.
Raising the cap is a person’s act: on an AI-call campaign that has started, an API key can set a cap where there is none, or lower one, but raising or removing it is 403 spend_cap_raise_needs_person (cap, dashboard_url). A person raises it on the campaign’s page (Usage & cost, Spending limit), then resumes. A draft takes any value. A resume whose next call would not fit is 409 spend_cap_reached (cap, used, in_flight, next_call, remaining, dashboard_url), and nothing changes.
retry (voice): a field you leave out is stored with its default and read back. A busy line counts as no_answer, so no_answer retries both; busy itself is 400 invalid_request. on is stored and answered as written.
A campaign answers limits and retry as written, each null when not set or not this channel’s.

Previews

The other channel differences, side by side: How the channels differ.

	SMS	WhatsApp and voice
answers	`201` at once, usually `status: "building"`; poll until `ready`	`201` with the result at once
`id`	`snap_…` once a snapshot is built; `rev_…` for one that failed its checks first	`rev_…`
the audience	frozen (`freezes_audience: true`): the start sends to exactly the people counted	read again at the start
needed to start	yes (`409 preview_required` without one)	no: a start without one is checked as a preview would be
after any edit, or a change to what it checked	stale: reading it shows `preview_stale` and keeps its counts	stale: reading it shows `preview_stale` with `null` counts
lifetime	30 minutes, and a newer preview expires it (`preview_expired`)	until the next edit
`samples`	up to 3, the first people in the send order, while `ready`	WhatsApp: a few; voice: up to 3, from the people the calls reach
`cost_credits`	the snapshot’s cost	WhatsApp: 0.1 per recipient; voice: the high end of an estimate
`cost_estimate`	`null`	WhatsApp: `null`; voice: `{ low, high, per_call, talk_minutes, includes_retry, per_call_components }`

A preview takes no fields: send no body, or {}. Any field is 400 unknown_field, refused before anything is built.
Treat a preview id as opaque. Starting with a preview_id of another campaign is 404 not_found.
recipients is who will get it; skipped and skipped_by_reason who will not, and why (an opted-out number is always skipped). They are null only while an SMS preview is building, on a stale WhatsApp or voice preview, and on one that failed its content checks (the audience is counted once the content passes).
A preview runs every check the start makes, and a preview a start would refuse is status: "failed", with the start’s own code: the schedule’s end (invalid_schedule), Call plans turned off (call_plan_disabled), the account (workspace_suspended, outbound_compliance_required, billing_not_eligible, insufficient_credits with short_credits, daily_voice_minutes_exceeded), the sender (sender_not_cleared with sender_status, sender_missing, sender_provider_unsupported, sms_no_billing_mode, invalid_from, calls_not_routed, trial_sender_not_allowed), the content (launch_fields_missing with missing, agent_required, agent_disabled, template_not_approved, unmapped_variable, unknown_variable, invalid_variable) and the audience (no_recipients, too_many_recipients). The first is error and the rest are in error.also, in this order: the campaign’s state, the account, the sender, the content, the audience; within one, by param. Every problem, in error and in error.also, has a hint: what to set, or which route to call (a copy code that is too long names the 15-character limit and the variable to shorten).
A preview id records what the preview checked: the campaign as it was, and its sender, template, agent, compliance acknowledgment and list or segment. Reading or starting it checks them again; any change makes it preview_stale, and a start or resume from it is 409 preview_stale. After fixing a problem, preview again. A preview id made before previews recorded this is stale. Who is in a WhatsApp or voice list is not recorded: those audiences are read again at the start.
A person whose number is the campaign’s own sending number is skipped as same_as_sender, on every channel.
A campaign reaches a person through the phone number stored on any of their phone channels: the one for the campaign’s channel, else one stored for SMS, calls or WhatsApp. Someone with no phone number at all (an email-only contact) is skipped as no_phone_number. One number is sent or called once, even when two contacts hold it (the other is duplicate), and an opt-out is checked on the number for the campaign’s channel.
balance_credits is null when the balance covers cost_credits, or minus the shortfall.
Every sample is { "contact_id", "contact_short_id", "name", "to", "text" }: contact_id is the contact’s UUID, contact_short_id its ct-… id. SMS adds segments (null for MMS; with link tracking on, a link is counted as its short tracked link). WhatsApp adds header, uses the WhatsApp number as to, and adds buttons: each button with a variable, filled in for that person, as { "index", "type": "url", "url" } or { "index", "type": "copy_code", "code" }. index is the button’s position among all the template’s buttons, from 0: the index variables.button.<index>.… names. [] when the template has none. Voice: text is the mission as the agent will read it, plus greeting, the opening line (null when the agent opens in its own words). A new SMS preview can sample other people: the send order is drawn when it is built. After the start, samples is null.
WhatsApp and voice: the audience is counted as the start reaches it, up to the 10,000-recipient ceiling: no_phone_number, opted_out (on the campaign’s channel), same_as_sender and duplicate come off recipients. Each person is reached on the number for the campaign’s channel, else on the number stored for SMS, calls or WhatsApp.
WhatsApp: cost_credits is 0.1 credits per recipient. A number that is not on WhatsApp is a failed send, not a skip.
Voice: cost_credits is an estimate, the high end (p90) of what the calls are likely to cost. cost_estimate shows the range behind it: low (every call a median one), high (= cost_credits: every call a long one, plus one retry per recipient, so includes_retry is true), per_call (low/high for one answered call), talk_minutes (low/high talk time across the campaign; billed minutes are whole minutes per call and already priced) and per_call_components (one median call split into telephony, stt, tts, realtime, livekit, storage, llm). An agent on the “OpenAI Realtime + your voice” pipeline prices realtime and tts and no stt. It is null on SMS and WhatsApp, and on a failed preview.
no_recipients on an audience with nobody in it says “This audience has no contacts.”; otherwise skipped_by_reason accounts for every person.
A preview that fails lists every problem it finds before anyone is counted (the agent, the placeholders, the variables, the audience): the first is error, the rest are in error.also, each { "code", "message", … }. Each unfilled placeholder is its own entry with its own field:

"error": { "code": "unmapped_variable", "field": "aa", "param": "variables", "message": "…",
           "also": [ { "code": "unmapped_variable", "field": "bb", "param": "variables", "message": "…" },
                     { "code": "no_recipients", "param": "audience", "message": "…" } ] }

Starting

A WhatsApp or voice start whose audience reaches nobody is 422 no_recipients (with skipped_by_reason), and the campaign stays a draft. A create with start: "auto" whose audience reaches nobody is the same 422 no_recipients, and the campaign is kept as a draft, named in campaign_id, on every channel. A retry with the same Idempotency-Key answers the same refusal for the same draft.
A start is checked like a preview: a WhatsApp or voice draft without a preview_id that has an unfilled placeholder is 422 unmapped_variable (field, fields), and a stored name that fills nothing is 422 unknown_variable.
A campaign that is no longer a draft is answered by its state before any preview check: 409 campaign_completed, 409 campaign_canceled or 409 campaign_already_started.
Two starts at once without a key get one 200 and one 409 campaign_already_started; with the same key the second waits (409 start_in_progress) and then replays the first.
started_at is set once the first recipient is attempted.
A create that starts answers preparing (SMS) when a large audience takes longer to check than the request waits (about 10 seconds); the server starts the campaign by itself once the check passes.
DELETE decides whether anything was sent inside the delete itself, so a start or a send that lands first is never deleted.

Editing (PATCH)

PATCH /v1/campaigns/{id} takes the create fields except channel and start, makes the same checks a create makes, and answers the campaign as it now is.

field	a PATCH	`null`
`content`	merges: only the fields you send change	not taken, except SMS `content.media`: `null` removes the picture
`variables`	merges by name, in one database write (two PATCHes of different names at once both land)	a name set to `null` is removed; on SMS, a name that fills by itself (`first_name`, `last_name`, `full_name`, `email`, `phone`) gets its built-in fill back
`limits`	merges, one field at a time	a field set to `null` removes that limit
`retry`	merges into the stored policy; a campaign with no policy yet needs `max_attempts`	`"retry": null` removes the policy
`metadata`	replaces the stored object	`null` or `{}` removes it
`schedule`	replaces the whole schedule	`"schedule": null` removes it
`name`, `from`	replace the stored value	not taken
`audience`	replaces, on a draft only: a `list` or `segment`	not taken
`channel`, `start`	`400 unknown_field`
`audience.contacts`, `audience.csv`, `content.voicemail_drop`, an SMS campaign’s `from` (another number than its own; its own number, as E.164, `pn-…` or `ch-…`, is no change), a started campaign’s audience, a voicemail-drop campaign’s `retry`	`400 field_not_editable`

A field that is “not taken” refuses null with 400 invalid_request. To change an inline audience, put the people in a list and set audience.list.

A field set to what the campaign already has is no change: the same list again, null where nothing is stored, the same name, schedule, metadata or variables. A PATCH that changes nothing answers the campaign as it is and does not touch it, so a preview made before it is not stale and still starts the campaign. A PATCH that changes something makes every earlier preview stale.

After the merge, every name in variables must fill a placeholder in the content as it will be. When a PATCH changes the template (or the text, the mission or the agent), remove the stored names it no longer uses in the same request:

{ "content": { "template": { "id": "wt-0000000002" } },
  "variables": { "code": "{{contact.coupon}}", "first_name": null, "header.name": null } }

A paused WhatsApp or voice campaign whose content was edited is checked again on resume. An SMS resume may take a new preview’s preview_id; if what it sends, or to whom, changed since it was paused, a resume without one is 409 preview_stale.

Reading a campaign

status: draft, preparing, queued, running, paused, completed, failed or canceled; the last three are final.
counts (null for a draft) is one block on every channel. opted_out counts recipients whose number is opted out now: one who texted STOP and later START is no longer counted. replied and opted_out are null where a channel does not count them (WhatsApp has no opted_out; voice has neither). For voice, sent counts the calls that went through. WhatsApp counts are cumulative: a delivered message counts as sent too, and a read one as sent and delivered.
An SMS campaign created with start: auto that could not start after it was created stays a draft and carries refusal: { "status", "error" }, what a start would have answered.
Each read of one campaign adds its channel’s block, a draft included: sms (engagement with clicks on tracked links, skipped_by_reason, cost, errors, rate), whatsapp (read, null until the campaign has started) or voice (kind).
completed_at is set when the last recipient finished, or when the campaign stopped if nobody was reached. completed_reason is "schedule_ended" when it stopped at schedule.end_at with people left (they read skipped; SMS lists them in skipped_by_reason).
GET /v1/campaigns/{id}/usage is what the campaign cost so far: billed_credits, by_category (phone, recording, speech, ai, messaging, whatsapp, other, each with its English label), calls or messages, and spend_cap on an AI-call campaign with a cap. It grows for a few minutes after a call ends. One call’s cost is billed_credits on GET /v1/calls/{id}. own_speech_key: true means part of the speech was billed by the workspace’s own provider, not here.
GET /v1/campaigns items leave out what needs a per-campaign read (counts, started_at, completed_at are null; no channel block). A preparing campaign reads preparing in the list too, and is listed under ?status=preparing, not ?status=draft.

Recipients

status uses one vocabulary on every channel: a text or WhatsApp recipient’s is the word its message would have on GET /v1/messages/{id}, a voice recipient’s the word its call would have on GET /v1/calls/{id}, plus skipped for someone the campaign never reached out to.

channel	`status` (and what `?status=` takes)
SMS	`queued`, `sending`, `sent`, `delivered`, `undelivered`, `failed`, `unconfirmed`, `skipped`; the filter also takes `replied`
WhatsApp	`queued`, `sending`, `sent`, `delivered`, `read`, `failed`, `unconfirmed`, `skipped`; the filter also takes `replied`
voice	`queued`, `in_progress`, `completed`, `voicemail`, `no_answer`, `busy`, `failed`, `skipped`

The SMS filter still takes its older words (not_yet_sent, sent_awaiting, not_delivered) for now; rows always answer the words above.

message_id (SMS, WhatsApp) is the latest attempt’s message, null until it is sent, for WhatsApp messages sent before 2026-10-16, and when the message could not be recorded. An SMS row’s message_id can briefly answer 404 right after a send the engine refused and rolled back.
error.code is Meta’s code for WhatsApp (null with Meta’s words in message when there is none), and the call’s disconnect code for voice.
A voice row’s voicemail comes from how its call was classified (outcome), so a call that GET /v1/calls/{id} reads as completed can be a voicemail row.
Voice rows add call_short_id, the call’s cv-… id. Every row’s cursor starts the next page after that row. A ?status= word the channel does not have is 400 invalid_request listing its values.
An SMS walk is a snapshot as of its first page, so nobody is skipped, but a row can come back on a later page while a campaign is sending: de-duplicate by id, and start again without after for newer state.

Call settings

A voice campaign’s call_settings, and a single call’s (POST /v1/calls). Every field is optional; one left out takes its default. A read answers every field with the value the next call uses.

field	what it does	default
`phone_menu`	`auto`: the agent listens first, talks when a person answers and presses keys when a phone menu (IVR) answers. `always`: it expects a menu first and waits for it. `never`: it talks to whoever answers from the first word and never presses keys	`auto`
`record_calls`	keep an audio recording of each call	`true`
`max_hold_seconds`	seconds on hold before the agent ends the call, 60 to 2,700	`900`
`voicemail.action`	`hang_up`, or `play_recording`: play `voicemail.recording` into the mailbox (the agent never speaks into one)	`hang_up`
`voicemail.recording`	a voicemail recording’s `vm-…` id or UUID; required with `play_recording`	none
`voicemail.detect_by_agent`	the agent also listens for a voicemail greeting, on top of the automatic check that always runs (it adds instructions to each call)	on with `play_recording`, off with `hang_up`
`use_knowledge_base`	the agent may search its knowledge-base documents on the call	`true`

PATCH merges call_settings field by field, and voicemail inside it. null on max_hold_seconds, voicemail.recording or voicemail.detect_by_agent restores the default.
A campaign that has started (anything but a draft) keeps its max_hold_seconds: 400 field_not_editable. The other fields of a paused campaign reach the calls placed after it resumes.
An unknown recording is 404 voicemail_recording_not_found; play_recording with no recording is 400 invalid_request on call_settings.voicemail.recording.
A voice campaign created through the API before 28 October 2026 reads "phone_menu": "always" until you change it.

Rounds: results and clone

GET /v1/campaigns/{id}/results and POST /v1/campaigns/{id}/clone take AI-call campaigns only (422 channel_not_supported otherwise). The task guide is Improve an agent between rounds.

A round’s people are checked across its whole family: the first campaign and every clone made from it or from a later round.
audience: "unreached" takes a recipient whose status is no_answer, busy, voicemail or failed, or who was stopped before being called (a canceled campaign), never one refused before dialling (skipped), when no round reached that person or was told to stop by them, and the person is still a contact with a phone number that is not opted out. It is results.unreached, counted the same way.
audience: "same" takes everyone the campaign had, reached or not, except anyone who asked a round to stop (a do-not-call said on a call is kept on that call only, so a list re-read at start would not leave them out). A draft that never had recipients keeps its list or segment.
A campaign that is queued, running or paused is not cloned (409 campaign_not_finished); a draft may be copied as same. One unfinished round per family: a clone while another round of it is a draft, queued, running or paused is 409 round_in_progress.
A per-person number picked in the dashboard composer is not copied: the round calls each person’s main number.
A clone copies the campaign’s own settings, not the agent’s prompt: the prompt is read when the clone starts, and its calls carry that prompt_version.
by_outcome uses the call outcome words of GET /v1/calls/{id}, plus none for a recipient with no outcome yet; both by_status and by_outcome sum to recipients.

`GET /v1/campaigns`

List campaigns, newest first.

Parameters

name	in	type	description
`limit`	query	integer 1–200	Page size, 1 to 200 (default 50).
`after`	query	string	The previous page’s `next_cursor`.
`channel`	query	string `sms`, `whatsapp`, `voice`
`status`	query	string `draft`, `preparing`, `queued`, `running`, `paused`, `completed`, `failed`, `canceled`	Only campaigns with this `status` (`cancelled` is read as `canceled`). `preparing`: a one-request SMS create whose preview is still being built; it is not matched by `draft`.

Answers 200 with CampaignList. Errors use the error envelope; common codes: campaigns, lists, every request.

`POST /v1/campaigns`

Create a campaign (and start it).

One body for SMS, WhatsApp and voice. start is required (400 start_required without it). With start: "auto" the campaign is checked and started in this request: 202, status preparing, queued or running. A refusal after the campaign was created carries campaign_id; the campaign is kept as a draft. With start: "draft": 201, then preview and start it.

Parameters

name	in	type	description
`idempotency-key`	header	string ≤ 255 chars	Send one with every create. A retry with the same key never creates (or starts) a second campaign: it answers the first one as it is now. Rules: Idempotency.

Request body: CampaignCreate.

Answers 201 with Campaign; 202 with Campaign. Errors use the error envelope; common codes: campaigns, lists, every request.

`GET /v1/campaigns/{id}`

Read a campaign and its counts.

Parameters

name	in	type	description
`id`	path	string, required	The campaign’s `ca-…` id or UUID.

Answers 200 with Campaign. Errors use the error envelope; common codes: campaigns, lists, every request.

`PATCH /v1/campaigns/{id}`

Edit a draft or paused campaign.

Parameters

name	in	type	description
`id`	path	string, required	The campaign’s `ca-…` id or UUID.

Request body: CampaignUpdate.

Answers 200 with Campaign. Errors use the error envelope; common codes: campaigns, lists, every request.

`DELETE /v1/campaigns/{id}`

Delete a campaign that never sent anything.

A draft, or a campaign canceled before it sent anything: decided in the delete itself. A campaign that sent to anyone keeps its history: a queued, running or paused one is canceled instead, and a finished one stays. A refusal is 409 campaign_not_deletable with the campaign’s status.

Parameters

name	in	type	description
`id`	path	string, required	The campaign’s `ca-…` id or UUID.

Answers 200 with the object below. Errors use the error envelope; common codes: campaigns, lists, every request.

field	type	description
`id`	string, required
`object`	string, required always `campaign`
`deleted`	boolean, required always `true`

field	type	description
`id`	string, required
`short_id`	string or null, required
`object`	string, required always `campaign`
`name`	string or null, required
`channel`	string, required `sms`, `whatsapp`, `voice`
`status`	string, required `draft`, `preparing`, `queued`, `running`, `paused`, `completed`, `failed`, `canceled`	`draft`, `preparing`, `queued`, `running`, `paused`, `completed`, `failed` or `canceled`. New values may be added: treat one you don’t know as still in progress.
`paused_reason`	string or null, required	Why a `paused` campaign is paused: `operator`, `spend_cap`, `out_of_credits`, `daily_cap`, `circuit_breaker`, `campaign_blocking_error`, `trial_check_unavailable`, `trial_campaign_needs_card`, `needs_review`, `engine_error`. `null` on a paused campaign means a person paused it. New values may be added: show `message` from the `campaign.paused` event, or treat an unknown one as “paused”.
`from`	string or null, required
`content`	SmsCampaignContent or WhatsappCampaignContent or VoiceCampaignContent or null, required	This campaign’s channel’s content, as written: SMS `{ text, media, track_links, show_in_conversations }`, WhatsApp `{ template: { id, name, language } }`, voice `{ agent, mission }`. `channel` says which.
`variables`	map of string to string, required	As written; `{}` when there are none.
`schedule`	CampaignScheduleRead or null, required
`limits`	object, required	As written with `limits`; each field is `null` when not set. `spend_cap_credits` is SMS and AI-call campaigns (not voicemail drops), `max_concurrent_calls` voice only.
`limits.spend_cap_credits`	number or null, required
`limits.max_concurrent_calls`	integer or null, required
`retry`	object or null, required	AI-call campaigns: the retry policy as written; `null` when none.
`retry.max_attempts`	integer, required
`retry.interval_min`	integer or null, required
`retry.on`	array of string or null, required
`call_settings`	CallSettingsRead or null, required
`counts`	object or null, required	`null` for a draft, and on every item of `GET /v1/campaigns` (read one campaign for its counts).
`counts.recipients`	integer, required
`counts.pending`	integer, required
`counts.sent`	integer, required	Messages sent, or calls that went through. Cumulative: WhatsApp counts a delivered or read message as sent too.
`counts.delivered`	integer, required	Cumulative: WhatsApp counts a read message as delivered too.
`counts.failed`	integer, required
`counts.skipped`	integer, required
`counts.replied`	integer or null, required
`counts.opted_out`	integer or null, required
`audience`	object, required	Who the campaign sends to.
`audience.type`	string or null, required `list`, `segment`	`list` or `segment`; `null` when the campaign has no audience yet (a draft). An inline `contacts` or `csv` audience is imported into a contact list when the campaign is created, so it reads as `list`. That list (`source: "campaign"`) is removed when the campaign is deleted, unless another campaign uses it; the contacts stay.
`audience.id`	string or null, required	The list’s `cl-…` or the segment’s `sg-…` id (`GET /v1/lists`, `GET /v1/segments`).
`audience.import`	object	The create answer only, when it imported `contacts` or `csv`: what the import did. Not on later reads.
`audience.import.source`	string or null, required `contacts`, `csv`	Which inline audience was imported: `audience.contacts` or `audience.csv`.
`audience.import.received`	integer, required	Rows received (blank CSV lines excluded).
`audience.import.imported`	integer, required	New contacts made.
`audience.import.matched_existing`	integer, required	Rows whose number a contact already had: that contact was used.
`audience.import.invalid_rows`	integer, required	Rows dropped because their phone number could not be read.
`audience.import.duplicate_in_file`	integer, required	Rows that repeated a number earlier in the same audience.
`audience.import.skipped_rows`	integer, required	Blank CSV lines skipped.
`audience.import.race_lost`	integer, required	Rows whose number another import added to your contacts at the same moment: this import did not add them to the campaign’s list. Usually 0; when it is not, add those people with `PATCH` and a list.
`audience.import.errors`	array of objects, required	Each dropped or partly read row: its line and why.
`audience.import.errors[].row`	integer, required
`audience.import.errors[].message`	string, required
`audience.import.warnings`	array of string, required	How the file was read: two columns claiming one field, a repeated header, ….
`insight`	string or null, required	AI-call campaigns: the insight (`di-…`) its calls run; `null` when it names none (its calls then run the agent’s, if any), and on every other campaign.
`metadata`	map of string to any or null, required
`created_at`	string or null, required
`started_at`	string or null, required	When the first recipient was attempted; `null` until then, and on list items.
`completed_at`	string or null, required	Once `completed`, `failed` or `canceled`: when the last recipient finished (or the campaign stopped, when nobody was reached). `null` before, and on list items.
`completed_reason`	string or null, required always `schedule_ended`	`schedule_ended` when a `completed` campaign stopped at `schedule.end_at`: recipients it had not sent or called by then read `skipped`. `null` otherwise. New values may be added.
`cloned_from`	CampaignLineage or null, required
`sms`	object	SMS, on every read of one campaign: engagement, `skipped_by_reason`, cost, errors, rate; each `null` until the campaign has started. Not on list items.
`sms.engagement`	map of string to any or null, required
`sms.skipped_by_reason`	map of string to number or null, required
`sms.cost`	map of string to any or null, required
`sms.errors`	array of map of string to any or null, required
`sms.rate`	map of string to any or null, required
`whatsapp`	object	WhatsApp: how many messages were read; `null` until the campaign has started. Not on list items.
`whatsapp.read`	integer or null, required
`voice`	object	Voice: `kind`. Not on list items.
`voice.kind`	string, required `ai_agent`, `voicemail_drop`
`refusal`	object	SMS, `start: auto` only: present when the automatic start was refused after the campaign was created (the campaign stays a draft). The same error a start would have answered; fix the cause, then preview and start the draft.
`refusal.status`	integer, required	The HTTP status a start would have answered.
`refusal.error`	map of string to any, required	The error object a start would have answered: `type`, `code`, `message`, `param`, ….

field	type	description
`text`	string or null, required
`media`	string or null, required
`track_links`	boolean, required
`show_in_conversations`	boolean or null, required	As set; once the campaign has started and it was not set, the default the campaign applied (on up to 1,000 recipients). `null` on a draft that has not set it: the default.

field	type	description
`template`	object, required
`template.id`	string or null, required	The template’s `wt-…` id.
`template.name`	string or null, required	The template’s name.
`template.language`	string or null, required	The template’s language code, as Meta has it (`en_US`).

field	type	description
`agent`	string or null, required	The agent’s `ag-…` id.
`mission`	string or null, required

field	type	description
`start_at`	string or null, required
`end_at`	string or null, required
`tz`	string or null, required
`days`	array of integer or null, required
`hours`	array of objects or null, required
`hours[].start`	string, required
`hours[].end`	string, required

field	type	description
`name`	string, required 1–200 chars
`from`	string, required 1–64 chars	Same as MessageCreate.from.
`start`	string, required `auto`, `draft`	Required, no default (`400 start_required` without it; nothing is created). `auto`: create and start in one request, after the same checks a start makes. `draft`: save it to preview and start later.
`audience`	CampaignAudience
`variables`	map of string to string values ≤ 420 chars	Fill placeholders per recipient. Each value is one reference, `"{{contact.<field>}}"` or `"{{contact.<field>\|fallback}}"`, or plain text used for everyone. Standard fields: `first_name`, `last_name`, `full_name`, `email`, `phone`, and `id` (the contact’s id); any other name reads the contact’s custom field. Plain text, a field name and a fallback are each at most 200 characters (`400 invalid_variable`, with `part` naming which); a whole value at most 420. Every bad value is reported at once, in `problems`.
`schedule`	CampaignSchedule
`limits`	object
`limits.spend_cap_credits`	integer > 0	SMS: stop at this many credits (a whole number above 0).
`limits.max_concurrent_calls`	integer 0–1,000	Voice: live calls at once (0 = no limit).
`metadata`	map of string to string ≤ 20 keys; keys 1–40 chars; values ≤ 500 chars	Same as MessageCreate.metadata.

field	type	description
`channel`	string, required always `sms`
`content`	object, required
`content.text`	string, required 1–1,600 chars	The text. Placeholders: `{{first_name}}`, `{{last_name}}`, `{{full_name}}`, `{{email}}`, `{{phone}}` fill by themselves; `{{name\|fallback}}` uses the fallback when there is no value; any other `{{name}}` comes from `variables`.
`content.media`	string ≤ 512 chars	A picture or video: the `media` that `POST /v1/media` answers.
`content.track_links`	boolean	Replace each link with a tracked short link and count clicks.
`content.show_in_conversations`	boolean	Add each text to the recipient’s conversation (default on up to 1,000 recipients).

field	type	description
`channel`	string, required always `whatsapp`
`content`	object, required
`content.template`	object, required
`content.template.id`	string 1–64 chars	Same as WhatsappMessageCreate.template.id.
`content.template.name`	string 1–512 chars	The template’s name, as approved by Meta, on the `from` number.
`content.template.language`	string 2–15 chars	With `name`: the language code, e.g. `en_US`.

field	type	description
`channel`	string, required always `voice`
`content`	object	`agent` and `mission`. A draft may leave out either, or `content` itself; a start needs both.
`content.agent`	string 1–64 chars	`ag-…` id or UUID. Required to start.
`content.mission`	string 1–4,000 chars	What the agent should get done on each call. Required to start.
`content.voicemail_drop`	object	Not available yet: a voicemail-drop campaign is `400 voicemail_drop_unavailable` (nothing is created). Use `agent` and `mission`.
`content.voicemail_drop.audio_url`	string (uri), required ≤ 2,048 chars
`retry`	object	Voice only: how unanswered calls are retried. A field left out takes its default (`interval_min` 60, `on` `no_answer`, `voicemail`, `closed`), stored and read back.
`retry.max_attempts`	integer, required 1–10	Calls per person at most, the first included (1 to 10).
`retry.interval_min`	integer ≥ 1	Minutes to wait before calling again. Default 60.
`retry.on`	array of string ≤ 8 items; each `no_answer`, `voicemail`, `failed`, `callback_requested`, `hold_timeout`, `menu_dead_end`, `menu_loop`, `closed`	The call results to try again, stored and returned as written. Default `no_answer`, `voicemail`, `closed`. A busy line counts as `no_answer`.
`call_settings`	CallSettings
`insight`	string or null 1–64 chars	The insight (`di-…` id or UUID, from `GET /v1/insights`) this campaign’s calls run: each answer appears in the call’s `extracted`, shortly after it ends. `null` or left out: the calls run the agent’s insight, if it has one. AI calls only. Each analysed call spends credits for one model run. On a PATCH, a change of `insight` alone is taken while the campaign is queued, running or paused too; it applies to calls that end after it. Like any edit, it makes earlier previews stale.

field	type	description
`phone_menu`	string `auto`, `always`, `never`	Same as CallSettings.phone_menu.
`record_calls`	boolean	Keep an audio recording of each call. Default `true`.
`max_hold_seconds`	integer or null 60–2,700	Same as CallSettings.max_hold_seconds.
`voicemail`	object	Merged field by field. `recording: null` removes the recording; `detect_by_agent: null` restores the default.
`voicemail.action`	string `hang_up`, `play_recording`	Same as CallSettings.voicemail.action.
`voicemail.recording`	string or null 1–64 chars	Same as CallSettings.voicemail.recording.
`voicemail.detect_by_agent`	boolean or null	Same as CallSettings.voicemail.detect_by_agent.
`use_knowledge_base`	boolean	Same as CallSettings.use_knowledge_base.

field	type	description
`phone_menu`	string, required `auto`, `always`, `never`
`record_calls`	boolean, required
`max_hold_seconds`	integer, required
`voicemail`	object, required
`voicemail.action`	string, required `hang_up`, `play_recording`
`voicemail.recording`	string or null, required
`voicemail.detect_by_agent`	boolean, required
`use_knowledge_base`	boolean, required

field	type	description
`contacts`	array of objects, required ≤ 10,000 items	1 to 10,000 rows. An empty list is `400 empty_audience_input`.
`contacts[].phone`	string, required pattern `^\+[1-9]\d{6,14}$`	E.164 (`+14155550100`); anything else is `400 invalid_number`, with the E.164 form as a hint when there is one. An import never makes a second contact for a number: it reuses the contact that has the number on the campaign’s channel, else the one that holds it on another channel (`audience.import.matched_existing`). Records split before October 2026 show under Contacts → Duplicates. A campaign reaches a contact through the phone number stored on any of its phone channels; one with no phone number is skipped as `no_phone_number`, and one whose number is the campaign’s own sending number as `same_as_sender`.
`contacts[].name`	string ≤ 200 chars	Sets the name of a NEW contact. A reused contact takes it only when it has no name (blank, or just its phone number); a contact that has a name keeps it. Company, labels and attributes of a reused contact are updated from the row.
`contacts[].email`	string ≤ 320 chars
`contacts[].company`	string ≤ 200 chars
`contacts[].attributes`	map of string to string or number or boolean	Custom fields, readable as `{{contact.<key>}}` in `variables`.

field	type	description
`tz`	string, required 1–64 chars	IANA time zone, e.g. `America/Los_Angeles`. An abbreviation (`PST`) or an offset is `400 invalid_schedule`.
`start_at`	string 1–40 chars	When to start: a local time without offset (`2026-10-20T09:00`) read in `tz`, a date (`2026-10-20`, local midnight), or an instant with offset (`2026-10-20T09:00:00-07:00`). Stored and read back as an instant with the offset `tz` has then.
`end_at`	string 1–40 chars	When to stop starting new sends and calls: a date (`2026-10-24`, the END of that day in `tz`), a local time without offset (`2026-10-24T18:00`) read in `tz`, or an instant with offset. Must be at least 1 ms later than `start_at`, and later than now (`400 invalid_schedule`, `param: "schedule.end_at"`). At `end_at` the campaign stops: recipients not yet sent or called read `skipped`, a call or text already under way finishes, and the campaign completes with `completed_reason: "schedule_ended"`.
`days`	array of integer ≤ 7 items; each 0–6	Days it may send or call, 0 = Sunday.
`hours`	array of objects ≤ 8 items	Sending hours in `tz`, e.g. `[{ "start": "09:00", "end": "18:00" }]`. `start` is 00:00–23:59, `end` 00:00–24:00 (24:00 = the end of the day); a window may not start and end at the same time. `start` after `end` is an overnight window (`22:00`–`06:00` sends from 22:00 until 06:00 the next morning, `days` is checked against the day it is at each moment, so the hours after midnight need the next day in `days` too). Hours are wall-clock time in `tz` across daylight saving.
`hours[].start`	string, required pattern `^(?:[01]\d\|2[0-3]):[0-5]\d$`
`hours[].end`	string, required pattern `^(?:(?:[01]\d\|2[0-3]):[0-5]\d\|24:00)$`

field	type	description
`name`	string 1–200 chars
`from`	string 1–64 chars	The new sender, named as on create (E.164, `pn-…` or `ch-…`). An SMS campaign takes one while it is a draft (a paused one keeps its sender: `400 field_not_editable`); a number not cleared to send yet is accepted, and the next preview lists `sender_not_cleared`. A new sender makes every earlier preview of the campaign stale: preview again before you start.
`audience`	CampaignAudience	A draft’s `list` or `segment` (replacing the one it has). `contacts` and `csv` are imported at create only, and a paused campaign keeps its audience: both are `400 field_not_editable`.
`variables`	map of string to string or null values ≤ 420 chars	Merged into the stored `variables`: a name with a value sets it, a name set to `null` is removed, and every name you leave out keeps its value. Values are written as on create. On SMS, `null` on a name that fills by itself (`first_name`, `last_name`, `full_name`, `email`, `phone`) restores that built-in fill, when `content.text` uses it. After the merge, every name must have a placeholder in the content as it will be (`400 unknown_variable`, with every such name in `fields`). A PATCH that changes nothing (every field as stored) changes nothing: the campaign is answered as it is, and an earlier preview stays valid.
`schedule`	CampaignSchedule or null	Replaces the stored schedule whole; `null` removes it (send as soon as started).
`limits`	object	A field set to `null` removes that limit; a field left out keeps it.
`limits.spend_cap_credits`	integer or null > 0	SMS and AI-call campaigns: stop at this many credits (a whole number above 0; at most 10,000,000 on an AI-call campaign). An AI-call campaign pauses with `paused_reason: "spend_cap"` before a call that would not fit (billed so far, plus the calls under way, plus one more call at its estimated price). On an AI-call campaign that has started, an API key can lower it but not raise or remove it (`403 spend_cap_raise_needs_person`): a person raises it in the dashboard.
`limits.max_concurrent_calls`	integer or null 0–1,000	Voice: live calls at once (0 = no limit).
`retry`	object or null	Merged into the stored retry policy: a field you send replaces that field, the others keep their values. `null` removes the policy (no retries). A campaign without a policy needs `max_attempts`.
`retry.max_attempts`	integer 1–10	Calls per person at most, the first included (1 to 10).
`retry.interval_min`	integer ≥ 1	Minutes to wait before calling again. Default 60.
`retry.on`	array of string ≤ 8 items; each `no_answer`, `voicemail`, `failed`, `callback_requested`, `hold_timeout`, `menu_dead_end`, `menu_loop`, `closed`	The call results to try again, stored and returned as written. Default `no_answer`, `voicemail`, `closed`. A busy line counts as `no_answer`.
`call_settings`	CallSettingsPatch
`insight`	string or null 1–64 chars	The insight (`di-…` id or UUID, from `GET /v1/insights`) this campaign’s calls run: each answer appears in the call’s `extracted`, shortly after it ends. `null` or left out: the calls run the agent’s insight, if it has one. AI calls only. Each analysed call spends credits for one model run. On a PATCH, a change of `insight` alone is taken while the campaign is queued, running or paused too; it applies to calls that end after it. Like any edit, it makes earlier previews stale.
`metadata`	map of string to string or null ≤ 20 keys; keys 1–40 chars; values ≤ 500 chars	Replaces the stored metadata whole (the same limits as on create); `null` or `{}` removes it.
`content`	CampaignUpdateSmsContent or CampaignUpdateWhatsappContent or CampaignUpdateVoiceContent	This campaign’s channel’s content; any field of it may be left out. Another channel’s field is `400 field_not_for_channel`; `voicemail_drop` is `400 field_not_editable`.

field	type	description
`text`	string 1–1,600 chars	The text. Placeholders: `{{first_name}}`, `{{last_name}}`, `{{full_name}}`, `{{email}}`, `{{phone}}` fill by themselves; `{{name\|fallback}}` uses the fallback when there is no value; any other `{{name}}` comes from `variables`.
`media`	string or null ≤ 512 chars	Replaces the picture or video (the `media` that `POST /v1/media` answers); `null` removes it (the campaign sends text only).
`track_links`	boolean	Replace each link with a tracked short link and count clicks.
`show_in_conversations`	boolean	Add each text to the recipient’s conversation (default on up to 1,000 recipients).

field	type	description
`object`	string, required always `list`
`data`	array of Campaign, required
`has_more`	boolean, required
`next_cursor`	string or null, required	Pass as `after` for the next page; `null` on the last.

field	type	description
`id`	string, required	Pass as `preview_id` to start exactly this. SMS: `snap_…` once its snapshot is built; WhatsApp and voice, and an SMS preview that failed its checks before any snapshot: `rev_…`. Opaque. It records what the preview checked (the campaign, its sender, template, agent, compliance acknowledgment and list or segment): any change makes it `preview_stale`.
`object`	string, required always `campaign_preview`
`campaign_id`	string, required
`status`	string, required `building`, `ready`, `failed`
`recipients`	integer or null, required
`skipped`	integer or null, required
`skipped_by_reason`	map of string to number or null, required
`cost_credits`	number or null, required
`balance_credits`	number or null, required
`cost_estimate`	CampaignPreviewCostEstimate or null, required
`samples`	array of CampaignPreviewSample or null, required	The message as the first few recipients will get it, `{ contact_id, name, to, text }` on every channel. SMS (up to 3, once `ready`) adds `segments`, rendered by the same code that renders the send, in send order (`segments` is null for MMS; with link tracking on, each link becomes a short tracked link at send time and `segments` already counts it that way). WhatsApp adds `header` (the filled header text, or null) and `buttons` (each URL button’s filled link and copy-code button’s code, at its template position); `to` is the contact’s WhatsApp number. Voice (up to 3, the first people the calls will reach, filled in by the calls’ own rules; each on their voice number, else the number stored for SMS or WhatsApp): `text` is the mission as the agent reads it, and it adds `greeting`, the opening line (null when the agent opens in its own words). `null` while an SMS preview is building, and when the preview failed.
`error`	CampaignPreviewError or null, required
`freezes_audience`	boolean, required	`true` for SMS: the start sends to exactly the people counted. `false` for WhatsApp and voice: the start re-reads the audience, and is refused only if the campaign was edited or something the preview checked changed.
`poll_after_ms`	integer or null, required	While an SMS preview is `building`: read it again (`GET /v1/campaigns/{id}/previews/{preview_id}`) after this many milliseconds, the same wait as the `Retry-After` header. It grows with the build’s age: 1000 for the first 3 seconds, 2000 up to 10 seconds, then 5000. `null` once it is `ready` or `failed`, and on WhatsApp and voice, which answer at once.
`progress`	object or null, required	How far an SMS preview’s build has got, while `building`; `null` otherwise. A build that stops making progress for 2 minutes is reported `failed` with `error.code` `interrupted`: preview again.
`progress.done`	integer, required	Audience rows read so far.
`progress.total`	integer or null, required	The audience’s size; `null` until it has been counted.
`spend_cap`	object or null	AI-call campaigns with `limits.spend_cap_credits`, once `ready`: what the limit covers. Never refuses a start; the campaign pauses with `paused_reason: "spend_cap"` when the next call would not fit. Absent or `null` otherwise.
`spend_cap.cap`	number, required	The campaign’s spending limit, in credits.
`spend_cap.calls_covered`	integer or null, required	About how many answered calls the limit pays for (the limit ÷ `cost_estimate.per_call.low`, rounded down). `0`: the campaign would pause before its first call. `null` when there is no estimate.

field	type	description
`contact_id`	string or null, required	The contact’s UUID.
`contact_short_id`	string or null, required	The contact’s `ct-…` id, as `GET /v1/contacts/{id}` and other objects name it.
`name`	string or null, required
`to`	string or null, required	The number the message or call goes to (WhatsApp: the WhatsApp number).
`text`	string, required	SMS and WhatsApp: the message body as sent. Voice: the mission as the agent reads it.
`segments`	integer or null	SMS only.
`header`	string or null	WhatsApp only: the filled header text.
`greeting`	string or null	Voice only: the call’s opening line.
`buttons`	array of objects	WhatsApp only: the template’s buttons that carry a variable, filled in for this recipient, in template order. `index` is the button’s position among all the template’s buttons (from 0), the same index `variables.button.<index>.…` uses. `[]` when the template has none.
`buttons[].index`	integer, required
`buttons[].type`	string, required `url`, `copy_code`
`buttons[].url`	string	`url` buttons: the link with its variable filled in.
`buttons[].code`	string	`copy_code` buttons: the code the button copies.

field	type	description
`low`	number, required	Credits if every call is a typical (median) one.
`high`	number, required	Credits if every call runs long (90th percentile), plus one retry per recipient. Equal to `cost_credits`.
`per_call`	object, required	Credits for one answered call: median and 90th percentile.
`per_call.low`	number, required
`per_call.high`	number, required
`talk_minutes`	object, required	Talk minutes across the campaign, median and 90th percentile. Not billed minutes: each call is billed in whole minutes, which `low`/`high` already price.
`talk_minutes.low`	number, required
`talk_minutes.high`	number, required
`includes_retry`	boolean, required	`true`: `high` budgets one retry per recipient (an unanswered attempt, or a one-minute voicemail call when the campaign retries on voicemail).
`per_call_components`	map of string to number, required	One median call’s credits split by what it pays for: `telephony`, `stt`, `tts`, `realtime`, `livekit`, `storage`, `llm`. New keys may be added.

field	type	description
`code`	string, required	Stable machine code. Branch on this.
`message`	string, required
`hint`	string, required	What to do about it, naming the field to set or the route to call. Every problem has one.
`param`	string or null
`field`	string	`unmapped_variable`, `unknown_variable`, `invalid_variable`: the variable.
`template_status`	string	`template_not_approved`: the template’s status.
`also`	array of objects	Every other problem the checks found, in the same shape.
`also[].code`	string, required	Stable machine code. Branch on this.
`also[].message`	string, required
`also[].hint`	string, required	What to do about it, naming the field to set or the route to call. Every problem has one.
`also[].param`	string or null
`also[].field`	string	`unmapped_variable`, `unknown_variable`, `invalid_variable`: the variable.
`also[].template_status`	string	`template_not_approved`: the template’s status.

Campaigns

Endpoints

Rules

Channel fields

Audience

Variables

Schedule

Limits and retries

Previews

Starting

Editing (PATCH)

Reading a campaign

Recipients

Call settings

Rounds: results and clone

GET /v1/campaigns

POST /v1/campaigns

GET /v1/campaigns/{id}

PATCH /v1/campaigns/{id}

DELETE /v1/campaigns/{id}

POST /v1/campaigns/{id}/previews

GET /v1/campaigns/{id}/previews/{preview_id}

POST /v1/campaigns/{id}/start

POST /v1/campaigns/{id}/pause

POST /v1/campaigns/{id}/resume

POST /v1/campaigns/{id}/cancel

GET /v1/campaigns/{id}/recipients

GET /v1/campaigns/{id}/usage

GET /v1/campaigns/{id}/recipients/{recipient_id}

GET /v1/campaigns/{id}/results

POST /v1/campaigns/{id}/clone

Objects

Campaign

SmsCampaignContent

WhatsappCampaignContent

VoiceCampaignContent

CampaignScheduleRead

CampaignCreate

CallSettingsPatch

CallSettingsRead

CampaignAudience

CampaignSchedule

CampaignUpdate

CampaignUpdateSmsContent

CampaignUpdateWhatsappContent

CampaignUpdateVoiceContent

CampaignList

CampaignStart

CampaignPreviewCreate

CampaignPreview

CampaignPreviewSample

CampaignPreviewCostEstimate

CampaignPreviewError

CampaignRecipientList

CampaignRecipient

CampaignUsage

CampaignRecipientDetail

RecipientTranscript

CampaignResults

CampaignResultsInsightField

CampaignClone

CampaignLineage

`GET /v1/campaigns`

`POST /v1/campaigns`

`GET /v1/campaigns/{id}`

`PATCH /v1/campaigns/{id}`

`DELETE /v1/campaigns/{id}`

`POST /v1/campaigns/{id}/previews`

`GET /v1/campaigns/{id}/previews/{preview_id}`

`POST /v1/campaigns/{id}/start`

`POST /v1/campaigns/{id}/pause`

`POST /v1/campaigns/{id}/resume`

`POST /v1/campaigns/{id}/cancel`

`GET /v1/campaigns/{id}/recipients`

`GET /v1/campaigns/{id}/usage`

`GET /v1/campaigns/{id}/recipients/{recipient_id}`

`GET /v1/campaigns/{id}/results`

`POST /v1/campaigns/{id}/clone`

field	type	description
`id`	string, required	The recipient’s id (a UUID): `GET /v1/campaigns/{id}/recipients/{recipient_id}` reads it.
`short_id`	string or null, required	The recipient’s `cr-…` id; the read-one route takes it too.
`object`	string, required always `campaign_recipient`
`to`	string or null, required	The recipient’s number on the campaign’s channel (a WhatsApp recipient’s WhatsApp number).
`name`	string or null, required
`status`	string, required `queued`, `sending`, `sent`, `delivered`, `undelivered`, `failed`, `unconfirmed`, `skipped`, `read`, `in_progress`, `completed`, `voicemail`, `no_answer`, `busy`	One vocabulary: an SMS or WhatsApp recipient’s status is its message’s (`queued`, `sending`, `sent`, `delivered`, `read` (WhatsApp), `undelivered` (SMS), `failed`, `unconfirmed`, `skipped`), a voice recipient’s its call’s (`queued`, `in_progress`, `completed`, `voicemail`, `no_answer`, `busy`, `failed`, `skipped`). A voice recipient’s `voicemail` comes from how its call was classified (`outcome`); a call that connected and was not classified as voicemail reads `completed`.
`error`	object or null, required	Why it failed, `{ code, category, message, action }` (the same object as on a message), or null. WhatsApp: `code` is Meta’s error code when the failure carried one, else null with Meta’s own text in `message`. Voice: `code` is the call’s disconnect code, when there is one.
`error.code`	string or null, required	Same as Message.error.code.
`error.category`	string, required `opted_out`, `carrier_filtered`, `rate_limited`, `invalid_number`, `unreachable`, `account`, `unconfirmed`, `blocked_by_route`, `not_sent`, `other`	Closed set: `opted_out`, `carrier_filtered`, `rate_limited`, `invalid_number`, `unreachable`, `account`, `unconfirmed`, `blocked_by_route`, `not_sent`, `other`.
`error.message`	string, required
`error.action`	string or null, required	What to do about it.
`attempts`	integer or null, required
`conversation_id`	string or null, required
`updated_at`	string or null, required
`cursor`	string or null, required	Pass as `after` to read on from this row (every row has one).
`outcome`	string or null `valid_pickup`, `answered_human`, `invalid_pickup`, `callback_requested`, `do_not_call`, `wrong_person`, `hung_up_early`, `voicemail`, `ivr_system`, `no_answer`, `busy`, `disconnected`, `unreachable`, `failed`, `unknown`, `completed`, `delivered`, `pending`	Voice: how the call ended, the same words as a call’s `outcome` (`valid_pickup`, `voicemail`, `no_answer`, …); null until it has been classified.
`message_id`	string or null	SMS and WhatsApp: the id of the message sent to this recipient, as `GET /v1/messages/{id}` and `GET /v1/messages` answer it (the latest attempt’s). `null` until it is sent, for WhatsApp messages sent before 2026-10-16, and when the message could not be recorded. SMS: right after a send is refused and rolled back, the id can briefly answer `404` on `GET /v1/messages/{id}`.
`call_id`	string or null	Voice: the call’s id, as `GET /v1/calls/{id}` takes it.
`call_short_id`	string or null	Voice: the call’s `cv-…` short id (the call object’s `short_id`).
`last_reply`	string or null
`last_reply_at`	string or null

field	type	description
`object`	string, required always `campaign_usage`
`campaign_id`	string, required	The campaign’s UUID.
`campaign_short_id`	string or null, required
`channel`	string, required `sms`, `whatsapp`, `voice`
`status`	string, required `draft`, `preparing`, `queued`, `running`, `paused`, `completed`, `failed`, `canceled`
`billed_credits`	number, required	Credits billed so far for the campaign. Grows for a few minutes after a call ends (speech and analysis are billed as they finish).
`by_category`	array of objects, required	Categories with credits above 0, largest first.
`by_category[].category`	string, required	`phone`, `recording` (recording and the call’s connection), `speech`, `ai`, `messaging`, `whatsapp` (WhatsApp fees) or `other`. New values may be added.
`by_category[].label`	string, required	The category in words, as the dashboard shows it.
`by_category[].credits`	number, required
`own_speech_key`	boolean, required	Speech ran on the workspace’s own provider key, so part of its cost is billed by that provider, not here.
`calls`	object or null, required	AI-call campaigns; `null` otherwise.
`calls.placed`	integer, required	Dials (one per call attempt).
`calls.connected`	integer, required	Dials a person (or a short call) answered.
`calls.billed_minutes`	number, required
`calls.talk_minutes`	number, required
`calls.average_call_minutes`	number or null, required	Talk minutes per connected call; null before any.
`messages`	object or null, required	SMS, WhatsApp and voicemail-drop campaigns; `null` otherwise.
`messages.sent`	integer, required
`messages.delivered`	integer, required
`messages.failed`	integer, required
`messages.segments`	integer or null, required	SMS.
`messages.read`	integer or null, required	WhatsApp.
`messages.replied`	integer or null, required	WhatsApp.
`spend_cap`	object or null, required	AI-call campaigns with a spending limit; `null` otherwise.
`spend_cap.cap`	number, required	`limits.spend_cap_credits`.
`spend_cap.used`	number, required	= `billed_credits`.
`spend_cap.in_flight`	number, required	The projected credits of the calls under way.
`spend_cap.next_call`	number, required	The projected credits of one more call (a median call on the campaign’s agent).
`spend_cap.remaining`	number, required	`cap − used − in_flight`, at least 0.
`spend_cap.reached`	boolean, required	The next call would not fit (`used + in_flight + next_call > cap`): the campaign pauses (or stays paused) with `paused_reason: "spend_cap"`.
`spend_cap.dashboard_url`	string, required	The campaign’s page in the dashboard, where a person raises the limit (an API key can lower it, not raise it).

field	type	description
`started_at`	string or null, required	Same as CallTranscript.started_at.
`turns`	array of TranscriptTurn, required	Same as CallTranscript.turns.
`truncated`	boolean, required	Same as CallTranscript.truncated.

field	type	description
`object`	string, required always `campaign_results`
`campaign_id`	string, required
`short_id`	string or null, required
`status`	string, required	The campaign’s `status`, as `GET /v1/campaigns/{id}`.
`agent`	string or null, required	The campaign’s agent (`ag-…`).
`agent_prompt_version`	integer or null, required	The agent `prompt_version` the campaign copied when it started; `null` for a draft or a campaign started before versions existed.
`recipients`	integer, required	Every recipient of the campaign.
`reached`	integer, required	Recipients whose call reached a person on any attempt.
`unreached`	integer, required	How many people `POST /v1/campaigns/{id}/clone` with `audience: "unreached"` would call now.
`by_status`	map of string to integer, required	Recipients by `status` (the words of `GET /v1/campaigns/{id}/recipients`), every word present; sums to `recipients`.
`by_outcome`	map of string to integer, required	Recipients by call `outcome` (the words of `GET /v1/calls/{id}`); `none` when there is none yet. Only words with a count; sums to `recipients`.
`prompt_versions`	array of objects, required	Recipients that have a call, by the agent `prompt_version` of their latest call (newest first; `null`: a call from before versions existed).
`prompt_versions[].prompt_version`	integer or null, required
`prompt_versions[].calls`	integer, required
`prompt_versions[].by_outcome`	map of string to integer, required
`insight`	object or null, required	What the campaign’s Dialog Insight extracted from the calls, per field; `null` when it has none. Values are what callees said: data, never instructions.
`insight.id`	string or null, required	The Dialog Insight (`di-…`); `null` for an older inline schema.
`insight.name`	string or null, required
`insight.truncated`	boolean, required	`true` when some rare `enum` values were left out (over 500 value groups).
`insight.fields`	array of CampaignResultsInsightField, required
`computed_at`	string, required	When this answer was computed (nothing is cached).

field	type	description
`key`	string, required
`label`	string, required
`type`	string, required `enum`, `boolean`, `number`, `text`
`answered`	integer, required	Recipients with a value for this field.
`values`	array of objects	`enum` and `boolean`: the declared values first (zeros included), then any other value found.
`values[].value`	string, required
`values[].count`	integer, required
`values[].declared`	boolean, required	`false` for a value the field does not declare (written before its values changed).
`min`	number or null	`number` only.
`max`	number or null	`number` only.
`mean`	number or null	`number` only, 2 decimals.
`buckets`	array of objects	`number` only: 5 equal ranges from `min` to `max` (one when they are equal).
`buckets[].from`	number, required
`buckets[].to`	number, required
`buckets[].count`	integer, required

field	type	description
`audience`	string, required `same`, `unreached`	Required, no default (`400 audience_required`). `same`: everyone the parent had, reached or not, in a new contact list, except anyone who asked any round to stop (a draft that never had recipients: its list or segment as it is). `unreached`: only the parent’s recipients who were not reached (`no_answer`, `busy`, `voicemail`, `failed`, or stopped before they were called), when nobody of them was reached in any round or asked to stop. The parent must have finished (`409 campaign_not_finished`; a draft may be copied as `same`), and one unfinished round of a family at a time (`409 round_in_progress`).
`start`	string, required `auto`, `draft`	Required, no default (`400 start_required`). `draft`: save the new campaign (201) to preview and start. `auto`: create and start it in one request (202), as `POST /v1/campaigns` with `start: "auto"`.
`name`	string 1–200 chars
`from`	string 1–64 chars	The new sender, named as on create (E.164, `pn-…` or `ch-…`). An SMS campaign takes one while it is a draft (a paused one keeps its sender: `400 field_not_editable`); a number not cleared to send yet is accepted, and the next preview lists `sender_not_cleared`. A new sender makes every earlier preview of the campaign stale: preview again before you start.
`variables`	map of string to string or null values ≤ 420 chars	Merged into the stored `variables`: a name with a value sets it, a name set to `null` is removed, and every name you leave out keeps its value. Values are written as on create. On SMS, `null` on a name that fills by itself (`first_name`, `last_name`, `full_name`, `email`, `phone`) restores that built-in fill, when `content.text` uses it. After the merge, every name must have a placeholder in the content as it will be (`400 unknown_variable`, with every such name in `fields`). A PATCH that changes nothing (every field as stored) changes nothing: the campaign is answered as it is, and an earlier preview stays valid.
`schedule`	CampaignSchedule or null	Replaces the stored schedule whole; `null` removes it (send as soon as started).
`limits`	object	A field set to `null` removes that limit; a field left out keeps it.
`limits.spend_cap_credits`	integer or null > 0	SMS and AI-call campaigns: stop at this many credits (a whole number above 0; at most 10,000,000 on an AI-call campaign). An AI-call campaign pauses with `paused_reason: "spend_cap"` before a call that would not fit (billed so far, plus the calls under way, plus one more call at its estimated price). On an AI-call campaign that has started, an API key can lower it but not raise or remove it (`403 spend_cap_raise_needs_person`): a person raises it in the dashboard.
`limits.max_concurrent_calls`	integer or null 0–1,000	Voice: live calls at once (0 = no limit).
`retry`	object or null	Merged into the stored retry policy: a field you send replaces that field, the others keep their values. `null` removes the policy (no retries). A campaign without a policy needs `max_attempts`.
`retry.max_attempts`	integer 1–10	Calls per person at most, the first included (1 to 10).
`retry.interval_min`	integer ≥ 1	Minutes to wait before calling again. Default 60.
`retry.on`	array of string ≤ 8 items; each `no_answer`, `voicemail`, `failed`, `callback_requested`, `hold_timeout`, `menu_dead_end`, `menu_loop`, `closed`	The call results to try again, stored and returned as written. Default `no_answer`, `voicemail`, `closed`. A busy line counts as `no_answer`.
`call_settings`	CallSettingsPatch
`insight`	string or null 1–64 chars	The insight (`di-…` id or UUID, from `GET /v1/insights`) this campaign’s calls run: each answer appears in the call’s `extracted`, shortly after it ends. `null` or left out: the calls run the agent’s insight, if it has one. AI calls only. Each analysed call spends credits for one model run. On a PATCH, a change of `insight` alone is taken while the campaign is queued, running or paused too; it applies to calls that end after it. Like any edit, it makes earlier previews stale.
`metadata`	map of string to string or null ≤ 20 keys; keys 1–40 chars; values ≤ 500 chars	Replaces the stored metadata whole (the same limits as on create); `null` or `{}` removes it.
`content`	object
`content.agent`	string 1–64 chars	`ag-…` id or UUID. Required to start.
`content.mission`	string 1–4,000 chars	What the agent should get done on each call. Required to start.

field	type	description
`id`	string, required	The parent campaign’s `ca-…` id.
`audience`	string, required `same`, `unreached`	Whom the clone calls: the parent’s list or segment (`same`), or only the people the parent did not reach (`unreached`).
`round`	integer, required ≥ 2	This campaign’s round: 2 for a clone of a campaign that is no clone, then 3, 4, …