Broadcasts

A broadcast sends one approved WhatsApp template to every contact in one or more segments, or retargets the recipients of an earlier broadcast based on what they did with it. Create and schedule broadcasts from your own systems, change or cancel them before they start, and read their delivery stats and per-recipient logs.

Conventions

Send your key in the x-api-key header and bodies as JSON with Content-Type: application/json. Requests without a valid key get 401 { "message": "Unauthorized" }; other errors look like { "error": "message" }. The workspace goes in the request (workspace: { "id" } in the body, or ?workspaceId= when listing). Lists are plain arrays, paged with page (default 1) and limit (default 10, max 100; higher values are reduced to 100): keep increasing page until you get fewer results than your limit. See REST API for your API host and key.

Endpoints

GET/v1/broadcastsList broadcasts POST/v1/broadcastsCreate and schedule a broadcast GET/v1/broadcasts/{id}Get a broadcast with its stats PUT/v1/broadcasts/{id}Update a broadcast that hasn't started DEL/v1/broadcasts/{id}Cancel and delete a broadcast that hasn't started GET/v1/broadcasts/{id}/logsPer-recipient results

How broadcasts run

Scheduling. A new broadcast has status PENDING and runs at scheduleDateTime. Leave scheduleDateTime out to send it straight away.
Changing or cancelling. You can update or delete a broadcast only while its status is PENDING and its scheduleDateTime is still in the future. A broadcast created without scheduleDateTime starts at once, so it can't be changed or deleted afterwards.
Audience. A contact broadcast goes to the contacts its segments select when it runs. A retarget broadcast goes to recipients of an earlier broadcast, filtered by retargetEngagementType.
Template. The template is looked up by its WhatsApp name and language in the broadcast's workspace. See the WhatsApp templates API to list them.

The broadcast object

Attributes

idstring

The broadcast id

namestring

The broadcast name

statusstring

PENDING until it starts. Other values include RUNNING, SENDING, MESSAGES QUEUED, COMPLETED, STOPPING and FAILED.

typestring

contact or retarget

segmentsobject[]

contact broadcasts: the segments, each { id, name }. Older broadcasts may have a single segment instead.

retargetBroadcast, retargetEngagementTypeobject, string

retarget broadcasts: the earlier broadcast ({ id, name }) and the engagement filter

scheduleDateTime, startedAt, completedAtstring

Lifecycle timestamps

templateobject

The template's WhatsApp name and language

headerMediaUrl, headerTextParameters, bodyTextParameters, buttonUrlParameters, locationParameters, flowParameters

The template values you set. See create.

processedStats, deliveryStatsobject

See the broadcast stats

workspaceobject

{ id, title }

createdAt, updatedAtstring

Timestamps

Fields with no value, including stats a new broadcast doesn't have yet, are left out of the response.

The broadcast object
{
  "id": "Bc6tY3pLq8",
  "name": "October offer",
  "status": "COMPLETED",
  "type": "contact",
  "segments": [
    { "id": "Sg4mN7qRt2", "name": "VIP customers, inactive 30 days" }
  ],
  "scheduleDateTime": "2026-10-20T14:00:00.000Z",
  "startedAt": "2026-10-20T14:00:02.000Z",
  "completedAt": "2026-10-20T14:06:45.000Z",
  "template": {
    "name": "october_offer",
    "language": "en_US"
  },
  "headerMediaUrl": "https://cdn.example.com/offers/october.jpg",
  "bodyTextParameters": ["{{contact.name}}", "20%"],
  "processedStats": {
    "totalCount": 1250,
    "successCount": 1238,
    "failureCount": 12
  },
  "deliveryStats": {
    "sentCount": 1238,
    "deliveredCount": 1201,
    "failedCount": 12,
    "readCount": 864,
    "repliedCount": 97
  },
  "workspace": {
    "id": "Wq3nT8vYp1",
    "title": "Downtown Studio"
  },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-20T14:06:45.000Z"
}

The broadcast stats

processedStats

totalCountinteger

Recipients picked

successCountinteger

Recipients queued successfully

failureCountinteger

Recipients that failed

deliveryStats

sentCountinteger

Sent on WhatsApp

deliveredCountinteger

Delivered

failedCountinteger

Failed

readCountinteger

Read

repliedCountinteger

Replied

