Broadcasts

List the broadcasts in this organization, newest first. MARKETING broadcasts are bulk sends to segments or all contacts; TRANSACTIONAL broadcasts are single-recipient sends fired by triggers or the API.

Read a single broadcast in full: status, schedule, audience (segments or all contacts), channel templates and delivery counters (sent, delivered, opened, failed).

Create a broadcast as a DRAFT: a bulk marketing campaign (e.g. a WhatsApp template blast) to segments or all contacts, or a transactional single-recipient send.

Update a broadcast name, schedule time or audience. Audience and schedule can only change while the broadcast is editable (marketing: DRAFT, CANCELLED or FAILED; transactional: DRAFT, ACTIVE or PAUSED).

Copy a broadcast including its segments and channel templates. The copy is created as a DRAFT and does not send anything.

Permanently delete a broadcast and its delivery history. Marketing broadcasts cannot be deleted while scheduled or sending; transactional ones must be paused first.

Move a broadcast through its lifecycle: 'schedule' queues a MARKETING broadcast for its full audience (the real mass send — immediately, or at its scheduled time; requires a channel template); 'cancel' stops a scheduled/sending marketing broadcast and returns it to draft; 'activate' turns a TRANSACTIONAL broadcast on; 'pause' suspends it.

Attach or update the channel message of a broadcast — what actually gets sent.

Add specific contacts to a MARKETING broadcast audience (on top of segments / send-to-all), e.g. a list imported from a file or filtered in code. Requires an editable broadcast with at least one channel template.

Preview how many recipients a MARKETING broadcast will reach per channel, based on its current audience — check this before scheduling the send.

Retry the failed recipients of a broadcast (up to 1000 per call). Omit recipient_ids to retry all failed ones.

Remove pending (not yet sent) recipients from an editable MARKETING broadcast. Omit contact_ids to remove all pending.

List the personalization fields ({{variable}} placeholders) of a broadcast with their default values.

Create or update a personalization field ({{variable}}) on a broadcast with its default value. Reserved keys like first_name/last_name resolve from the contact; other keys use the default unless a per-recipient entry overrides it.

Set per-recipient personalization values on a MARKETING broadcast. Pass one entry per recipient, identified by email, phone or user_id. Pass dry_run to preview which recipients would match without writing.

Queue a MARKETING broadcast for delivery to its full audience. Sends immediately when the broadcast has no scheduled time, otherwise waits for it. This is the real mass send: confirm with the user before calling it. Requires DRAFT, CANCELLED or FAILED status and at least one channel template.

Cancel a MARKETING broadcast in SCHEDULED or SENDING status: it returns to DRAFT and can be edited and re-scheduled. Recipients already sent stay sent.

Activate a TRANSACTIONAL broadcast so it accepts triggers and starts sending to individual recipients. Allowed from DRAFT or PAUSED; requires at least one channel template.

Pause an ACTIVE transactional broadcast. Triggers are rejected until it is activated again; configuration is preserved.

Send a test of a broadcast to a single email address or phone number so its content can be reviewed before the real send. Only works while the broadcast is testable (marketing: DRAFT, CANCELLED or FAILED; transactional: DRAFT, ACTIVE or PAUSED).

Aggregated delivery and engagement stats per broadcast: totals, delivery rate and open rate, optionally limited to a date range.

List individual broadcast deliveries with their status (sent, delivered, opened, failed, bounced). Answers "did we send X to this contact": filter by broadcast, by contact, or search by name, email or phone across all broadcasts.