> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/chat/broadcast/create-a-campaign.md).

# Create a campaign

Sends an approved template to every contact in a recipient list, now or at a scheduled time. Messages go out in batches of 20.

The campaign is created with `status: processing` (sending now) or `status: scheduled`. Track it with `GET /api/campaigns` and `GET /api/v2/campaigns/{id}/messages`. Carousel templates are not supported.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Broadcast","description":"Use these endpoints to manage WhatsApp message templates, upload recipient lists, and run broadcast campaigns.\n\n## Typical flow\n1. **Create a template** with `POST /templates`. Meta reviews it; its `status` starts as `PENDING`.\n2. **Check approval** with `GET /api/templates`. Only templates with `status: APPROVED` can be sent. If you created or edited templates directly in Meta, call `POST /templates/sync` first to copy them into Cekat.\n3. **Send to one contact** with `POST /templates/send`, or continue below to send to many.\n4. **Upload a recipient list** with `POST /api/recipients`. Contacts are imported in the background; poll `GET /api/recipients` until the list's `total_contacts` matches the number returned by the upload.\n5. **Create a campaign** with `POST /api/campaigns`, using the template's `wa_template_id` as `template_id`. Leave out `schedule_at` to send right away.\n6. **Track results** with `GET /api/campaigns` for totals and `GET /api/v2/campaigns/{id}/messages` for each recipient's delivery status and replies.\n\nEvery step needs the `inbox_id` of a connected WhatsApp inbox. Get it from `GET /api/inboxes` (the `id` of an inbox whose `type` is `whatsapp`).\n"}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"responses":{"ApiBadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"schemas":{"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}}},"paths":{"/api/campaigns":{"post":{"tags":["Broadcast"],"operationId":"CreateCampaign","summary":"Create a campaign","description":"Sends an approved template to every contact in a recipient list, now or at a scheduled time. Messages go out in batches of 20.\n\nThe campaign is created with `status: processing` (sending now) or `status: scheduled`. Track it with `GET /api/campaigns` and `GET /api/v2/campaigns/{id}/messages`. Carousel templates are not supported.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaign_name","inbox_id","recipient_list_id","template_id"],"properties":{"campaign_name":{"type":"string"},"inbox_id":{"type":"string","format":"uuid","description":"The WhatsApp inbox that sends the campaign. It must own the template."},"recipient_list_id":{"type":"string","format":"uuid","description":"ID from `POST /api/recipients` or `GET /api/recipients`."},"template_id":{"type":"string","description":"The template's `wa_template_id`."},"template_body_variables":{"type":"array","description":"One value per body variable, in order. The count must match the template's highest variable number, and values cannot be empty.\nUse `name` or `phone_number` to insert each recipient's own name or number.\n","items":{"type":"string"}},"schedule_at":{"type":"string","format":"date-time","description":"When to start sending, as an ISO 8601 date-time in the future (for example `2026-10-20T09:00:00+07:00`). Leave out to send immediately."},"label_id":{"type":"string","format":"uuid","description":"Optional label added to each recipient's conversation. Follow-ups set up for this label in the inbox also run."}}}}}},"responses":{"201":{"description":"Campaign created and queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Campaign ID."},"campaign_name":{"type":"string"},"status":{"type":"string","enum":["processing","scheduled"]},"created_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/ApiBadRequest"},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"422":{"description":"A required field is missing, the inbox, template or recipient list was not found, the inbox is not WhatsApp, the variables don't match the template, or `schedule_at` is invalid or in the past.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The campaign was saved but could not be queued, and has been marked `failed`. Create it again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```