curl --request POST \
  --url https://messenger-public-api.cogfy.com/broadcasts \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "<string>",
  "title": "<string>",
  "status": "<string>",
  "scheduleDate": "2023-11-07T05:31:56Z",
  "batchSize": 0,
  "batchInterval": 0,
  "allowedSendTimeStart": "<string>",
  "allowedSendTimeEnd": "<string>",
  "allowedSendTimeTimezone": "<string>",
  "createDate": "2023-11-07T05:31:56Z",
  "processedContacts": 0,
  "totalBatches": 0
}

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

curl --request POST \
  --url https://messenger-public-api.cogfy.com/broadcasts \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "<string>",
  "title": "<string>",
  "status": "<string>",
  "scheduleDate": "2023-11-07T05:31:56Z",
  "batchSize": 0,
  "batchInterval": 0,
  "allowedSendTimeStart": "<string>",
  "allowedSendTimeEnd": "<string>",
  "allowedSendTimeTimezone": "<string>",
  "createDate": "2023-11-07T05:31:56Z",
  "processedContacts": 0,
  "totalBatches": 0
}

Authorizations

api-key

string

header

required

Body

application/json

title

string

required

Broadcast title, used for identification

Maximum string length: 100

phoneNumber

string

required

Id or phone number of the sender phone number

Minimum string length: 1

type

enum<string>

default:text

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

Available options:

text,

template

content

string

Message content. Required when type is text

Maximum string length: 1024

template

object

Template specification. Required when type is template

Show child attributes

contactsQuery

object

Filter for contacts already registered in the workspace. Mutually exclusive with contacts

Show child attributes

contacts

object[]

Explicit list of recipients. Mutually exclusive with contactsQuery

Required array length: 1 - 10000 elements

Show child attributes

scheduleDate

string

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

batchSize

integer

default:5

Number of messages sent per batch

Required range: 1 <= x <= 1000

batchInterval

integer

default:1

Interval in minutes between batches

Required range: 1 <= x <= 9007199254740991

allowedSendTimeStart

string

default:08:00

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

Pattern: ^([01]\d|2[0-3]):[0-5]\d$

allowedSendTimeEnd

string

default:18:00

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

Pattern: ^([01]\d|2[0-3]):[0-5]\d$

allowedSendTimeTimezone

string

default:America/Sao_Paulo

IANA timezone used to evaluate the allowed send time window

whatsappApi

enum<string>

default:cloud_api

WhatsApp API used to deliver the messages

Available options:

cloud_api,

mm_api

Response

Broadcast created successfully

string<uuid>

required

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

string

required

title

string | null

required

status

string | null

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> | null

required

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))$

batchSize

integer | null

required

Required range: -9007199254740991 <= x <= 9007199254740991

batchInterval

integer | null

required

Required range: -9007199254740991 <= x <= 9007199254740991

allowedSendTimeStart

string | null

required

allowedSendTimeEnd

string | null

required

allowedSendTimeTimezone

string | null

required

createDate

string<date-time>

required

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

integer | null

Number of contacts processed. Only returned when creating from an explicit contacts list

Required range: -9007199254740991 <= x <= 9007199254740991

totalBatches

integer | null

Number of batches the contacts were split into. Only returned when creating from an explicit contacts list

Required range: -9007199254740991 <= x <= 9007199254740991

Getting started

Endpoints

Create a new broadcast

Authorizations

Body

Response