Campaigns API

POST

api

messaging

campaigns

Campaigns API

curl --request POST \
  --url https://api.vobiz.ai/api/v1/messaging/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "channel_id": "<string>",
  "name": "<string>",
  "template_id": "<string>",
  "template_components": [
    {}
  ],
  "audience_type": "<string>"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/messaging/campaigns"

payload = {
    "channel_id": "<string>",
    "name": "<string>",
    "template_id": "<string>",
    "template_components": [{}],
    "audience_type": "<string>"
}
headers = {
    "X-Auth-ID": "<x-auth-id>",
    "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': '<x-auth-id>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: '<string>',
    name: '<string>',
    template_id: '<string>',
    template_components: [{}],
    audience_type: '<string>'
  })
};

fetch('https://api.vobiz.ai/api/v1/messaging/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Prerequisites: Campaigns require an approved template (you pass its template_id) and either contact tags or explicit contact IDs as the audience. See Templates API and Contacts API.

Base URL: https://api.vobiz.ai/api/v1/messaging Authentication: Every request requires X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: <token> headers (a Bearer JWT is also accepted). Set Content-Type: application/json on requests with a body. Get your credentials from console.vobiz.ai.

string

required

Your Vobiz account ID, for example MA_XXXXXXXX.

Campaign lifecycle

draft → scheduled → sending → paused → completed / cancelled / failed

List campaigns

GET https://api.vobiz.ai/api/v1/messaging/campaigns

Returns a paginated list of campaigns with status, delivery counts, and scheduling details. Filter with the status query parameter.

Query param	Default	Description
`status`	-	Filter by campaign status
`page`	`1`	Page number
`limit`	`20`	Page size (max `100`)

cURL

curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/campaigns?status=completed&page=1&limit=20" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"

200 OK

{
  "items": [
    {
      "id": "7c2e9a4d-1b3f-4e6a-8c9d-0f1a2b3c4d5e",
      "channel_id": "3f1c9b7e-2d4a-4f6b-9c8e-0a1b2c3d4e5f",
      "name": "Welcome Campaign",
      "template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
      "template_name": "welcome_message",
      "template_lang": "en_US",
      "status": "completed",
      "total_recipients": 142,
      "sent_count": 142,
      "delivered_count": 138,
      "read_count": 95,
      "failed_count": 4,
      "skipped_count": 0,
      "created_at": "2026-03-25T09:55:00Z",
      "updated_at": "2026-03-25T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "has_more": false
}

Create campaign

POST https://api.vobiz.ai/api/v1/messaging/campaigns

Create a new campaign. Reference an approved template by its template_id (a UUID, not a template name). Choose the audience with audience_type: use tags plus audience_tags, or contact_ids plus audience_contact_ids. Set scheduled_at for a future send, or omit it to send immediately.

Request body

Field	Required	Description
`channel_id`	Yes	Channel (UUID) to send from
`name`	Yes	Campaign display name
`template_id`	Yes	UUID of an approved template
`template_components`	Yes	Meta component structure for the template
`audience_type`	Yes	`tags` or `contact_ids`
`audience_tags`	Conditional	Array of contact tags. Required when `audience_type` is `tags`
`audience_contact_ids`	Conditional	Array of contact IDs. Required when `audience_type` is `contact_ids`
`variable_mappings`	No	Object mapping template variables to contact fields
`recipient_variables`	No	Object: `{ "<contact_id>": { "<key>": "<value>" } }` per-recipient values
`scheduled_at`	No	RFC3339 datetime (UTC) for a scheduled send

string

required

Channel (UUID) to send from.

string

required

Campaign display name.

string

required

UUID of an approved template.

object[]

required

Meta component structure for the template.

string

required

Either tags or contact_ids.

string[]

Array of contact tags. Required when audience_type is tags.

string[]

Array of contact IDs. Required when audience_type is contact_ids.

object

Object mapping template variables to contact fields.

object

Per-recipient values, shaped as { "<contact_id>": { "<key>": "<value>" } }.

string

RFC3339 datetime (UTC) for a scheduled send.

cURL

curl -X POST \
  "https://api.vobiz.ai/api/v1/messaging/campaigns" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "3f1c9b7e-2d4a-4f6b-9c8e-0a1b2c3d4e5f",
    "name": "Welcome Campaign",
    "template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
    "template_components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "{{1}}" }] }
    ],
    "audience_type": "tags",
    "audience_tags": ["vip"],
    "recipient_variables": {
      "1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718": { "1": "Asha" }
    },
    "scheduled_at": "2026-03-25T10:00:00Z"
  }'

201 Created

{
  "id": "7c2e9a4d-1b3f-4e6a-8c9d-0f1a2b3c4d5e",
  "channel_id": "3f1c9b7e-2d4a-4f6b-9c8e-0a1b2c3d4e5f",
  "name": "Welcome Campaign",
  "template_id": "9d8f1e2a-4c3b-4a1d-8e7f-1a2b3c4d5e6f",
  "template_name": "welcome_message",
  "template_lang": "en_US",
  "status": "scheduled",
  "total_recipients": 0,
  "sent_count": 0,
  "delivered_count": 0,
  "read_count": 0,
  "failed_count": 0,
  "skipped_count": 0,
  "scheduled_at": "2026-03-25T10:00:00Z",
  "created_at": "2026-03-25T09:55:00Z",
  "updated_at": "2026-03-25T09:55:00Z"
}

Get campaign

GET https://api.vobiz.ai/api/v1/messaging/campaigns/{id}

Returns full details and delivery statistics for a specific campaign.

cURL

curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/campaigns/{id}" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"

Campaign actions

Control campaign execution. All three use POST with no request body and return the updated Campaign.

Endpoint	Description
`POST /campaigns/{id}/pause`	Pause a sending campaign. Sending stops immediately.
`POST /campaigns/{id}/resume`	Resume a paused campaign.
`POST /campaigns/{id}/cancel`	Permanently cancel. Cannot be undone.

cURL - pause

curl -X POST "https://api.vobiz.ai/api/v1/messaging/campaigns/{id}/pause" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"

Delete campaign

DELETE https://api.vobiz.ai/api/v1/messaging/campaigns/{id}

Permanently delete a campaign. Returns 204 No Content.

cURL

curl -X DELETE "https://api.vobiz.ai/api/v1/messaging/campaigns/{id}" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"

204 No Content

// Empty body on success

List campaign recipients

GET https://api.vobiz.ai/api/v1/messaging/campaigns/{id}/recipients

Returns a paginated, per-contact delivery status. Use it to audit delivery rates or identify failed recipients. Filter with status and page with page / limit.

cURL

curl -X GET \
  "https://api.vobiz.ai/api/v1/messaging/campaigns/{id}/recipients?status=failed&page=1&limit=50" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: {auth_token}"

200 OK

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-4071-8293-a4b5c6d7e8f9",
      "campaign_id": "7c2e9a4d-1b3f-4e6a-8c9d-0f1a2b3c4d5e",
      "contact_id": "1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718",
      "phone_number": "+919876543210",
      "status": "read",
      "meta_message_id": "wamid.HBgM...",
      "sent_at": "2026-03-25T10:00:05Z",
      "delivered_at": "2026-03-25T10:00:07Z",
      "read_at": "2026-03-25T10:15:00Z",
      "created_at": "2026-03-25T09:55:00Z",
      "updated_at": "2026-03-25T10:15:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 50,
  "has_more": true
}

