Convo Campaign Types: API Campaigns and Broadcasts

A Campaign in Convo is a named sending context that ties a WhatsApp Message Template to a set of recipients, delivery rules, and analytics tracking. Rather than sending raw messages, using a Campaign gives you delivery reporting, read-rate metrics, reply attribution, and audience management — all in one place. Every message sent through a Campaign is automatically tracked from dispatch through to delivery, read, and reply.

Campaign Types

Convo offers two fundamentally different Campaign types. Choosing the right type depends on whether your sends are event-driven (one contact at a time, triggered by something happening in your system) or scheduled (your entire audience at once).

API Campaign

Always live. Triggered per contact.An API Campaign stays in a LIVE state indefinitely. Your backend calls the Convo send endpoint each time an event occurs — a new order, a password reset, an appointment reminder — and Convo dispatches the template to that individual contact immediately.Best for:

Order confirmations and shipping updates
Abandoned cart reminders
OTP and verification messages
Any event-driven, personalised notification

Broadcast Campaign

One send, entire audience.A Broadcast Campaign targets a pre-defined audience (filtered by tags, attributes, or a contact list) and sends the template to everyone in that audience in a single scheduled operation.Best for:

Promotional announcements
Product launches and sales
Newsletter-style updates
Re-engagement campaigns

Campaign Statuses

The status of a Campaign reflects its current operational state. API and Broadcast Campaigns use different status vocabularies because they have different lifecycles.

Campaign Type	Status	Meaning
API	`LIVE`	The Campaign is active and accepting API send requests.
API	`PAUSED`	The Campaign has been temporarily paused. API send requests are rejected until resumed.
API	`STOPPED`	The Campaign has been permanently stopped and can no longer receive send requests.
Broadcast	`SENDING`	The Broadcast is currently being dispatched to the audience.
Broadcast	`SENT`	All messages in the Broadcast have been submitted to WhatsApp successfully.
Broadcast	`FAILED`	The Broadcast failed to send, typically due to a template rejection or account issue.

Campaign Workflow (API Campaigns)

Create the Campaign

Create a new API Campaign in the Convo dashboard or via the API, specifying:

A unique campaign_name (used as the identifier in send calls)
The approved template to use
Default country code for phone number normalisation

Call the send endpoint per recipient

Each time your system triggers an event (e.g., order placed), call the Campaign send endpoint with the recipient’s details and template parameters:

POST https://connect.api-wa.co/project-apis/v1/campaign/send

Convo resolves the template, substitutes your parameters, and dispatches the message to the contact over WhatsApp.

Track via analytics and audience endpoints

Use the Campaign analytics endpoint to retrieve aggregate delivery metrics, and the Campaign audience endpoint to inspect per-contact message statuses and replies.

Personalisation

Every send call to an API Campaign supports a rich set of personalisation fields that let you tailor the message for each individual recipient:

Field	Type	Description
`name`	string	The recipient’s display name. Creates or updates the Contact record.
`phone_number`	string	Recipient’s WhatsApp number (with or without country code).
`campaign_name`	string	The unique name of the API Campaign to trigger.
`template_params`	array of strings	Ordered values that replace `{{1}}`, `{{2}}`, etc. in the template body.
`default_country_code`	string	Country code prepended when `phone_number` has no prefix (e.g., `"91"`).
`media`	object	For media templates: `{ "url": "...", "filename": "..." }` pointing to the header asset.
`source`	string	Free-text label for the traffic source (e.g., `"website"`, `"crm_webhook"`).
`attributes`	object	Custom key-value pairs to merge into the contact’s attribute store.
`tags`	array of strings	Tags to apply to the contact at send time.

Example: Sending an order confirmation

{
  "name": "Ankit",
  "phone_number": "918116856153",
  "campaign_name": "order_confirmation",
  "template_params": ["#12345", "2 days"],
  "default_country_code": "91"
}

This call sends the order_confirmation template to +91 81168 56153 (Ankit), replacing {{1}} with #12345 (order ID) and {{2}} with 2 days (estimated delivery time). If Ankit doesn’t already exist as a Contact in your Project, Convo creates the record automatically.

Analytics

Both Campaign types expose engagement analytics so you can measure the effectiveness of your messaging. The following metrics are available through the Campaign analytics endpoint:

Metric	Description
`sentChatCount`	Total number of messages successfully submitted to WhatsApp.
`deliveredChatCount`	Messages confirmed as delivered to the recipient’s device.
`readChatCount`	Messages confirmed as read by the recipient (double blue tick).
`repliedToCampaignCount`	Recipients who sent at least one reply to a Campaign message.
`failedChatCount`	Messages that could not be delivered (invalid number, blocked, etc.).
`engagementCount`	Recipients who interacted with a button (Quick Reply or CTA tap).

Use the ratio of readChatCount to deliveredChatCount as your read rate, and repliedToCampaignCount to sentChatCount as your reply rate — these are the primary indicators of campaign quality on WhatsApp.

Get Started

Core Concepts

Guides

Convo Campaign Types: API Campaigns and Broadcasts

Campaign Types

API Campaign

Broadcast Campaign

Campaign Statuses

Campaign Workflow (API Campaigns)

Personalisation

Analytics

​Campaign Types

API Campaign

Broadcast Campaign

​Campaign Statuses

​Campaign Workflow (API Campaigns)

​Personalisation

​Analytics

Campaign Types

Campaign Statuses

Campaign Workflow (API Campaigns)

Personalisation

Analytics