broadcast.* events

Fires when a creator sends a Telegram message to a segment of their members. Two events bracket every send: one as it starts, carrying the audience and how many members it will reach, and one when it finishes, carrying the delivered and failed tallies.

Both fire for broadcasts started anywhere — the dashboard, the Telegram bot, the REST API, a Zap or an n8n workflow. They are emitted by the sending job rather than by each entry point, so a broadcast triggered by automation is indistinguishable from one typed into the dashboard.

Events

broadcast.queued

A broadcast started sending, with its audience and recipient count.

broadcast.completed

The send finished, with delivered and failed tallies.

Audience segments

The audience field on both events is one of:

Value	Reaches
`all`	Every member with a linked chat
`customer`	Paying members
`trialing`	Members on a trial
`lead`	Members who started the bot but never subscribed
`churned`	Members whose subscription ended
`expiring_soon`	Members whose access lapses inside `expiring_within_days`
`cancelled_still_active`	Members who turned renewal off but have time left
`paused`	Members whose subscription is paused rather than ended
`trialing_cardless`	Members on a trial with no card on file
`all_pass_holders`	Holders of any currently-active pass window
`all_pass_holders_not_in_queue`	As above, but only those who have not tapped their invite yet
`pass_holders`	Holders of one named window
`pass_holders_not_in_queue`	Holders of one named window who have not queued

The two single-window pass segments carry a pass_window_id; every other segment reports pass_window_id: null. The four pass segments require the passes capability — a project whose plan no longer includes it cannot address them, and the API refuses the send rather than silently reaching nobody.

expiring_soon reports the horizon it used in expiring_within_days; every other segment reports null. Note that an auto-renewing subscription is never in this segment: a subscription's end date is rewritten on every renewal, so a date alone would describe the next invoice rather than an expiry.

Narrowing by plan

Any segment except lead and the four pass segments can be narrowed to a single plan, and both events then carry that plan in data.plan_id. It composes with the segment rather than replacing it — customer plus a plan means people paying for that plan right now, churned plus a plan means people who held it and left. Segments that cannot be narrowed always report plan_id: null.

This matters for a consumer that counts sends per audience: two broadcast.completed events can now carry the same audience and describe different populations, and plan_id is what tells them apart.

A member is only ever a recipient if they have a chat on that project's bot. Members with no chat, or whose chat belongs to a different bot, are excluded — which is why a recipient count is often well below a project's total membership.

The message body is never in the payload

Neither event carries the text that was sent. Broadcasts are not stored — a broadcast is a send, not a record — and a body is arbitrary creator content up to 4096 characters. Repeating it on every subscribed endpoint would hand it to integrations that only need to know a send happened.

If you need the copy alongside the outcome, send the broadcast through the REST API or a Zap and correlate on project_id and created_at.

What does not emit

A broadcast that is refused never emits either event, because nothing was sent:

the project has no connected bot
the audience is unknown
the body is empty once reduced to Telegram's HTML subset
a pass segment was requested by a project whose plan no longer includes passes
a single-window segment was requested with no window

The REST API and MCP tool reject all of these up front with a validation error. The dashboard and bot paths log and abort.

Required abilities

Tokens subscribing to broadcast.* events must carry broadcast:send. There is no separate read ability: knowing that a broadcast went out, to whom and how many, is the same privilege as being able to send one.