WhatsApp Business API
WhatsApp Campaigns API — Bulk Template Broadcasts
Create and manage WhatsApp broadcast campaigns on Vobiz - send bulk outbound messages via Meta-approved templates to segmented contact audiences at scale.
POST
/
api
/
v1
/
Account
/
{auth_id}
/
WhatsApp
/
Campaign
/
Create a campaign
curl --request POST \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/ \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_components": [
{
"type": "BODY",
"text": "Hi {{1}}, enjoy {{2}} off this Diwali."
}
],
"audience_type": "tags"
}
'import requests
url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/"
payload = {
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_components": [
{
"type": "BODY",
"text": "Hi {{1}}, enjoy {{2}} off this Diwali."
}
],
"audience_type": "tags"
}
headers = {
"X-Auth-ID": "<api-key>",
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: '0a8f3feb-9598-47f2-8a6c-df1aeb306ae1',
name: 'Diwali offer',
template_id: '9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f',
template_components: [{type: 'BODY', text: 'Hi {{1}}, enjoy {{2}} off this Diwali.'}],
audience_type: 'tags'
})
};
fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "7b3e9d21-6c4a-4f8e-9a1b-2d5c8e7f3a10",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_name": "diwali_offer",
"template_lang": "en",
"template_components": [
{
"type": "BODY",
"text": "Hi {{1}}, enjoy {{2}} off this Diwali."
}
],
"variable_mappings": null,
"audience_type": "tags",
"audience_tags": [
"vip"
],
"audience_contact_ids": null,
"scheduled_at": null,
"status": "sending",
"pause_reason": "",
"total_recipients": 42,
"sent_count": 0,
"delivered_count": 0,
"read_count": 0,
"failed_count": 0,
"skipped_count": 0,
"batch_size": 30,
"batch_delay_ms": 10000,
"daily_send_count": 0,
"daily_send_date": null,
"created_at": "2026-10-20T09:15:00Z",
"updated_at": "2026-10-20T09:15:00Z",
"started_at": "2026-10-20T09:15:00Z",
"completed_at": null
}Prerequisites: Campaigns require an
approved template (you pass its template_id) and contacts to send to: all your contacts, contacts with given tags, or a list of contact IDs. See Templates API and Contacts API.https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp
Authentication: every request needs the X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. Set Content-Type: application/json on requests with a JSON body. Get your credentials from console.vobiz.ai.
Campaign lifecycle
A new campaign startssending right away, or is scheduled when scheduled_at is in the future. From there:
scheduled→sendingwhen the scheduled time arrives.sendingorscheduled→pausedwhen you pause it, andpaused→sendingwhen you resume it.sending→completedwhen every recipient has been processed.- Any unfinished campaign →
cancelledwhen you cancel it.
draft, scheduled, sending, paused, completed, cancelled, and failed.
List campaigns
GET https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/
status query parameter.
| Query param | Default | Description |
|---|---|---|
status | - | Filter by campaign status: draft, scheduled, sending, paused, completed, cancelled, or failed |
page | 1 | Page number, starting at 1 |
limit | 20 | Page size, from 1 to 100 |
cURL
curl -X GET \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Campaign/?status=completed&page=1&limit=20" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
items (an array of campaign objects), total, page, limit, and has_more.
Create campaign
POST https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/
template_id (the Vobiz UUID from the Templates API, not the template name). Choose the audience with audience_type. Set scheduled_at for a future send, or omit it to send immediately.
Creating a campaign sends real messages to real people and is charged to your account. Use your own credentials and confirm the audience before you create it.
MARKETING templates, +1 numbers are excluded. Messages go out in batches of 30, 10 seconds apart. Track progress with Get campaign and List campaign recipients.
Request body
| Field | Required | Description |
|---|---|---|
channel_id | Yes | Channel (UUID) to send from |
name | Yes | Campaign display name |
template_id | Yes | Vobiz id (UUID) of an approved template on the channel |
template_components | Yes | The template’s components, usually copied from the template’s components. Vobiz fills in header media, URL button parameters, and body variables at send time. |
audience_type | Yes | all (every contact), tags (contacts with any of audience_tags), or manual (the contacts in audience_contact_ids) |
audience_tags | Conditional | Array of contact tags. Used when audience_type is tags |
audience_contact_ids | Conditional | Array of contact IDs (UUIDs). Used when audience_type is manual |
recipient_variables | No | Body variable values per recipient, keyed by phone number, then by variable number: { "+919876543210": { "1": "Priya", "2": "20%" } }. A leading + on the key is optional. |
variable_mappings | No | Any JSON value you want stored with the campaign and returned on reads. To fill body variables per recipient, use recipient_variables. |
scheduled_at | No | RFC3339 datetime (UTC) to start sending. Omit it, or send a time in the past, to start immediately. |
header_media_id | No | Media ID from POST /Media/ for a template with an IMAGE, VIDEO, or DOCUMENT header. Without it, the template’s own example media is used. |
header_media_type | No | Type of header_media_id: image, video, or document. Case-insensitive; defaults to the header’s format. |
cURL
curl -X POST \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Campaign/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_components": [
{ "type": "BODY", "text": "Hi {{1}}, enjoy {{2}} off this Diwali." }
],
"audience_type": "tags",
"audience_tags": ["vip"],
"recipient_variables": {
"+919876543210": { "1": "Priya", "2": "20%" }
}
}'
201 Created
{
"id": "7b3e9d21-6c4a-4f8e-9a1b-2d5c8e7f3a10",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_name": "diwali_offer",
"template_lang": "en",
"template_components": [
{ "type": "BODY", "text": "Hi {{1}}, enjoy {{2}} off this Diwali." }
],
"variable_mappings": null,
"audience_type": "tags",
"audience_tags": ["vip"],
"audience_contact_ids": null,
"scheduled_at": null,
"status": "sending",
"pause_reason": "",
"total_recipients": 42,
"sent_count": 0,
"delivered_count": 0,
"read_count": 0,
"failed_count": 0,
"skipped_count": 0,
"batch_size": 30,
"batch_delay_ms": 10000,
"daily_send_count": 0,
"daily_send_date": null,
"created_at": "2026-10-20T09:15:00Z",
"updated_at": "2026-10-20T09:15:00Z",
"started_at": "2026-10-20T09:15:00Z",
"completed_at": null
}
Errors
400 Bad Request- The body is invalid, or the template is notapproved.404 Not Found- The channel or template was not found on your account.
Get campaign
GET https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/{id}/
404.
cURL
curl -X GET \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Campaign/{id}/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
Campaign actions
Control campaign execution. All three usePOST with no request body and return a status object, for example { "status": "paused" }.
| Endpoint | Description |
|---|---|
POST /Campaign/{id}/Pause/ | Pause a sending or scheduled campaign. Queued recipients wait until you resume or cancel it. Returns { "status": "paused" }. |
POST /Campaign/{id}/Resume/ | Resume a paused campaign; sending continues with the queued recipients. Returns { "status": "resumed" }. |
POST /Campaign/{id}/Cancel/ | Cancel a campaign that has not finished. Queued recipients are not sent, and cancelling can’t be undone. Returns { "status": "cancelled" }. |
400, for example pausing a completed campaign. An unknown campaign returns 404.
cURL - pause
curl -X POST "https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Campaign/{id}/Pause/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
200 OK
{ "status": "paused" }
Delete campaign
DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/{id}/
sending, pause or cancel it first; otherwise the request returns 400. Returns 200 OK.
cURL
curl -X DELETE "https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Campaign/{id}/" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
200 OK
{ "status": "deleted" }
List campaign recipients
GET https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/{id}/Recipient/
| Query param | Default | Description |
|---|---|---|
status | - | Filter by recipient status: queued, sending, sent, delivered, read, failed, or skipped |
page | 1 | Page number, starting at 1 |
limit | 20 | Page size, from 1 to 100 |
cURL
curl -X GET \
"https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/WhatsApp/Campaign/{id}/Recipient/?status=failed&page=1&limit=50" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN"
200 OK
{
"items": [
{
"id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a0c2e19",
"campaign_id": "7b3e9d21-6c4a-4f8e-9a1b-2d5c8e7f3a10",
"contact_id": "4f9c2a18-3e6b-4d2f-8b1a-9e7c5d3f1a02",
"phone_number": "+919876543210",
"variables": { "1": "Priya", "2": "20%" },
"status": "delivered",
"meta_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQzVGNkE3QjhDOUQwRTFGMkEzAA==",
"meta_error_code": null,
"meta_error_description": null,
"sent_at": "2026-10-20T09:16:00Z",
"delivered_at": "2026-10-20T09:16:03Z",
"read_at": null,
"created_at": "2026-10-20T09:15:00Z",
"updated_at": "2026-10-20T09:16:03Z"
}
],
"total": 42,
"page": 1,
"limit": 50,
"has_more": false
}
Campaign object
| Field | Type | Description |
|---|---|---|
id | UUID | Campaign ID |
account_id | string | Your account ID (MA_XXXXXXXX) |
channel_id | UUID | Channel the campaign sends from |
name | string | Campaign display name |
template_id | UUID | Approved template used |
template_name | string | Template name, copied when the campaign was created |
template_lang | string | Template language code |
template_components | array or null | The template components sent with the campaign |
variable_mappings | any | The variable_mappings you sent, or null |
audience_type | string | all, tags, or manual |
audience_tags | array or null | Targeted tags |
audience_contact_ids | array or null | Targeted contact IDs |
status | string | draft, scheduled, sending, paused, completed, cancelled, or failed |
pause_reason | string | Why the campaign was paused or cancelled. Empty string when not paused. |
total_recipients | int | Recipients resolved when the campaign was created |
sent_count | int | Messages sent |
delivered_count | int | Messages delivered |
read_count | int | Messages read |
failed_count | int | Messages failed |
skipped_count | int | Recipients skipped |
batch_size | int | Messages sent per batch |
batch_delay_ms | int | Delay between batches (ms) |
daily_send_count | int | Messages sent today |
daily_send_date | RFC3339 or null | The day daily_send_count applies to |
header_media_id | string | Media ID used for the template’s media header. Omitted when not set. |
header_media_type | string | Type of the header media. Omitted when not set. |
scheduled_at | RFC3339 or null | Scheduled send time (UTC), or null to send immediately |
started_at | RFC3339 or null | When sending started (UTC) |
completed_at | RFC3339 or null | When the campaign completed, was cancelled, or failed (UTC) |
created_at | RFC3339 | Creation timestamp (UTC) |
updated_at | RFC3339 | Last update timestamp (UTC) |
Campaign recipient object
| Field | Type | Description |
|---|---|---|
id | UUID | Recipient row ID |
campaign_id | UUID | Parent campaign |
contact_id | UUID | Contact targeted |
phone_number | string | Recipient phone (E.164) |
variables | object | This recipient’s body variables, from recipient_variables. Omitted when none were set. |
status | string | queued, sending, sent, delivered, read, failed, or skipped |
meta_message_id | string or null | WhatsApp message ID (wamid) once sent |
meta_error_code | string or null | Meta error code when the send failed |
meta_error_description | string or null | Meta error detail when the send failed |
sent_at | RFC3339 or null | Sent timestamp (UTC) |
delivered_at | RFC3339 or null | Delivered timestamp (UTC) |
read_at | RFC3339 or null | Read timestamp (UTC) |
created_at | RFC3339 | Creation timestamp (UTC) |
updated_at | RFC3339 | Last update timestamp (UTC) |
Authorizations
Path Parameters
Body
application/json
Response
The campaign, sending or scheduled.
Was this page helpful?
⌘I
Create a campaign
curl --request POST \
--url https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/ \
--header 'Content-Type: application/json' \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_components": [
{
"type": "BODY",
"text": "Hi {{1}}, enjoy {{2}} off this Diwali."
}
],
"audience_type": "tags"
}
'import requests
url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/"
payload = {
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_components": [
{
"type": "BODY",
"text": "Hi {{1}}, enjoy {{2}} off this Diwali."
}
],
"audience_type": "tags"
}
headers = {
"X-Auth-ID": "<api-key>",
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Auth-ID': '<api-key>',
'X-Auth-Token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: '0a8f3feb-9598-47f2-8a6c-df1aeb306ae1',
name: 'Diwali offer',
template_id: '9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f',
template_components: [{type: 'BODY', text: 'Hi {{1}}, enjoy {{2}} off this Diwali.'}],
audience_type: 'tags'
})
};
fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp/Campaign/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "7b3e9d21-6c4a-4f8e-9a1b-2d5c8e7f3a10",
"account_id": "MA_XXXXXXXX",
"channel_id": "0a8f3feb-9598-47f2-8a6c-df1aeb306ae1",
"name": "Diwali offer",
"template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
"template_name": "diwali_offer",
"template_lang": "en",
"template_components": [
{
"type": "BODY",
"text": "Hi {{1}}, enjoy {{2}} off this Diwali."
}
],
"variable_mappings": null,
"audience_type": "tags",
"audience_tags": [
"vip"
],
"audience_contact_ids": null,
"scheduled_at": null,
"status": "sending",
"pause_reason": "",
"total_recipients": 42,
"sent_count": 0,
"delivered_count": 0,
"read_count": 0,
"failed_count": 0,
"skipped_count": 0,
"batch_size": 30,
"batch_delay_ms": 10000,
"daily_send_count": 0,
"daily_send_date": null,
"created_at": "2026-10-20T09:15:00Z",
"updated_at": "2026-10-20T09:15:00Z",
"started_at": "2026-10-20T09:15:00Z",
"completed_at": null
}