Messaging

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, 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 is marketing and the contact's marketing consent 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 describes their parameters, payloads, and errors.

  • POST

    createBroadcast

    Create a broadcast draft

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts
  • GET

    listWorkspaceBroadcasts

    List workspace broadcasts

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts
  • GET

    getBroadcast

    Get a broadcast

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}
  • PATCH

    updateBroadcast

    Update a broadcast draft

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}
  • DELETE

    deleteBroadcast

    Delete a broadcast draft

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}
  • POST

    sendBroadcast

    Send a broadcast

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/send
  • POST

    scheduleBroadcast

    Schedule a broadcast

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/schedule
  • POST

    unscheduleBroadcast

    Unschedule a broadcast

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/unschedule
  • POST

    cancelBroadcast

    Cancel a sending broadcast

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/cancel
  • GET

    listBroadcastRecipients

    List a broadcast's recipients

    /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/recipients