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

# Create an API Campaign Tied to a WhatsApp Template

> Create an API campaign that links an approved WhatsApp Message Template to a reusable, named campaign for programmatic per-contact sends.

An **API Campaign** ties an approved WhatsApp Message Template to a reusable, named campaign. Once created (and its status is `LIVE`), you trigger individual per-contact sends via the [Send Campaign](https://convo.co.in/docs/api-reference/campaigns/send-campaign.md) endpoint — passing dynamic parameter values at send time for each recipient.

This two-step model (create once, send many) lets you configure the template association once and reuse it for all programmatic sends, without repeating template configuration on every API call.

## Endpoint

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

## Authentication

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

**project\_id** `string` *required*

Your Convo project ID.

## Request Body

**template\_name** `string` *required*

The `name` of an **approved** WhatsApp Message Template in your project. The template must have `status: "APPROVED"` — campaigns linked to pending or rejected templates cannot send messages.

**campaign\_name** `string` *required*

A unique name for this campaign within your project. This is the identifier you use in all subsequent [Send Campaign](https://convo.co.in/docs/api-reference/campaigns/send-campaign.md) calls. Choose a descriptive, stable name (e.g., `ShipmentAlerts_Q4_2024`).

## Request Example

```bash theme={null}
curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaign/api" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "shipping_update_v1",
    "campaign_name": "ShipmentAlerts_Q4_2024"
  }'
```

## Response

A successful request returns `200 OK` with the full campaign object. The campaign is immediately `LIVE` and ready to accept send requests.

**\_id** `string`

The unique identifier of this campaign.

**name** `string`

The campaign name you provided.

**type** `string`

Campaign type. Always `"API"` for campaigns created via this endpoint. Broadcast campaigns created in the dashboard have type `"BROADCAST"`.

**status** `string`

Current campaign status. Newly created API campaigns are always `"LIVE"`.

**message\_type** `string`

The media type of the linked template (e.g., `"TEXT"`, `"IMAGE"`, `"VIDEO"`).

**message\_payload** `object`

Contains the full `template` object that this campaign is linked to, including the template body, buttons, parameters, and metadata.

**created\_at** `string`

ISO 8601 timestamp of when the campaign was created.

```json theme={null}
{
  "_id": "64b3e1ac7f2c0a001d8e9f34",
  "name": "ShipmentAlerts_Q4_2024",
  "type": "API",
  "status": "LIVE",
  "message_type": "TEXT",
  "message_payload": {
    "template": {
      "_id": "64a1f3bc9e4a2b001c3d7f12",
      "name": "shipping_update_v1",
      "label": "Shipping Update",
      "status": "APPROVED",
      "category": "TRANSACTIONAL",
      "type": "TEXT",
      "language": "English",
      "text": "Hi {{1}}, your order {{2}} has been shipped and will arrive by {{3}}.",
      "sample_text": "Hi Priya, your order #ORD-4521 has been shipped and will arrive by Dec 10.",
      "total_parameters": 3,
      "footer_text": "Reply STOP to unsubscribe",
      "message_action_type": "CTA",
      "call_to_action": [
        {
          "type": "URL",
          "button_title": "Track Order",
          "button_value": "https://example.com/track/{{1}}"
        }
      ],
      "quick_replies": [],
      "project_id": "YOUR_PROJECT_ID"
    }
  },
  "project_id": "YOUR_PROJECT_ID",
  "created_at": "2024-07-16T09:30:00.000Z"
}
```

## Error Responses

| Status | Description |
| - | - |
| `400 Bad Request` | `campaign_name` already exists in your project, `template_name` is missing or refers to a non-existent or non-approved template. The response body includes a `message` field with details. |
| `500 Internal Server Error` | An unexpected server-side error occurred. |

```json theme={null}
{
  "error": "Bad Request",
  "message": "A campaign with name 'ShipmentAlerts_Q4_2024' already exists in this project."
}
```


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