Skip to main content
POST

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json

A WhatsApp broadcast or a calling campaign, told apart by kind.

kind
string
required

whatsapp for a broadcast.

Allowed value: "whatsapp"
name
string
required

What the console lists it as. Runs of spaces are collapsed.

Required string length: 2 - 120
Example:

"Diwali sale — VIP customers"

template
string
required

The name of an approved template in this workspace (List Templates).

Example:

"diwali_offer_v2"

language
string

The template's language. Needed only when the name exists in more than one language.

Example:

"en"

agent
string

The agent that answers replies to this broadcast (ag_…). Leave it out and the agent on your connected WhatsApp number answers.

Example:

"ag_5c4a5f93-2b1e-4c0a-9d3f-7e8a1b2c3d4e"

variables
object[]

What fills each blank. Every {{n}} in the body, and the blank in a link button's address, must be filled.

Maximum array length: 20
offerExpiresAt
string<date-time>

When the offer's countdown ends. Required, and in the future, when the template counts down to an offer.

audience
enum<string>
default:whatsapp_consented

Which contacts the campaign draws from. whatsapp_consented: people who messaged you on WhatsApp and agreed to hear from you — the safest list, and a broadcast's default. consented: everyone who agreed to marketing, on any channel — a calling campaign's default. imported: contacts that came from your own imports; they may never have contacted you. everyone: every contact with a number. People who asked not to be contacted are left out whichever you choose.

Available options:
whatsapp_consented,
consented,
imported,
everyone
tags
string[]

Reach only contacts carrying at least one of these tags. Narrows the audience, never widens it. Tags are lower-cased, spaces become hyphens, and at most 20 are kept. To aim at your own list, add the contacts with Create Contact and a tag first.

Example:
groups
string[]

Reach only contacts in at least one of these contact groups, grp_…. Narrows the audience, never widens it. With tags, anyone carrying one of the tags OR in one of the groups.

Maximum array length: 20
Example:
followUp
object

Reach the people from an earlier campaign who answered it a certain way. Both fields, or leave the whole object out.

scheduledAt
string<date-time>

Start the campaign by itself at this time, in the future. Do not send it together with launch.

launch
boolean
default:false

true also starts it now, with Launch Campaign's checks. A refused launch keeps the draft and message says why.

Response

Created. The campaign as Get Campaign shows it, plus message: how many people it will reach, that it started, or why a requested launch did not happen (the campaign is then a draft you can launch later).

The campaign, plus a sentence about what just happened.

id
string
required

The campaign's id.

Example:

"cmp_9a3b7c21-4d5e-4f60-8a1b-2c3d4e5f6a7b"

agent
string
required

A calling campaign: the agent that makes the calls. A broadcast: the agent that answers replies to it.

Example:

"ag_5c4a5f93-2b1e-4c0a-9d3f-7e8a1b2c3d4e"

name
string
required

The campaign's name, as the console lists it.

kind
enum<string>
required

whatsapp for a broadcast, voice for a calling campaign.

Available options:
whatsapp,
voice
status
enum<string>
required

draft until launched (a scheduled campaign stays a draft until scheduledAt), sending while it runs, paused when stopped for now, then sent, failed (it could not run; see lastError) or cancelled.

Available options:
draft,
sending,
paused,
sent,
failed,
cancelled
template
string | null
required

A broadcast's template name. null on a calling campaign.

purpose
string | null
required

A calling campaign's opening line: the sentence the agent opens each call with, copied from the agent when the campaign was created (editing the agent later does not change it). null on a broadcast.

counts
object
required

How far the campaign has got, person by person.

scheduledAt
string<date-time> | null
required

When a scheduled campaign starts itself. null when it is started by hand.

startedAt
string<date-time> | null
required

When it started sending. null while a draft.

finishedAt
string<date-time> | null
required

When it finished or was cancelled. null while it can still send.

createdAt
string<date-time>
required

When it was created.

lastError
string | null
required

Why the campaign last stopped or failed, when it did. Cleared when it is launched or resumed.

message
string
required

What happened, in a sentence you can show a person: how many people it will reach, that sending or calling started (and, when the balance covers only part of it, how far it goes), or — on create with launch: true — why the launch was refused and the campaign kept as a draft.

Example:

"Created. 412 people will receive it."