Broadcasting¶

Need to tell 4,000 users about a sale? Bot.broadcast() starts a mass-messaging job that runs a command (or sends a Telegram method) for every matching user — chunking, queues, rate limits, and flood protection handled in the background.

You kick it off. The platform delivers. You go get coffee.

What is broadcasting?¶

A distributed job that targets many users at once. Two ways to send:

Each target user gets a simulated private-chat context — inside your broadcast command, user and chat reflect that recipient.

How to use it¶

Quick start¶

let job = await Bot.broadcast({
  command: "send_promo",
  filters: { chatType: "private" }
})

Bot.sendMessage("Broadcast started! ID: " + job.broadcastId + ", targets: " + job.totalTargetChats)

Returns:

{
  broadcastId: "uuid-string",
  totalTargetChats: 4523,
  totalBatches: 10
}

Using a command¶

Your command runs once per user with that user's context:

await Bot.broadcast({
  command: "weekly_digest",
  filters: { chatType: "private", premiumOnly: true }
})

Inside /weekly_digest, globals like user and chat reflect each target user.

Using a Telegram method directly¶

Skip a command — send raw API calls:

await Bot.broadcast({
  method: "sendMessage",
  body: { text: "System maintenance tonight at 2 AM." },
  filters: { chatType: "all" }
})

Try it — copy-paste examples¶

Simple promo to all private users¶

let job = await Bot.broadcast({
  command: "promo_message",
  filters: { chatType: "private" }
})

Bot.sendMessage("Sending to " + job.totalTargetChats + " users.")

Premium groups only¶

await Bot.broadcast({
  command: "vip_alert",
  filters: { chatType: "group", premiumOnly: true }
})

Lifecycle hooks¶

Run commands when the job starts or finishes. Hook commands receive job data in options:

await Bot.broadcast({
  command: "newsletter",
  filters: { chatType: "private" },
  on_create: "broadcast_started",
  on_complete: "broadcast_finished"
})

Check progress and stop if needed¶

let stats = await Bot.getBroadcastStats(job.broadcastId)
Bot.sendMessage("Progress: " + stats.processed_count + "/" + stats.total_chats)

await Bot.stopBroadcast(job.broadcastId)
// { success: true, message: "Broadcast stopped successfully" }

Filters¶

Blocked users are always excluded. No exceptions. They opted out.

Speed plans¶

Override explicitly: plan: "fast" or plan: "slow".

Managing broadcasts¶

Bot.stopBroadcast(broadcastId)¶

Stop a running job immediately.

Bot.getBroadcastStats(broadcastId)¶

Real-time job record:

Bot.listBroadcasts(status?)¶

let active = await Bot.listBroadcasts()
let all = await Bot.listBroadcasts(["processing", "queued", "pending", "completed"])

Default filter: ["processing", "queued", "pending"].

Broadcast execution limits¶

Commands triggered by broadcast run in a restricted context — designed to keep batches fast and reliable:

Available: Bot, Api, db, and globals (user, chat, options, etc.).

Design broadcast commands to be fast and self-contained — send a message, update a counter, done.

Auto-termination rules¶

Broadcasts stop automatically when things go wrong:

Method reference¶

Bot.broadcast(params)¶

Important notes¶

• Bot.broadcast() must be awaited — it returns a Promise
• At least one of command or body is required
• The current bot ID is set automatically
• To query users without broadcasting, use Bot.getUsers