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

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

***

## Setting Up an API Campaign

**1. 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.

**2. 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 |

**3. 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.

**4. 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.

**5. 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.

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.