Mon-Fri 10am - 6pm
Create Campaign
Base URL for your account: https://cpaas.studio
POST
/api/whatsapp/v1/campaigns
Create a campaign and launch it now (or schedule it with schedule_at). Recipients excluded by opt-out, blacklist or inactive status are recorded as skipped and cost nothing.
Parameters
| Param | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | |
channel |
string | if the key is not restricted | Your number's uid. |
template / language |
string | yes | An approved marketing or utility template (authentication templates are sent one by one with Send Template). |
variables |
object | per template | {"body.1": {"source": "name"}, "body.2": {"source": "attribute", "value": "city", "fallback": "your city"}} — source: attribute, name, phone or static. |
audience |
object | yes | {"type": "groups", "groups": ["WGR…"]}, {"type": "all"} or {"type": "filter", "attribute": "city", "value": "Kochi"}. |
header_media |
string | media-header templates | Media uid. |
schedule_at |
ISO-8601 | no | Omit to send now. |
drip_per_minute |
integer | no | Cap on messages per minute. |
launch |
boolean | no | false = save as draft. Default true. |
token |
string | no | Any string unique per intended campaign: a retried create with the same token returns the same campaign. |
Request example
curl -X POST "https://cpaas.studio/api/whatsapp/v1/campaigns" \
-H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"name":"Diwali offer","channel":"WCH54DZ7M7M5V","template":"diwali_offer","language":"en","variables":{"body.1":{"source":"name","fallback":"there"}},"audience":{"type":"groups","groups":["WGR4K7Q2M9X"]},"token":"diwali-2026-run-1"}'
Success response (data)
{
"campaign": {
"uid": "WCPFH2VWMY9ZA",
"name": "Diwali offer",
"channel": "WCH54DZ7M7M5V",
"status": "running",
"pause_reason": null,
"template": {
"name": "diwali_offer",
"language": "en",
"category": "marketing"
},
"counters": {
"total_recipients": 5000,
"queued_count": 4870,
"submitted_count": 2300,
"sent_count": 2210,
"delivered_count": 2100,
"read_count": 900,
"failed_count": 12,
"skipped_count": 130,
"cancelled_count": 0
},
"exclusions": {
"skipped_optout": 80,
"skipped_invalid": 40,
"skipped_duplicate": 10
},
"amounts": {
"estimated": 6574.5,
"charged": 3105,
"refunded": 13.5
},
"warning": null,
"last_error": null,
"scheduled_at": null,
"started_at": "2026-10-10T09:00:03+00:00",
"completed_at": null,
"created_at": "2026-10-10T08:59:40+00:00"
}
}
Errors
| Code | Status | When |
|---|---|---|
REQ_VALIDATION_FAILED |
422 | A field is invalid, the template is not approved / not found (field template_name), or nothing can be sent now (field campaign: no plan, category disabled, no allowance). |
Notes
- The allowance check at launch is a guide, not a reservation: allowance is taken as messages are sent. A campaign that runs out pauses (status paused_no_balance) and resumes after a top-up — nothing is failed.
- Marketing campaigns do not send during quiet hours (21:00–09:00 in your account's timezone by default); they continue when the window opens.
Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.