Broadcasts
14 tools

Broadcasts tools

Create broadcasts, follow delivery and pause, resume, cancel or retry them.

Badges:Read onlyWrites dataSends to WhatsAppDestructive
list_broadcasts#

List broadcasts

Read only

WhatsApp broadcasts in this workspace, newest first, with status and delivery counts. For why one failed use get_broadcast_stats.

Parameters (4)›
  • status

    "queued" | "scheduled" | "running" | "paused" | "completed" | "failed" | "cancelled"

    No extra notes.
  • cursor

    string

    next_cursor from the previous page; omit for the first page. Keep the other filters the same; the page size stays as on the first page.
  • page_size

    integer

    Rows per page, 1-100. Default 20.Default 20
  • response_format

    "concise" | "detailed"

    concise returns the fields a person reads; detailed adds ids and raw fields for follow-up calls.Default "concise"
get_broadcast#

Get one broadcast

Read only

One WhatsApp broadcast: template or text, schedule, counts, error and retry history. For failure reasons use get_broadcast_stats.

Parameters (1)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
get_broadcast_stats#

Get broadcast delivery and failure stats

Read only

Delivery counts of one WhatsApp broadcast and every failure grouped by Meta error code, each with a plain label, a class (transient, blocked, permanent, unknown) and whether a retry can work. retryable_error_codes lists the codes to pass to retry_broadcast.

Parameters (1)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
list_broadcast_recipients#

List a broadcast's recipients

Read only

Per-recipient rows of one WhatsApp broadcast: phone, status, error and skip reason; detailed adds attempts and sent/delivered/read times. Filter by status or error code (unknown = failed without a code).

Parameters (7)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
  • status

    "pending" | "sent" | "delivered" | "read" | "failed" | "skipped"

    No extra notes.
  • error_code

    string

    A Meta error code from get_broadcast_stats, or unknown.
  • query

    string

    Phone substring.
  • cursor

    string

    next_cursor from the previous page; omit for the first page. Keep the other filters the same; the page size stays as on the first page.
  • page_size

    integer

    Rows per page, 1-100. Default 20.Default 20
  • response_format

    "concise" | "detailed"

    concise returns the fields a person reads; detailed adds ids and raw fields for follow-up calls.Default "concise"
create_broadcast#

Create a broadcast to many people

Sends to WhatsApp

Creates and queues a WhatsApp broadcast to many people. Recipients come from recipients (phones with their own variables) or tag_ids (subscribed contacts with any of those tags, at most 500). Check a template's placeholders with get_template first. Text and media broadcasts reach only people who messaged in the last 24 hours. For one person use send_template_message. Reaches real phones and is billed.

Parameters (12)›
  • namerequired

    string

    Broadcast name shown in the dashboard.
  • message_type

    "template" | "text" | "media"

    No extra notes.Default "template"
  • template_name

    string

    For message_type template: an APPROVED template's name.
  • language_code

    string

    For message_type template: the template's language code, e.g. en_US.
  • text

    string

    For message_type text: the message text.
  • media_asset_id

    string

    For message_type media: a media_asset_id from list_media.
  • recipients

    object[]

    No extra notes.
  • tag_ids

    string[]

    Send to subscribed contacts with any of these tags.
  • variables

    string[]

    Body values used for every recipient.
  • variables_from_contact

    string[]

    Per-contact body values, in placeholder order: first_name, last_name, phone or a custom attribute key. Tag sends only.
  • scheduled_at

    string

    ISO 8601 with offset; omit to send now.
  • rate_per_second

    integer

    Messages per second, 1-70.
pause_broadcast#

Pause a broadcast

Writes data

Pauses a running, queued or scheduled WhatsApp broadcast. Continue with resume_broadcast; stop for good with cancel_broadcast.

Parameters (1)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
resume_broadcast#

Resume a paused broadcast

Sends to WhatsApp

Continues a paused WhatsApp broadcast from where it stopped. Reaches real phones and is billed.

Parameters (1)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
retry_broadcast#

Retry failed recipients by error code

Sends to WhatsApp

Re-sends a finished WhatsApp broadcast to recipients that failed with the given Meta error codes (unknown = no code). Take codes from get_broadcast_stats; permanent ones such as 131026 (number not on WhatsApp) never succeed. Schedule it later for transient limits. Billed.

Parameters (3)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
  • error_codesrequired

    string[]

    Codes from retryable_error_codes of get_broadcast_stats.
  • scheduled_at

    string

    ISO 8601 with offset; omit to retry now.
cancel_broadcast#

Cancel a broadcast

Destructive

Stops a WhatsApp broadcast for good; pending recipients are marked cancelled. Cannot be undone; to stop for now use pause_broadcast. Owner or admin keys only.

Parameters (1)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
update_broadcast_retry#

Move a scheduled resend

Sends to WhatsApp

Moves a WhatsApp broadcast's scheduled resend of failed recipients (set by retry_broadcast with scheduled_at) to another future time. Fails when no scheduled resend is waiting. Billed when it runs.

Parameters (2)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
  • scheduled_atrequired

    string

    New time, ISO 8601 with offset, in the future.
cancel_broadcast_retry#

Cancel a scheduled resend

Writes data

Cancels a WhatsApp broadcast's scheduled resend before it runs; those recipients stay failed in the report and the broadcast itself is not cancelled. Only a resend of one error code can be cancelled.

Parameters (1)›
  • broadcast_idrequired

    string

    A broadcast_id from list_broadcasts.
get_best_send_time#

Best hour to send

Read only

The hour of day when this workspace's contacts read the most WhatsApp broadcast messages, from the read receipts of its broadcasts in the last 30 days (at most 20). found: false when there are too few reads to tell. The hour is in timezone, else the workspace's.

Parameters (1)›
  • timezone

    string

    IANA timezone for the hour, e.g. Asia/Kolkata. Defaults to the workspace's.
get_error_meaning#

Explain a WhatsApp failure code

Read only

What a WhatsApp failure code means and what fixes it, in the dashboard's words.

Parameters (1)›
  • coderequired

    string

    The failure code, e.g. 131049.
get_broadcast_failures#

Why messages failed, and the fix

Read only

Why WhatsApp messages failed, one row per reason: plain words, what the customer can do, a link, and the fix (fix) to run once the user agrees. Pick the broadcast by id, by words from its name, or by a number a message went to; with none, the latest broadcast with failures in the last 7 days. error adds what that error means (asked_error), even when no broadcast is found.

Parameters (4)›
  • broadcast_id

    string

    A broadcast_id from list_broadcasts.
  • name

    string

    Words from the broadcast's name, e.g. diwali.
  • phone

    string

    A number a failed message went to, with country code.
  • error

    string

    The error the customer saw: a code like 131049 or its words.