Skip to main content
POST
Create a campaign
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.
Base URL: 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 starts sending right away, or is scheduled when scheduled_at is in the future. From there:
  • scheduled → sending when the scheduled time arrives.
  • sending or scheduled → paused when you pause it, and paused → sending when you resume it.
  • sending → completed when every recipient has been processed.
  • Any unfinished campaign → cancelled when you cancel it.
Campaign statuses are draft, scheduled, sending, paused, completed, cancelled, and failed.

List campaigns

Returns a paginated list of campaigns, newest first, with status, delivery counts, and scheduling details. Filter with the status query parameter.
cURL
The response holds items (an array of campaign objects), total, page, limit, and has_more.

Create campaign

Create a campaign that sends one approved template to an audience, and start it. Reference the template by its 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.
Vobiz resolves the recipients from your contacts when you create the campaign, so the audience must include at least one eligible contact. For 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

cURL
201 Created

Errors

  • 400 Bad Request - The body is invalid, or the template is not approved.
  • 404 Not Found - The channel or template was not found on your account.

Get campaign

Returns full details and delivery counters for a specific campaign. An unknown campaign returns 404.
cURL

Campaign actions

Control campaign execution. All three use POST with no request body and return a status object, for example { "status": "paused" }. An action that doesn’t fit the campaign’s current status returns 400, for example pausing a completed campaign. An unknown campaign returns 404.
cURL - pause
200 OK

Delete campaign

Permanently delete a campaign and its recipients. To delete a campaign that is sending, pause or cancel it first; otherwise the request returns 400. Returns 200 OK.
cURL
200 OK

List campaign recipients

Returns a paginated, per-contact delivery status, in the order recipients were added. Use it to audit delivery rates or identify failed recipients.
cURL
200 OK

Campaign object

Campaign recipient object

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token
string
header
required

Your Vobiz account Auth Token.

Path Parameters

auth_id
string
required

Your account Auth ID. It must match the X-Auth-ID header.

Example:

"MA_XXXXXXXX"

Body

application/json
channel_id
string<uuid>
required

The channel to send from.

Example:

"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1"

name
string
required

Campaign name.

Example:

"Diwali offer"

template_id
string<uuid>
required

The Vobiz id of an approved template on the channel, from GET /Channel/{channelId}/Template/.

Example:

"9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f"

template_components
object[]
required

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.

Example:
audience_type
enum<string>
required

all sends to every contact, tags to contacts with any of audience_tags, and manual to the contacts in audience_contact_ids. Lowercase. For MARKETING templates, +1 numbers are excluded.

Available options:
all,
tags,
manual
Example:

"tags"

variable_mappings
any

Any JSON value you want stored with the campaign and returned on reads. To fill body variables per recipient, use recipient_variables.

recipient_variables
object

Body variable values per recipient, keyed by the recipient's phone number, then by variable number: {"+919876543210": {"1": "Priya", "2": "20%"}}. A leading + on the key is optional.

Example:
audience_tags
string[]

Tags to target. Used when audience_type is tags.

Example:
audience_contact_ids
string<uuid>[]

Contact IDs to target. Used when audience_type is manual.

Example:
scheduled_at
string<date-time>

When to start sending (RFC 3339). Omit it, or send a time in the past, to start immediately.

Example:

"2026-11-01T04:30:00Z"

header_media_id
string

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.

Example:

"1234567890123456"

header_media_type
enum<string>

Type of header_media_id. Case-insensitive. Defaults to the header's format.

Available options:
image,
video,
document
Example:

"image"

Response

The campaign, sending or scheduled.

id
string<uuid>
required

Campaign ID.

Example:

"7b3e9d21-6c4a-4f8e-9a1b-2d5c8e7f3a10"

account_id
string
required
Example:

"MA_XXXXXXXX"

channel_id
string<uuid>
required
Example:

"0a8f3feb-9598-47f2-8a6c-df1aeb306ae1"

name
string
required
Example:

"Diwali offer"

template_id
string<uuid>
required
Example:

"9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f"

template_name
string
required

Name of the template, copied when the campaign was created.

Example:

"diwali_offer"

template_lang
string
required

Language of the template.

Example:

"en"

template_components
object[] | null
required

The template components sent with the campaign.

audience_type
enum<string>
required
Available options:
all,
tags,
manual
Example:

"tags"

audience_tags
string[] | null
required
Example:
audience_contact_ids
string<uuid>[] | null
required
Example:

null

scheduled_at
string<date-time> | null
required

When sending is scheduled to start, or null to send immediately.

Example:

null

status
enum<string>
required

Campaign state.

Available options:
draft,
scheduled,
sending,
paused,
completed,
cancelled,
failed
Example:

"sending"

pause_reason
string | null
required

Why the campaign was paused or cancelled. null or empty when it wasn't.

Example:

null

total_recipients
integer
required

Recipients resolved when the campaign was created.

Example:

120

sent_count
integer
required
Example:

0

delivered_count
integer
required
Example:

0

read_count
integer
required
Example:

0

failed_count
integer
required
Example:

0

skipped_count
integer
required
Example:

0

batch_size
integer
required

Messages sent per batch.

Example:

30

batch_delay_ms
integer
required

Delay between batches, in milliseconds.

Example:

10000

daily_send_count
integer
required

Messages sent today.

Example:

0

daily_send_date
string<date-time> | null
required

The day daily_send_count applies to.

Example:

null

created_at
string<date-time>
required
Example:

"2026-10-20T09:15:00Z"

updated_at
string<date-time>
required
Example:

"2026-10-20T09:15:00Z"

started_at
string<date-time> | null
required

When sending started.

Example:

"2026-10-20T09:15:00Z"

completed_at
string<date-time> | null
required

When the campaign completed, was cancelled or failed.

Example:

null

variable_mappings
any

The variable_mappings you sent, when you sent any.

header_media_id
string

Media ID used for the template's media header. Omitted when not set.

Example:

"1234567890123456"

header_media_type
string

Type of the header media. Omitted when not set.

Example:

"image"