broadcast.queued

A broadcast started sending, carrying the audience it resolved to and how many members it will reach.

When this fires

A broadcast began sending. The audience has been resolved to a concrete set of recipients and the first message is on its way.

This fires for broadcasts started anywhere — the dashboard, the Telegram bot, the REST API, a Zap or an n8n workflow. The event is emitted by the sending job itself rather than by each entry point, so every route announces a broadcast identically.

This is the start, not the outcome. Delivery runs at roughly 28 messages a second to stay inside Telegram's rate limit, so a large broadcast is still sending long after this arrives. Subscribe to broadcast.completed for the tallies.

Required ability

broadcast:send — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "broadcast.queued",
  "created_at": "2026-09-01T10:30:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "audience": "customer",
    "pass_window_id": null,
    "plan_id": null,
    "expiring_within_days": null,
    "recipient_estimate": 128
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `broadcast.queued` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID	Project this event belongs to.
`data.project_id`	string UUID	Same project, repeated inside `data` so a consumer reading only the data object is self-sufficient.
`data.audience`	string	The segment addressed. One of the values in Audience segments.
`data.pass_window_id`	string UUID / null	Set only for the two single-window pass segments; `null` for every other audience.
`data.plan_id`	string UUID / null	The plan the segment was narrowed to, if any. `null` when unnarrowed or when the segment cannot be narrowed.
`data.expiring_within_days`	integer / null	The horizon used, set only for `expiring_soon`; `null` for every other audience.
`data.recipient_estimate`	integer	How many members the resolved query matched at send time.

Caveats

recipient_estimate is the count at the moment sending began. Someone who joins mid-send is not included, and someone who blocks the bot mid-send is still counted here but will appear in failed on completion.
A member is only a recipient if they have a linked chat on that project's bot. A member with no chat, or one attached to a different bot, is silently excluded — which is why the estimate can be far lower than the project's member count.
The message body is not in the payload. Broadcasts are not persisted, and a body can be up to 4096 characters of arbitrary creator content; repeating it on every subscribed endpoint would leak it to integrations that only need to know a send happened.
If the audience resolves to zero recipients this still fires, immediately followed by broadcast.completed with sent: 0.

broadcast.completed — the outcome, with sent and failed tallies.
Broadcast events overview — back to family overview.
Broadcasts API — send one programmatically.