service events

telegram sends many changes as updates or service messages: joins, leaves, reactions, pins, payments, forum topic changes, boosts, and chat migrations.

new members

joins.ts

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.on("message", async (ctx) => {
  const members = ctx.message?.new_chat_members;
  if (!members?.length) return;

  await ctx.reply("welcome " + members.map((u) => u.first_name).join(", "));
});

reactions

reaction updates are not part of telegram's default update set. registering a handler for them (on("message_reaction")) is enough: bot.start(), the runner and setWebhook then request the default set plus message_reaction. an explicit allowedUpdates option always wins.

reactions.ts

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.on("message_reaction", async (ctx) => {
  const reaction = ctx.update.message_reaction!;
  console.log(reaction.user?.id, reaction.old_reaction, reaction.new_reaction);
});

pinned messages

pinned.ts

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.on("message", async (ctx) => {
  if (!ctx.message?.pinned_message) return;
  await ctx.reply("new pinned message");
});

chat boosts

chat_boost and removed_chat_boost arrive by default — the bot only has to be an administrator of the chat.

boost.ts

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.on("chat_boost", async (ctx) => {
  const boost = ctx.update.chat_boost!.boost;
  console.log("boosted until", new Date(boost.expiration_date * 1000));
});

common service fields

field/update	what it means
`new_chat_members`	users joined a group
`left_chat_member`	a user left or was removed
`pinned_message`	a message was pinned
`successful_payment`	a payment completed — see payments
`forum_topic_created`	a forum topic was created
`message_reaction`	a user changed reactions on a message
`chat_boost` / `removed_chat_boost`	a boost was added to, or removed from, the chat
`migrate_to_chat_id`	a group was upgraded to a supergroup — the chat id changed

message:<field> filter queries narrow some of these (photo, successful_payment, web_app_data, …) onto a typed ctx.message — see core concepts. the rest ( new_chat_members, left_chat_member, pinned_message) aren't in that narrowing list yet, so check them with a plain if as shown above.

service events are normal bot logic. route them, test them with @yaebal/test, and include them in allowedUpdates when telegram does not send them by default.