Send a bulk campaign

Send an approved WhatsApp template to many recipients at once. Each message is queued and sent through the same engine as the dashboard’s bulk campaigns, so you get the same pacing, retries, delivery tracking, and chat-history sync — driven entirely from the API. Two input modes:

Mode	Endpoint	Best for	Limit
JSON inline	`POST /api/v1/{subdomain}/campaigns/send`	programmatic sends, small/medium lists	1,000 recipients/request
CSV upload	`POST /api/v1/{subdomain}/campaigns/send-csv`	large lists, spreadsheet exports	50,000 rows/file

Both return immediately with a campaign_id (messages are queued, not sent synchronously). Track delivery via outbound webhooks or the Get message status endpoint. Required ability: messages.send.

How variable substitution works

A template’s body/header can contain positional placeholders {{1}}, {{2}}, … You map each placeholder to a recipient field using a @{key} expression in variables, and supply the value per recipient.

variables.body[0] → fills {{1}}, variables.body[1] → {{2}}, and so on.
@{firstname} resolves to each recipient’s firstname value.
Static text is allowed too: "variables": { "body": ["Welcome", "@{order}"] }.

The same applies to variables.header, variables.footer, and variables.button.

Buttons: only send variables.button for templates whose button URL is dynamic (contains a {{n}} placeholder). Static URL buttons, quick-reply, and copy-code buttons take no parameter — if you send one anyway, it is automatically ignored (so you can’t trigger a parameter-count error).

Media-header templates (IMAGE / VIDEO / DOCUMENT header) require a pre-uploaded header_media_id. If the template needs one and you omit it, the request returns 422 with a clear message.

Not supported in bulk: carousel (multi-card) templates and authentication/OTP templates. Use the single-message endpoints for those.

Mode 1 — JSON inline

Endpoint

POST /api/v1/{subdomain}/campaigns/send

Headers

Header	Value
`Authorization`	`Bearer <your-token>`
`Content-Type`	`application/json`

Body

{
  "campaign_name": "June Promo",
  "template_name": "welcome_message_1",
  "template_language": "en",
  "variables": {
    "body": ["@{firstname}", "@{order}"]
  },
  "recipients": [
    { "phone": "+919909919284", "firstname": "Rahul", "order": "Order #4471" },
    { "phone": "+918160748516", "firstname": "Priya", "order": "Order #4472" }
  ]
}

Body fields

string

required

A label for this campaign (shown in the dashboard).

string

required

An APPROVED template name for this workspace.

string

required

Template language code, e.g. en, en_US.

object

Per-section arrays of @{key} expressions. Keys: header, body, footer, button. Positional to the template’s {{1}}, {{2}}, …

string

Pre-uploaded WhatsApp media id — required only for templates with a media (IMAGE/VIDEO/DOCUMENT) header.

array

required

1–1000 objects. Each MUST have phone. Any other keys (firstname, order, …) are stored per recipient and are addressable from variables via @{key}.

curl -X POST "https://dash.example.com/api/v1/acme/campaigns/send" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "June Promo",
    "template_name": "welcome_message_1",
    "template_language": "en",
    "variables": { "body": ["@{firstname}"] },
    "recipients": [
      { "phone": "+919909919284", "firstname": "Rahul" },
      { "phone": "+918160748516", "firstname": "Priya" }
    ]
  }'

import requests

resp = requests.post(
    "https://dash.example.com/api/v1/acme/campaigns/send",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "campaign_name": "June Promo",
        "template_name": "welcome_message_1",
        "template_language": "en",
        "variables": {"body": ["@{firstname}"]},
        "recipients": [
            {"phone": "+919909919284", "firstname": "Rahul"},
            {"phone": "+918160748516", "firstname": "Priya"},
        ],
    },
)
print(resp.json())

const res = await fetch("https://dash.example.com/api/v1/acme/campaigns/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer <your_token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_name: "June Promo",
    template_name: "welcome_message_1",
    template_language: "en",
    variables: { body: ["@{firstname}"] },
    recipients: [
      { phone: "+919909919284", firstname: "Rahul" },
      { phone: "+918160748516", firstname: "Priya" },
    ],
  }),
});
const body = await res.json();

