Create an API Campaign Tied to a WhatsApp Template

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

POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/api

Authentication

X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD

Path Parameters

string

required

Your Convo project ID.

Request Body

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.

string

required

A unique name for this campaign within your project. This is the identifier you use in all subsequent Send Campaign calls. Choose a descriptive, stable name (e.g., ShipmentAlerts_Q4_2024).

Request Example

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.

string

The unique identifier of this campaign.

string

The campaign name you provided.

string

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

string

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

string

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

object

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

string

ISO 8601 timestamp of when the campaign was created.

{
  "_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.

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

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

Create an API Campaign Tied to a WhatsApp Template

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Error Responses

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Error Responses

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Error Responses