Sign in

v8

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01390206.4 KB
Broadcasts

Create a new broadcast

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.

post/broadcasts

Request body

type'text' | 'template'

text sends a free-form text message. template sends an approved WhatsApp template message

titlestring required

Broadcast title, used for identification

contentstring

Message content. Required when type is text

phoneNumberstring required

Id or phone number of the sender phone number

scheduleDatestring

When provided, the broadcast is scheduled to be sent automatically at this date. Must be in the future

batchSizeinteger

Number of messages sent per batch

batchIntervalinteger

Interval in minutes between batches

allowedSendTimeStartstring

Start of the time window in which batches may be sent (HH:MM)

allowedSendTimeEndstring

End of the time window in which batches may be sent (HH:MM)

allowedSendTimeTimezonestring

IANA timezone used to evaluate the allowed send time window

whatsappApi'cloud_api' | 'mm_api'

WhatsApp API used to deliver the messages

Response

Broadcast created successfully

idstring uuid required
typestring required
titlestring nullable required
statusstring 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

scheduleDatestring date-time nullable required
batchSizeinteger nullable required
batchIntervalinteger nullable required
allowedSendTimeStartstring nullable required
allowedSendTimeEndstring nullable required
allowedSendTimeTimezonestring nullable required
createDatestring date-time required