The broadcast stats
{
  "processedStats": {
    "totalCount": 1250,
    "successCount": 1238,
    "failureCount": 12
  },
  "deliveryStats": {
    "sentCount": 1238,
    "deliveredCount": 1201,
    "failedCount": 12,
    "readCount": 864,
    "repliedCount": 97
  }
}

The broadcast log entry

Attributes

broadcastobject

{ id, name }

recepientNamestring

The contact's name. Note the spelling: that is the field name the API returns.

countryCode, phonestring

The contact's number split into country code (with +) and national number

statusstring

The message status, when there is one

errorstring

Why the message failed, when it did

replystring

The contact's reply, when they replied

createdAt, updatedAtstring

Timestamps

The broadcast log entry
{
  "broadcast": { "id": "Bc6tY3pLq8", "name": "October offer" },
  "recepientName": "Maria Lopez",
  "countryCode": "+1",
  "phone": "2025550188",
  "status": "read",
  "reply": "Yes, please book me in",
  "createdAt": "2026-10-20T14:00:05.000Z",
  "updatedAt": "2026-10-20T14:21:40.000Z"
}

List broadcasts

GET/v1/broadcasts

Query parameters

workspaceIdstring

Only broadcasts in this workspace. Must be a workspace in your account.

searchTextstring

Matches part of the broadcast name. Not case sensitive.

startDatestring

Only broadcasts scheduled on or after this day, as YYYY-MM-DD, for example 2026-10-01. Days follow your account's time zone.

endDatestring

Only broadcasts scheduled on or before this day, as YYYY-MM-DD, for example 2026-10-31

pageintegerdefault 1

limitintegerdefault 10

Max 100. Higher values are reduced to 100.

200 OK: a JSON array of broadcasts, latest scheduleDateTime first. When it has fewer than limit items, it's the last page. This list doesn't filter out broadcasts you have deleted.

Errors

Status	Body	When
`404`	`{ "error": "Invalid workspaceId" }`	`workspaceId` isn't in your account
`500`	`{ "error": "Could not retrieve Broadcasts" }`	The request could not be completed. Retry.

Request
curl "https://api.whauto.chat/v1/broadcasts?workspaceId=Wq3nT8vYp1&startDate=2026-10-01&endDate=2026-10-31&limit=50" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
[
  {
    "id": "Bc6tY3pLq8",
    "name": "October offer",
    "status": "COMPLETED",
    "type": "contact",
    "segments": [{ "id": "Sg4mN7qRt2", "name": "VIP customers, inactive 30 days" }],
    "scheduleDateTime": "2026-10-20T14:00:00.000Z",
    "template": { "name": "october_offer", "language": "en_US" },
    "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
    "createdAt": "2026-10-14T09:30:00.000Z",
    "updatedAt": "2026-10-20T14:06:45.000Z"
  }
]

Create a broadcast

POST/v1/broadcasts

Creates a broadcast with status PENDING. See how broadcasts run.

Body parameters

namestringrequired

The broadcast name

typestringrequired

contact to send to segments, or retarget to follow up an earlier broadcast

workspaceobjectrequired

The broadcast's workspace

templateobjectrequired

The approved WhatsApp template

segmentsobject[]for contact

At least one segment, as [{ "id": "..." }]. Every segment must belong to the same workspace and not be deleted.

retargetBroadcastobjectfor retarget

The earlier broadcast

retargetEngagementTypestringfor retarget

Who to send to: sent, delivered, read, replied, not-replied or failed

scheduleDateTimestring

When to send, as an ISO 8601 date and time, for example 2026-10-20T14:00:00Z. Leave it out to send now.

headerMediaUrlstring

Public URL of the header image, video or document, for templates with a media header

headerTextParametersstring[]

Values for the header variables, in order

bodyTextParametersstring[]

Values for the body variables, in order

buttonUrlParametersstring[]

Values for dynamic URL buttons, in order

locationParametersobject

For templates with a location header

flowParametersobject

For templates with a WhatsApp Flow button

Text, button and flow values can include personalisation placeholders that are filled in for each recipient, such as {{contact.name}}, {{contact.phone}}, {{contact.id}}, {{contact.customFields.city}}, {{workspace.name}}, {{currentDate}} and {{currentTime}}.