Campaign object

Field	Type	Description
`id`	UUID	Campaign ID
`channel_id`	UUID	Channel the campaign sends from
`name`	string	Campaign display name
`template_id`	UUID	Approved template used
`template_name`	string	Resolved template name
`template_lang`	string	Template language code
`status`	string	`draft`, `scheduled`, `sending`, `paused`, `completed`, `cancelled`, or `failed`
`total_recipients`	int	Total recipients resolved for the audience
`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	Recipients per batch
`batch_delay_ms`	int	Delay between batches (ms)
`pause_reason`	string	Reason if paused
`scheduled_at`	RFC3339	Scheduled send time (UTC)
`started_at`	RFC3339	When sending started (UTC)
`completed_at`	RFC3339	When sending completed (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	Per-recipient template variables
`status`	string	`queued`, `sent`, `delivered`, `read`, `failed`, or `skipped`
`meta_message_id`	string	Meta message ID (when sent)
`error_code`	string	Meta error code (on failure)
`error_desc`	string	Meta error description (on failure)
`sent_at`	RFC3339	Sent timestamp (UTC)
`delivered_at`	RFC3339	Delivered timestamp (UTC)
`read_at`	RFC3339	Read timestamp (UTC)
`created_at`	RFC3339	Creation timestamp (UTC)
`updated_at`	RFC3339	Last update timestamp (UTC)

Campaigns API

curl --request POST \
  --url https://api.vobiz.ai/api/v1/messaging/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <x-auth-id>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "channel_id": "<string>",
  "name": "<string>",
  "template_id": "<string>",
  "template_components": [
    {}
  ],
  "audience_type": "<string>"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/messaging/campaigns"

payload = {
    "channel_id": "<string>",
    "name": "<string>",
    "template_id": "<string>",
    "template_components": [{}],
    "audience_type": "<string>"
}
headers = {
    "X-Auth-ID": "<x-auth-id>",
    "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': '<x-auth-id>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: '<string>',
    name: '<string>',
    template_id: '<string>',
    template_components: [{}],
    audience_type: '<string>'
  })
};

fetch('https://api.vobiz.ai/api/v1/messaging/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​Campaign lifecycle

​List campaigns

​Create campaign

​Request body

​Get campaign

​Campaign actions

​Delete campaign

​List campaign recipients

​Campaign object

​Campaign recipient object

Campaign lifecycle

List campaigns

Create campaign

Request body

Get campaign

Campaign actions

Delete campaign

List campaign recipients

Campaign object

Campaign recipient object