POST /project/{project_id}/campaigns — List Campaigns

Retrieve a paginated list of campaigns in your project. You can filter by campaign type — API, BROADCAST, or ALL — and paginate through results using skip and limit.

This endpoint uses POST (not GET) so that filter criteria can be passed in the request body rather than as query parameters.

Endpoint

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

Authentication

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

Path Parameters

string

required

Your Convo project ID.

Request Body

string

required

The type of campaigns to retrieve. Accepted values:

"API" — Returns only API campaigns (created programmatically via the Create Campaign endpoint).
"BROADCAST" — Returns only broadcast campaigns (created in the Convo dashboard).
"ALL" — Returns both API and broadcast campaigns.

integer

The number of records to skip before returning results. Use with limit to paginate through large lists. Defaults to 0.

integer

The maximum number of campaigns to return. Defaults to 10. Must be a positive integer.

Request Example

curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaigns" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignType": "API",
    "skip": 0,
    "limit": 10
  }'

To fetch the next page:

curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaigns" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignType": "API",
    "skip": 10,
    "limit": 10
  }'

Response

A successful request returns 200 OK with a campaigns array.

{
  "campaigns": [
    {
      "_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}}.",
          "total_parameters": 3
        }
      },
      "audience_size": 0,
      "submitted": 1482,
      "project_id": "YOUR_PROJECT_ID",
      "created_at": "2024-07-16T09:30:00.000Z"
    },
    {
      "_id": "64c2d4ff1a3b0b002e7f0a55",
      "name": "InvoiceDelivery_2024",
      "type": "API",
      "status": "LIVE",
      "message_type": "FILE",
      "message_payload": {
        "template": {
          "_id": "64b0c1aa3e2d1c001f4a8b99",
          "name": "invoice_delivery_v1",
          "label": "Invoice Delivery",
          "status": "APPROVED",
          "category": "TRANSACTIONAL",
          "type": "FILE",
          "language": "English",
          "text": "Hi {{1}}, please find your invoice {{2}} for ₹{{3}} attached.",
          "total_parameters": 3
        }
      },
      "audience_size": 0,
      "submitted": 374,
      "project_id": "YOUR_PROJECT_ID",
      "created_at": "2024-08-02T14:15:00.000Z"
    }
  ]
}

Campaign Object Fields

Field	Type	Description
`_id`	string	Unique campaign identifier.
`name`	string	Campaign name.
`type`	string	`"API"` or `"BROADCAST"`.
`status`	string	`"LIVE"`, `"PAUSED"`, or `"STOPPED"`.
`message_type`	string	Media type of the linked template.
`message_payload.template`	object	The linked WhatsApp template object.
`audience_size`	integer	Number of contacts in the campaign audience (0 for API campaigns — audience is determined per-send).
`submitted`	integer	Total number of messages sent through this campaign so far.
`project_id`	string	The project this campaign belongs to.
`created_at`	string	ISO 8601 creation timestamp.

Error Responses

Status	Description
`400 Bad Request`	`campaignType` is missing or not one of `"API"`, `"BROADCAST"`, `"ALL"`. `limit` or `skip` is not a valid integer.
`500 Internal Server Error`	An unexpected server-side error occurred.

{
  "error": "Bad Request",
  "message": "campaignType must be one of: API, BROADCAST, ALL."
}

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

POST /project/{project_id}/campaigns — List Campaigns

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Campaign Object Fields

Error Responses

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Campaign Object Fields

​Error Responses

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Campaign Object Fields

Error Responses