200 OK: the new broadcast.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing, including `segments` for a `contact` broadcast or `retargetBroadcast` and `retargetEngagementType` for a `retarget` broadcast
`404`	`{ "error": "Location not found in the account." }`	The workspace isn't in your account
`404`	`{ "error": "Invalid whatsApp Template" }`	No template with that name and language in the workspace
`404`	`{ "error": "Invalid Retarget Broadcast" }`	The earlier broadcast isn't in the workspace
`404`	`{ "error": "Invalid Segments: ..." }`	Listed segments aren't in the workspace or were deleted
`500`	`{ "error": "Could not create Broadcast" }`	The request could not be completed. Retry.

Request
curl -X POST https://api.whauto.chat/v1/broadcasts \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October offer",
    "type": "contact",
    "workspace": { "id": "Wq3nT8vYp1" },
    "segments": [{ "id": "Sg4mN7qRt2" }],
    "template": { "name": "october_offer", "language": "en_US" },
    "scheduleDateTime": "2026-10-20T14:00:00Z",
    "headerMediaUrl": "https://cdn.example.com/offers/october.jpg",
    "bodyTextParameters": ["{{contact.name}}", "20%"]
  }'

Retarget everyone who read it but didn't reply
curl -X POST https://api.whauto.chat/v1/broadcasts \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October offer reminder",
    "type": "retarget",
    "workspace": { "id": "Wq3nT8vYp1" },
    "retargetBroadcast": { "id": "Bc6tY3pLq8" },
    "retargetEngagementType": "not-replied",
    "template": { "name": "october_offer_reminder", "language": "en_US" },
    "scheduleDateTime": "2026-10-23T14:00:00Z"
  }'

Response 200
{
  "id": "Bc6tY3pLq8",
  "name": "October offer",
  "status": "PENDING",
  "type": "contact",
  "segments": [{ "id": "Sg4mN7qRt2", "name": "VIP customers, inactive 30 days" }],
  "scheduleDateTime": "2026-10-20T14:00:00.000Z",
  "template": { "name": "october_offer", "language": "en_US" },
  "headerMediaUrl": "https://cdn.example.com/offers/october.jpg",
  "bodyTextParameters": ["{{contact.name}}", "20%"],
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Get a broadcast

GET/v1/broadcasts/{id}

Path parameters

idstringrequired

Broadcast id

200 OK: the broadcast, including its current stats.

Errors

Status	Body	When
`404`	`{ "error": "Broadcast not found" }`	The broadcast isn't in your account
`500`	`{ "error": "Could not retrieve Broadcast" }`	The request could not be completed. Retry.

Request
curl "https://api.whauto.chat/v1/broadcasts/Bc6tY3pLq8" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
{
  "id": "Bc6tY3pLq8",
  "name": "October offer",
  "status": "COMPLETED",
  "type": "contact",
  "segments": [{ "id": "Sg4mN7qRt2", "name": "VIP customers, inactive 30 days" }],
  "scheduleDateTime": "2026-10-20T14:00:00.000Z",
  "startedAt": "2026-10-20T14:00:02.000Z",
  "completedAt": "2026-10-20T14:06:45.000Z",
  "template": { "name": "october_offer", "language": "en_US" },
  "processedStats": { "totalCount": 1250, "successCount": 1238, "failureCount": 12 },
  "deliveryStats": { "sentCount": 1238, "deliveredCount": 1201, "failedCount": 12, "readCount": 864, "repliedCount": 97 },
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-20T14:06:45.000Z"
}

Update a broadcast

PUT/v1/broadcasts/{id}

Path parameters

idstringrequired

Broadcast id

Only for a broadcast that is still PENDING with a scheduleDateTime in the future. The body takes the same fields as create, with the same required fields, so send the whole broadcast each time. Send the broadcast's own workspace in workspace.id: the template and segments are looked up there.

A new scheduleDateTime reschedules the broadcast. Leave it out to keep the current time.
Changing type to retarget removes the segments. Changing it to contact removes the retarget settings.
If you leave out locationParameters or flowParameters, they are removed from the broadcast. If you leave out headerMediaUrl, headerTextParameters, bodyTextParameters or buttonUrlParameters, the current values are kept.

200 OK: the updated broadcast.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing (same rules as create)
`401`	`{ "error": "\"You cannot update this broadcast at this time" }`	The broadcast has started or its scheduled time has passed
`404`	`{ "error": "Workspace not found in the account" }`	The workspace isn't in your account
`404`	`{ "error": "Broadcast not found" }`	The broadcast isn't in your account
`404`	`{ "error": "Invalid whatsApp Template" }`	No template with that name and language in the workspace
`404`	`{ "error": "Invalid Retarget Broadcast" }`	The earlier broadcast isn't in the workspace
`404`	`{ "error": "Invalid Segments: ..." }`	Listed segments aren't in the workspace or were deleted
`500`	`{ "error": "Could not update Broadcast" }`	The request could not be completed. Retry.

Request
curl -X PUT https://api.whauto.chat/v1/broadcasts/Bc6tY3pLq8 \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October offer",
    "type": "contact",
    "workspace": { "id": "Wq3nT8vYp1" },
    "segments": [{ "id": "Sg4mN7qRt2" }],
    "template": { "name": "october_offer", "language": "en_US" },
    "scheduleDateTime": "2026-10-21T15:00:00Z",
    "bodyTextParameters": ["{{contact.name}}", "25%"]
  }'

