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, sent from one of the workspace's WhatsApp numbers to its contacts.
An optional audience 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, 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.
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, 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 ismarketingand the contact'smarketingconsent is notgranted.utility_consent_withdrawn: the template isutilityand the contact withdrew itsutilityconsent.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 describes their parameters, payloads, and errors.
- POST
createBroadcastCreate a broadcast draft
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts - GET
listWorkspaceBroadcastsList workspace broadcasts
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts - GET
getBroadcastGet a broadcast
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId} - PATCH
updateBroadcastUpdate a broadcast draft
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId} - DELETE
deleteBroadcastDelete a broadcast draft
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId} - POST
sendBroadcastSend a broadcast
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/send - POST
scheduleBroadcastSchedule a broadcast
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/schedule - POST
unscheduleBroadcastUnschedule a broadcast
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/unschedule - POST
cancelBroadcastCancel a sending broadcast
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/cancel - GET
listBroadcastRecipientsList a broadcast's recipients
/api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/recipients