> ## Documentation Index > Fetch the complete documentation index at: https://docs.cogfy.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml POST /broadcasts openapi: 3.1.0 info: title: Cogfy Messenger Public API version: 1.0.0 description: API for interacting with the Cogfy Messenger platform servers: - url: https://messenger-public-api.cogfy.com description: Production server - url: http://localhost:3100 description: Local server security: - ApiKeyAuth: [] paths: /broadcasts: post: tags: - Broadcasts summary: Create a new broadcast description: >- 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`. requestBody: required: true content: application/json: schema: type: object properties: type: default: text description: >- `text` sends a free-form text message. `template` sends an approved WhatsApp template message type: string enum: - text - template title: type: string maxLength: 100 description: Broadcast title, used for identification content: description: Message content. Required when `type` is `text` type: string maxLength: 1024 template: description: Template specification. Required when `type` is `template` type: object properties: whatsAppId: type: string minLength: 1 description: Id of the approved WhatsApp template message required: - whatsAppId phoneNumber: type: string minLength: 1 description: Id or phone number of the sender phone number contactsQuery: description: >- Filter for contacts already registered in the workspace. Mutually exclusive with `contacts` type: object properties: tags: description: Recipients are the contacts that have all the given tags type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string contacts: description: >- Explicit list of recipients. Mutually exclusive with `contactsQuery` minItems: 1 maxItems: 10000 type: array items: type: object properties: phoneNumber: type: string minLength: 1 description: >- Recipient WhatsApp number, digits only, including country code variables: description: >- Values for the named parameters of the WhatsApp template, keyed by parameter name type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: boolean required: - phoneNumber scheduleDate: description: >- When provided, the broadcast is scheduled to be sent automatically at this date. Must be in the future type: string batchSize: default: 5 description: Number of messages sent per batch type: integer minimum: 1 maximum: 1000 batchInterval: default: 1 description: Interval in minutes between batches type: integer minimum: 1 maximum: 9007199254740991 allowedSendTimeStart: default: '08:00' description: >- Start of the time window in which batches may be sent (HH:MM) type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ allowedSendTimeEnd: default: '18:00' description: End of the time window in which batches may be sent (HH:MM) type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ allowedSendTimeTimezone: default: America/Sao_Paulo description: IANA timezone used to evaluate the allowed send time window type: string whatsappApi: default: cloud_api description: WhatsApp API used to deliver the messages type: string enum: - cloud_api - mm_api required: - title - phoneNumber examples: templateWithExplicitContacts: summary: Template broadcast for an explicit list of recipients value: type: template title: Appointment reminder template: whatsAppId: '1234567890' phoneNumber: '5511999998888' scheduleDate: '2026-10-30T13:00:00Z' contacts: - phoneNumber: '5599888887777' variables: NAME: John - phoneNumber: '5599888886666' variables: NAME: Mary textWithContactsQuery: summary: Text broadcast for tagged contacts value: type: text title: Weekly update content: Hello! phoneNumber: '5511999998888' contactsQuery: tags: - name: customers templateWithContactsQuery: summary: Template broadcast for tagged contacts value: type: template title: Promotional campaign template: whatsAppId: '1234567890' phoneNumber: '5511999998888' contactsQuery: tags: - name: leads responses: '201': description: Broadcast created successfully content: application/json: schema: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ type: type: string title: anyOf: - type: string - type: 'null' status: anyOf: - type: string - type: 'null' description: >- `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: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' batchSize: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' batchInterval: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' allowedSendTimeStart: anyOf: - type: string - type: 'null' allowedSendTimeEnd: anyOf: - type: string - type: 'null' allowedSendTimeTimezone: anyOf: - type: string - type: 'null' createDate: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ processedContacts: description: >- Number of contacts processed. Only returned when creating from an explicit contacts list anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' totalBatches: description: >- Number of batches the contacts were split into. Only returned when creating from an explicit contacts list anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' required: - id - type - title - status - scheduleDate - batchSize - batchInterval - allowedSendTimeStart - allowedSendTimeEnd - allowedSendTimeTimezone - createDate additionalProperties: false '400': description: Bad request, invalid input data '401': description: Unauthorized '404': description: Phone number not found components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: api-key ````