> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/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).

<CardGroup cols={2}>
  <Card title="API Campaign" icon="bolt">
    **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
  </Card>

  <Card title="Broadcast Campaign" icon="megaphone">
    **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
  </Card>
</CardGroup>

***

## 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)

<Steps>
  <Step title="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
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.
</Tip>

***

## 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.