---
title: "Create a new broadcast"
method: POST
path: "/broadcasts"
tags: ["Broadcasts"]
---

# Create a new broadcast

`POST /broadcasts`

Creates a broadcast for a phone number of the workspace.

**Message type (`type`)** and **recipient source** are independent choices — any combination of them is valid:

- `type: text` sends a free-form text message. It only reaches contacts with an open service window (i.e. that messaged the business recently).
- `type: template` sends an approved WhatsApp template message. Required to reach recipients that never messaged the business or whose service window is closed.

**Recipient source** — exactly one of the following must be provided, regardless of `type`:

- `contactsQuery`: filters contacts already registered in the workspace by tag. The broadcast is created with status `pending` and the recipients are resolved asynchronously; once resolved it moves to `ready` (or `scheduled`).
- `contacts`: an explicit list of recipients sent in the request body, which does not require the contacts to be registered. The broadcast messages are created synchronously and the broadcast is returned already in status `ready` (or `scheduled`, when `scheduleDate` is provided).

A broadcast in status `ready` is only sent after calling `POST /broadcasts/{broadcastId}/send`. A broadcast in status `scheduled` is sent automatically at `scheduleDate`.

## Request body

- object
  - `type` 'text' | 'template' — `text` sends a free-form text message. `template` sends an approved WhatsApp template message
  - `title` string, required — Broadcast title, used for identification
  - `content` string — Message content. Required when `type` is `text`
  - `template` object — Template specification. Required when `type` is `template`
    - `whatsAppId` string, required — Id of the approved WhatsApp template message
  - `phoneNumber` string, required — Id or phone number of the sender phone number
  - `contactsQuery` object — Filter for contacts already registered in the workspace. Mutually exclusive with `contacts`
    - `tags` object[] — Recipients are the contacts that have all the given tags
      - `id` string, uuid
      - `name` string
  - `contacts` object[] — Explicit list of recipients. Mutually exclusive with `contactsQuery`
    - `phoneNumber` string, required — Recipient WhatsApp number, digits only, including country code
    - `variables` object — Values for the named parameters of the WhatsApp template, keyed by parameter name
  - `scheduleDate` string — When provided, the broadcast is scheduled to be sent automatically at this date. Must be in the future
  - `batchSize` integer — Number of messages sent per batch
  - `batchInterval` integer — Interval in minutes between batches
  - `allowedSendTimeStart` string — Start of the time window in which batches may be sent (HH:MM)
  - `allowedSendTimeEnd` string — End of the time window in which batches may be sent (HH:MM)
  - `allowedSendTimeTimezone` string — IANA timezone used to evaluate the allowed send time window
  - `whatsappApi` 'cloud_api' | 'mm_api' — WhatsApp API used to deliver the messages

## Response `201`

Broadcast created successfully

- object
  - `id` string, uuid, required
  - `type` string, required
  - `title` string, nullable, required
  - `status` string, nullable, required — `pending` when the recipients still have to be resolved from `contactsQuery`, `ready` when the broadcast is ready to be sent and `scheduled` when it will be sent at `scheduleDate`
  - `scheduleDate` string, date-time, nullable, required
  - `batchSize` integer, nullable, required
  - `batchInterval` integer, nullable, required
  - `allowedSendTimeStart` string, nullable, required
  - `allowedSendTimeEnd` string, nullable, required
  - `allowedSendTimeTimezone` string, nullable, required
  - `createDate` string, date-time, required
  - `processedContacts` integer, nullable — Number of contacts processed. Only returned when creating from an explicit contacts list
  - `totalBatches` integer, nullable — Number of batches the contacts were split into. Only returned when creating from an explicit contacts list

## Other responses

- `400` — Bad request, invalid input data
- `401` — Unauthorized
- `404` — Phone number not found

---

[API](https://skmtc.net/indigohive/apis/cogfy-messenger-public-api.md) · [All operations](https://skmtc.net/indigohive/apis/cogfy-messenger-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/indigohive/cogfy-messenger-public-api/versions/30bd33ee45c9/schema)