# Create a WhatsApp campaign

`POST https://api.chat-data.com/api/v2/whatsapp-campaigns`

Canonical: https://www.chat-data.com/api-reference/create-whatsapp-campaign

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Creates a campaign that sends one approved template to an audience from the chatbot's official WhatsApp integration, and starts it now or at `schedule.at`.

The audience is either a lead filter (the same filters as the dashboard builder) or a list of phone numbers. When the campaign starts, the audience is resolved once into one message per phone number. Numbers are excluded when they are invalid, blocked, opted out of marketing (marketing templates), US numbers on a marketing template, already sent a marketing template by this chatbot in the last 24 hours, or missing a variable value with no fallback.

`mapping` gives each slot of the template (named as in `/whatsapp-templates`, e.g. `body[1]`, `buttons[0][1]`) a source: a lead field (`name`, `first_name`, `email`, `phone`), a custom lead attribute, or fixed text, with an optional `fallback` used when the lead's value is empty.

With `replyMode: live_chat`, a recipient's reply is handed to a human agent in Live chats instead of the AI (requires the live chat plan feature).

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes |  |
| name | string | yes |  |
| from | string | no | The sending number; required when the chatbot has more than one. |
| template | object | yes |  |
| template.name | string | yes |  |
| template.language | string | no |  |
| mapping | object | no |  |
| media | object | no |  |
| media.link | string | no |  |
| media.id | string | no |  |
| flow | object | no |  |
| flow.data | object | no |  |
| replyMode | string | no | One of: `ai`, `live_chat`. |
| audience | object | yes |  |
| audience.type | string | no | One of: `filter`, `phones`. |
| audience.phones | array of string | no |  |
| audience.defaultCountry | string | no | Two-letter country for phone numbers without a country code. |
| audience.filter | object | no |  |
| audience.filter.search | string | no |  |
| audience.filter.tags | array of string | no |  |
| audience.filter.tagsMode | string | no | One of: `any`, `all`. |
| audience.filter.sources | array of string | no |  |
| audience.filter.createdFrom | string | no |  |
| audience.filter.createdTo | string | no |  |
| audience.filter.messagedWithinDays | integer | no |  |
| audience.filter.attributes | array of object | no |  |
| audience.filter.attributes[].name | string | no |  |
| audience.filter.attributes[].op | string | no | One of: `equals`, `contains`. |
| audience.filter.attributes[].value |  | no |  |
| audience.filter.attributes[].to |  | no |  |
| schedule | object | no |  |
| schedule.at | string | no |  |
| schedule.timeZone | string | no |  |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/whatsapp-campaigns' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "name": "November restock",
  "template": {
    "name": "Jane Doe"
  },
  "audience": {}
}'
```

## Example response (201)

```json
{
  "status": "success",
  "campaign": {
    "id": "6650f1c2a9e4b83d2c7a1f3c",
    "name": "Jane Doe",
    "phoneNumberId": "6650f1c2a9e4b83d2c7a1f3c",
    "template": {
      "name": "Jane Doe",
      "language": "sample language",
      "category": "sample category"
    },
    "replyMode": "ai",
    "status": "draft",
    "pauseReason": "sample pause reason",
    "schedule": {
      "at": "2026-10-14T09:30:00.000Z",
      "timeZone": "sample time zone"
    },
    "recipients": 10,
    "exclusions": {
      "opted_out": 3,
      "us_marketing": 12
    },
    "stats": {
      "queued": 10,
      "sent": 10,
      "delivered": 10,
      "read": 10,
      "replied": 10,
      "formCompleted": 10,
      "failed": 10,
      "cancelled": 10
    },
    "startedAt": "2026-10-14T09:30:00.000Z",
    "completedAt": "2026-10-14T09:30:00.000Z",
    "createdAt": "2026-10-14T09:30:00.000Z"
  }
}
```

## Responses

| Status | Description |
| --- | --- |
| 201 | The campaign, `scheduled` until it starts. |
| 400 | The campaign is invalid (`code` INVALID_CAMPAIGN) or the template cannot be used (template error codes as for `/send-whatsapp-template`). |
| 401 | Authentication failed. |
| 403 | The plan does not include live chat (for `replyMode: live_chat`), or the API key cannot access the chatbot. |
| 404 | The chatbot, the sending number or the template was not found. |