Skip to main content
flag
Mon - Fri   10:00 – 18:00

Create Campaign

API Documentation / WhatsApp / 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.