Skip to main content
A broadcast sends one message — filled in for each person — to many people on one channel. Through the API it is the same broadcast the panel’s Broadcasts screen sends: OMNI checks every number, leaves out people who may not be messaged, sends at the channel’s pace, and shows it in the panel beside the ones your team started. Use a broadcast when everyone gets the same message on the same channel. To reach one person with a fallback to other channels, send a message with failover instead. You need a key with broadcasts:write to start and control broadcasts, and broadcasts:read to follow them (see Keys and scopes).

​
Starting one

POST /v1/broadcasts takes the channel, a name, the channel’s content, and the audience:
It answers at once, preparing; the audience is read and checked on OMNI’s side, however large it is. Send an Idempotency-Key header so a retried request starts it only once.

​
What each channel sends

content is the channel’s own, with the same names messages with failover use. {{tags}} in it are filled for each person.

​
Who it goes to

Give one kind of audience:
  • recipients — up to 10,000 numbers, each with the values for its {{tags}}. The way to send what your own system has worked out per person.
  • contacts, segments and numbers — your saved contacts (up to 500 by id), whole segments (up to 50), and up to 500 more numbers. A contact’s name, number and fields fill the tags: {{name}}, {{msisdn}}, {{city}}…
  • audience — one of your saved audiences, with Customer data.
For more than 10,000 people with values of their own, save them as contacts first and send to their segment. A {{tag}} nothing in the audience can fill is refused before anything is sent — it is almost always a typo, and a blank would reach everyone.

​
Who is left out

Every number is checked the way the panel checks a broadcast:
  • Numbers that aren’t valid, and repeats, are skipped.
  • People who asked never to be contacted, or opted out, are skipped — of marketing when purpose is marketing (the default), of everything when they stopped everything.
  • On RCS, a number whose country has no route, or whose bot hasn’t approved the template, is skipped.
counts.skipped says how many; the rest are sent.

​
Following it

GET /v1/broadcasts/{broadcast_id} gives its status and counts — skipped, sent, delivered, failed, waiting — and its messages say how each one ended. GET /v1/broadcasts lists them all, the panel’s too. Rather than asking, subscribe a webhook endpoint to: Each carries the broadcast, as broadcast, in the shape GET answers. Each message also sends its own channel_message.* events, with the broadcast’s id in campaign.

​
Pausing, resuming and canceling

Asking for one at the wrong moment — pausing a finished broadcast, say — is refused with invalid_state (409), and the message says why.
An account sends a few broadcasts at a time; others wait their turn, queued. A broadcast’s messages are charged like any other send.