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

# 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](/api-reference/campaigns/send-campaign) 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

<ParamField path="project_id" type="string" required>
  Your Convo project ID.
</ParamField>

## Request Body

<ParamField body="template_name" type="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.
</ParamField>

<ParamField body="campaign_name" type="string" required>
  A unique name for this campaign within your project. This is the identifier you use in all subsequent [Send Campaign](/api-reference/campaigns/send-campaign) calls. Choose a descriptive, stable name (e.g., `ShipmentAlerts_Q4_2024`).
</ParamField>

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

<ResponseField name="_id" type="string">
  The unique identifier of this campaign.
</ResponseField>

<ResponseField name="name" type="string">
  The campaign name you provided.
</ResponseField>

<ResponseField name="type" type="string">
  Campaign type. Always `"API"` for campaigns created via this endpoint. Broadcast campaigns created in the dashboard have type `"BROADCAST"`.
</ResponseField>

<ResponseField name="status" type="string">
  Current campaign status. Newly created API campaigns are always `"LIVE"`.
</ResponseField>

<ResponseField name="message_type" type="string">
  The media type of the linked template (e.g., `"TEXT"`, `"IMAGE"`, `"VIDEO"`).
</ResponseField>

<ResponseField name="message_payload" type="object">
  Contains the full `template` object that this campaign is linked to, including the template body, buttons, parameters, and metadata.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the campaign was created.
</ResponseField>

```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."
}
```