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

# Build and Send API-Triggered Campaigns with Convo

> Learn how to build always-on API campaigns that send personalized WhatsApp templates to contacts one at a time, with delivery and engagement tracking.

API Campaigns are long-lived, always-on pipelines that tie an approved template to a named campaign. Instead of broadcasting to a static list, you trigger sends programmatically — one contact at a time — making them the right tool for **event-driven notifications** (order confirmations, OTPs, appointment reminders), **CRM-triggered outreach**, and **automated drip sequences**. Each send call accepts personalization variables, contact attributes, and tags so your analytics stay clean and segmentable.

<Tip>
  You can use the magic variables **`$Name`** and **`$FirstName`** in your `template_params` array and Convo will automatically substitute them with the contact's stored name — no extra lookup needed.
</Tip>

***

## Setting Up an API Campaign

<Steps>
  <Step title="Create the campaign">
    Create a named campaign and bind it to an approved template. You only need to do this once — the campaign stays `LIVE` indefinitely.

    ```text theme={null}
    POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/api
    ```

    | Header                     | Value               |
    | -------------------------- | ------------------- |
    | `X-API-WA-Project-API-Pwd` | `YOUR_API_PASSWORD` |
    | `Content-Type`             | `application/json`  |

    ```json theme={null}
    {
      "template_name": "shipping_update_v1",
      "campaign_name": "ShipmentAlerts_Q4"
    }
    ```

    **Response**

    ```json theme={null}
    {
      "id": "64f3a1b2c0e4d500123abc",
      "campaign_name": "ShipmentAlerts_Q4",
      "template_name": "shipping_update_v1",
      "status": "LIVE",
      "created_at": "2024-01-15T10:30:00Z"
    }
    ```

    Save the `id` — you'll need it for analytics and audience queries.
  </Step>

  <Step title="Send to a contact">
    Trigger a send to any individual contact. Convo looks up or creates the contact, substitutes `template_params` into the template body in order, and dispatches the message.

    ```text theme={null}
    POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/api/send
    ```

    ```json theme={null}
    {
      "name": "Ankit",
      "phone_number": "918116856153",
      "campaign_name": "ShipmentAlerts_Q4",
      "template_params": ["#ORDER-789", "3"],
      "source": "website",
      "default_country_code": "91",
      "attributes": {
        "order_id": "789",
        "region": "Mumbai"
      },
      "tags": ["premium_customer"]
    }
    ```

    | Field                  | Description                                                 |
    | ---------------------- | ----------------------------------------------------------- |
    | `name`                 | Contact's display name (creates or updates the contact)     |
    | `phone_number`         | Recipient phone with country code, no `+`                   |
    | `campaign_name`        | Must match an existing `LIVE` campaign                      |
    | `template_params`      | Ordered array mapped to `{{1}}`, `{{2}}`, … in the template |
    | `source`               | Free-text label to track where the send originated          |
    | `default_country_code` | Used if `phone_number` omits the country prefix             |
    | `attributes`           | Key-value pairs stored against the contact                  |
    | `tags`                 | Segment labels applied to the contact                       |
  </Step>

  <Step title="Get campaign details">
    Retrieve metadata and current status for a specific campaign.

    ```text theme={null}
    GET https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/api/{campaign_id}
    ```

    The response includes `template_name`, `status`, creation timestamps, and the cumulative send count.
  </Step>

  <Step title="View analytics">
    Pull aggregated delivery and engagement metrics for any date range.

    ```text theme={null}
    POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/analytics/{campaign_id}
    ```

    ```json theme={null}
    {
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-01-31T23:59:59Z"
    }
    ```

    See the [Analytics Metrics](#analytics-metrics) section below for a full breakdown of the returned fields.
  </Step>

  <Step title="Fetch audience list">
    Retrieve a paginated list of contacts in a specific delivery category. Use `category` to filter by outcome and `limit` to control page size.

    ```text theme={null}
    GET https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/audience/{campaign_id}?category=READ&limit=100
    ```

    See [Audience Categories](#audience-categories) for all valid `category` values.
  </Step>
</Steps>

***

## Sending Media with Campaigns

If your template has a media header (`IMAGE`, `VIDEO`, or `FILE`), include a `media` object in your send request. Convo uses the `url` as the header media and `filename` as the display name shown to the recipient.

```text theme={null}
POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/api/send
```

```json theme={null}
{
  "name": "Priya",
  "phone_number": "919876543210",
  "campaign_name": "PromoWithImage",
  "template_params": ["Priya", "20%"],
  "media": {
    "url": "https://example.com/banner.jpg",
    "filename": "summer_promo"
  }
}
```

The `url` must be a publicly accessible HTTPS link. For PDFs and documents, set `filename` with the appropriate extension (e.g., `"invoice.pdf"`) so the recipient sees a meaningful file name.

***

## Audience Categories

When fetching your campaign audience, filter by one of the following `category` values:

| Category    | Description                                     |
| ----------- | ----------------------------------------------- |
| `SENT`      | Message was dispatched from Convo to Meta       |
| `DELIVERED` | Message reached the recipient's device          |
| `READ`      | Recipient opened and read the message           |
| `FAILED`    | Delivery failed (invalid number, opt-out, etc.) |
| `REPLIED`   | Recipient sent a reply to the campaign message  |
| `CLICKED`   | Recipient tapped a CTA button in the message    |

***

## Analytics Metrics

The analytics response contains the following key fields:

| Field                    | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `sentChatCount`          | Total number of messages dispatched in the period      |
| `deliveredChatcount`     | Messages confirmed delivered to the recipient's device |
| `readChatCount`          | Messages opened by the recipient                       |
| `failedChatCount`        | Messages that could not be delivered                   |
| `repliedToCampaignCount` | Contacts who replied to the campaign message           |
| `engagementCount`        | Total interactions (replies + button clicks combined)  |

Use the **read rate** (`readChatCount / deliveredChatcount`) and **engagement rate** (`engagementCount / sentChatCount`) as your primary campaign health indicators.