@yaebal/broadcast

send a text message to many chats, one at a time, counting successes and failures. one blocked user never aborts the rest of the run.

install

shell

pnpm add @yaebal/broadcast

usage

broadcast is a plain async function — it takes bot.api directly and needs no middleware registration.

broadcast.ts

import { Bot } from "@yaebal/core";
import { broadcast } from "@yaebal/broadcast";

const bot = new Bot(token);

// send a plain message to every subscriber
const result = await broadcast(bot.api, subscriberIds, "hello everyone!");
console.log(result.sent, "sent,", result.failed, "failed");

api

export	kind	signature
`broadcast`	async function	`(api, chatIds, text, options?) => Promise<BroadcastResult>`
`BroadcastResult`	interface	`\{ sent: number; failed: number \}`
`BroadcastOptions`	interface	see options table below

parameters

parameter	type	description
`api`	`Api`	the bot's API object (`bot.api`).
`chatIds`	`Array<number \| string>`	the list of chat IDs to send to.
`text`	`string`	the message text.
`options.extra`	`Record<string, unknown>`	extra params merged into every `sendMessage` call (e.g. `parse_mode`, `reply_markup`). per-chat fields (`chat_id`, `text`) always win.
`options.onError`	`(chatId, error) => void`	called for each failed chat. the run continues regardless.

example with options

weekly-digest.ts

const result = await broadcast(
  bot.api,
  subscriberIds,
  "<b>weekly digest</b>\n\ncheck the latest posts below.",
  {
    extra: { parse_mode: "HTML" },
    onError: (chatId, error) => {
      console.error("failed for", chatId, error);
      // mark the user as unreachable in your db, etc.
    },
  },
);

no rate limiting built in. Telegram allows at most 30 messages per second to different chats. for large audiences pair this with @yaebal/throttle to avoid hitting the limit and triggering 429 errors.