Response 200
{
  "id": "Bc6tY3pLq8",
  "name": "October offer",
  "status": "PENDING",
  "type": "contact",
  "segments": [{ "id": "Sg4mN7qRt2", "name": "VIP customers, inactive 30 days" }],
  "scheduleDateTime": "2026-10-21T15:00:00.000Z",
  "template": { "name": "october_offer", "language": "en_US" },
  "headerMediaUrl": "https://cdn.example.com/offers/october.jpg",
  "bodyTextParameters": ["{{contact.name}}", "25%"],
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-15T10:12:00.000Z"
}

Delete a broadcast

DEL/v1/broadcasts/{id}

Path parameters

idstringrequired

Broadcast id

Cancels a broadcast that is still PENDING with a scheduleDateTime in the future, so it never sends.

Errors

Status	Body	When
`401`	`{ "error": "\"You cannot delete this broadcast at this time" }`	The broadcast has started or its scheduled time has passed
`404`	`{ "error": "Broadcast not found" }`	The broadcast isn't in your account
`500`	`{ "error": "Could not delete Broadcast" }`	The request could not be completed. Retry.

Request
curl -X DELETE https://api.whauto.chat/v1/broadcasts/Bc6tY3pLq8 \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
{ "success": true }

List broadcast logs

GET/v1/broadcasts/{id}/logs

Path parameters

idstringrequired

Broadcast id

Query parameters

pageintegerdefault 1

limitintegerdefault 10

Max 100. Higher values are reduced to 100.

200 OK: a JSON array with one log entry per recipient, newest first.

Errors

Status	Body	When
`404`	`{ "error": "Broadcast not found" }`	The broadcast isn't in your account
`500`	`{ "error": "Could not retrieve Broadcast Logs" }`	The request could not be completed. Retry.

Request
curl "https://api.whauto.chat/v1/broadcasts/Bc6tY3pLq8/logs?page=1&limit=100" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
[
  {
    "broadcast": { "id": "Bc6tY3pLq8", "name": "October offer" },
    "recepientName": "Maria Lopez",
    "countryCode": "+1",
    "phone": "2025550188",
    "status": "read",
    "reply": "Yes, please book me in",
    "createdAt": "2026-10-20T14:00:05.000Z",
    "updatedAt": "2026-10-20T14:21:40.000Z"
  },
  {
    "broadcast": { "id": "Bc6tY3pLq8", "name": "October offer" },
    "recepientName": "James Carter",
    "countryCode": "+44",
    "phone": "7700900123",
    "status": "failed",
    "error": "Message undeliverable",
    "createdAt": "2026-10-20T14:00:05.000Z",
    "updatedAt": "2026-10-20T14:00:09.000Z"
  }
]

How broadcasts run​

The broadcast object​

The broadcast stats​

The broadcast log entry​

List broadcasts​

Create a broadcast​

Get a broadcast​

Update a broadcast​

Delete a broadcast​

List broadcast logs​

How broadcasts run

The broadcast object

The broadcast stats

The broadcast log entry

List broadcasts

Create a broadcast

Get a broadcast

Update a broadcast

Delete a broadcast

List broadcast logs