> ## Documentation Index > Fetch the complete documentation index at: https://convo.co.in/docs/llms.txt > Use this file to discover all available pages before exploring further. # Convo Campaign Types: API Campaigns and Broadcasts > Convo supports API campaigns for triggered per-contact messaging and Broadcast campaigns for bulk sends. Learn how each type works and when to use them. 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) **1. 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 **2. 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: ```text theme={null} 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. **3. 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. | > [!TIP] > > **Example: Sending an order confirmation** > > ```json theme={null} > { > "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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.