> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Broadcasts: send a WhatsApp message to many customers

> Send one approved WhatsApp template to many customers, now or at a time you pick, skip those who did not agree to it, and follow each message.

A shop needs to tell everyone who pre-ordered its Ember jacket that it ships two weeks late. That is a broadcast: one approved `marketing` or `utility` [message template](https://heythere.io/docs/concepts/message-templates), sent from one of the workspace's WhatsApp numbers to its [contacts](https://heythere.io/docs/concepts/contacts).

An optional [audience](https://heythere.io/docs/concepts/audiences) narrows those contacts with conditions on `contact.<field>`, such as the customers whose `preorder` is `ember_jacket`. Each value of the template can read the contact, so `Hello {{contact.first_name}}` greets each customer by name.

## How does a broadcast go out?

A member writes it as a `draft`, which they can still change or delete. An administrator sends it. Heythere picks the recipients at that moment, and the broadcast stays `sending` until each one is handled, then becomes `completed`. Cancel it while it is `sending`, and the recipients not messaged yet end `not_sent`.

Each message lands in the customer's [conversation](https://heythere.io/docs/concepts/conversations), which it opens if they never wrote to that number. Their reply goes to the run waiting for it, or else to the number's [automation](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-).

## Can a broadcast go out later?

To land the news on Monday morning, an administrator schedules the draft: it stays `scheduled`, with that time on its number's card in the [workspace map](https://heythere.io/docs/concepts/organizations-and-workspaces#what-does-a-workspace-s-map-show-), then sends by itself. Until then they can move it, send it now, or unschedule it to edit it. If its template stops being sendable first, it sends nothing and returns to a draft whose `missedSchedule` says why.

## Which contacts does a broadcast skip?

A customer who never agreed to marketing messages does not get the jacket news. `listBroadcastRecipients` gives each recipient's `status` and, when skipped, its `skipReason`:

- `marketing_consent_missing`: the template is `marketing` and the contact's `marketing` [consent](https://heythere.io/docs/concepts/contacts#what-does-a-contact-consent-to-) is not `granted`.
- `utility_consent_withdrawn`: the template is `utility` and the contact withdrew its `utility` consent.
- `template_value_missing`: a value of the template reads a field the contact does not hold.

Meta can change a template's category, so Heythere checks consent again just before each message, against the category the template has then. A recipient ends `failed`, with a `failureReason`, when its message never reaches them or the template stops being sendable first.

## Why does a broadcast take a while?

Meta limits how many contacts a number can message each day. When the shop's number reaches that limit, the broadcast pauses, stays `sending`, and goes on once Meta allows more messages.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `createBroadcast`: Create a broadcast draft. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts`
- `listWorkspaceBroadcasts`: List workspace broadcasts. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts`
- `getBroadcast`: Get a broadcast. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}`
- `updateBroadcast`: Update a broadcast draft. `PATCH /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}`
- `deleteBroadcast`: Delete a broadcast draft. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}`
- `sendBroadcast`: Send a broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/send`
- `scheduleBroadcast`: Schedule a broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/schedule`
- `unscheduleBroadcast`: Unschedule a broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/unschedule`
- `cancelBroadcast`: Cancel a sending broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/cancel`
- `listBroadcastRecipients`: List a broadcast's recipients. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/recipients`