Mode 2 — CSV upload

Endpoint

POST /api/v1/{subdomain}/campaigns/send-csv

Form fields (multipart/form-data)

Field	Required	Notes
`campaign_name`	yes	campaign label
`template_name`	yes	APPROVED template
`template_language`	yes	e.g. `en`
`variables`	no	JSON string, e.g. `{"body":["@{firstname}"]}`
`header_media_id`	no	for media-header templates
`file`	yes	the `.csv` (≤ 20 MB / 50,000 rows)

CSV format — first row is the header; one column must be phone. All other columns become per-recipient values addressable via @{column}. Rows without a phone are skipped automatically.

phone,firstname,order
+919909919284,Rahul,Order #4471
+918160748516,Priya,Order #4472
919723275223,Mukesh,Order #4473

→ variables.body[0] = "@{firstname}" fills {{1}}, "@{order}" fills {{2}}, resolved per row.

curl -X POST "https://dash.example.com/api/v1/acme/campaigns/send-csv" \
  -H "Authorization: Bearer <your_token>" \
  -F "campaign_name=June Promo" \
  -F "template_name=welcome_message_1" \
  -F "template_language=en" \
  -F 'variables={"body":["@{firstname}","@{order}"]}' \
  -F "file=@recipients.csv"

import requests

with open("recipients.csv", "rb") as f:
    resp = requests.post(
        "https://dash.example.com/api/v1/acme/campaigns/send-csv",
        headers={"Authorization": "Bearer <your_token>"},
        data={
            "campaign_name": "June Promo",
            "template_name": "welcome_message_1",
            "template_language": "en",
            "variables": '{"body":["@{firstname}","@{order}"]}',
        },
        files={"file": f},
    )
print(resp.json())

Response

Both modes return the same envelope (HTTP 200):

{
  "status": "success",
  "message": "campaign_queued",
  "data": {
    "campaign_id": 88,
    "campaign_name": "June Promo",
    "template_name": "welcome_message_1",
    "total_recipients": 2,
    "queued": 2
  }
}

Field	Type	Notes
`campaign_id`	integer	Use to look up the campaign later.
`total_recipients`	integer	Recipients accepted (rows without a phone are excluded).
`queued`	integer	Messages queued for sending.

Per-message message_id (WhatsApp wamid) is not in this response — messages are queued, not yet sent. You receive each wamid in the message.sent webhook as the message goes out.

Tracking delivery

Every message — whether sent via this endpoint, the single-send endpoints, or the dashboard — emits delivery webhooks you can subscribe to: message.sent → message.delivered → message.read (or message.failed). Each event carries the message_id so you can match it back to your records. See Webhook Events → Message delivery status. For one-off lookups, use Get message status.

Error responses

Status	When	Example body
`401`	Missing / invalid token	`{"status":"error","message":"Invalid API token"}`
`403`	Missing ability	`{"status":"error","message":"Token does not have the required ability: messages.send"}`
`404`	Template not found / not approved	`{"status":"error","message":"Approved template not found for the given name and language"}`
`422`	Validation, or media-header template without `header_media_id`, or `> limit` recipients	`{"status":"error","message":"Template \"...\" has a IMAGE header — pass \"header_media_id\" ..."}`
`429`	Rate limit	`{"message":"Too many requests","retry_after":45}`

Sending speed beyond your token’s rate limit is handled internally by the queue — you don’t need to throttle the API call itself. Actual delivery pace to recipients is also subject to WhatsApp’s own per-number messaging tier.

Introduction

API Reference

Webhooks

Data Types

Send a bulk campaign

How variable substitution works

Mode 1 — JSON inline

Mode 2 — CSV upload

Response

Tracking delivery

Error responses

​How variable substitution works

​Mode 1 — JSON inline

​Mode 2 — CSV upload

​Response

​Tracking delivery

​Error responses

How variable substitution works

Mode 1 — JSON inline

Mode 2 — CSV upload

Response

Tracking delivery

Error responses