Skip to content

Bots in groups

How a bot joins and leaves Morsel groups, what privacy mode delivers to it, how button presses and answers work in a group, and the limits.

A group owner or admin adds your bot by its @username. From then on your bot is a member, end-to-end encrypted like everyone else, with a Bot badge.

Joining

  1. A manager adds the bot. Your bot gets bot_added, with the group's id and who added it.
  2. The SDK opens the group's keys, which are wrapped for the bot's address like any member's.
  3. It accepts the group with the bot's own signed join in the group's membership log, exactly as a person's app does.
  4. Then your handlers run, and the bot can read and write.
TypeScript
bot.on('bot_added', (ctx) => ctx.reply('Hi all. Try /poll.')); // ctx.chat is the group, ctx.update.by the manager
bot.on('bot_removed', (ctx) => forgetGroup(ctx.chat!.id));
Python
@bot.on("bot_added")
async def added(ctx: Context) -> None:
    await ctx.reply("Hi all. Try /poll.")  # ctx.gid is the group, ctx.group_event.by the manager


@bot.on("bot_removed")
async def removed(ctx: Context) -> None:
    forget_group(ctx.gid)

To decide yourself, turn off automatic joining with autoJoinGroups: false in TypeScript or auto_join_groups=False in Python, then call bot.joinGroup(gid) or await bot.join_group(gid).

A bot can be in up to 5000 groups. It can't create groups, add or remove people, or become an admin. Those calls answer 403 BOT_FORBIDDEN.

Leaving

TypeScript
bot.command('leave', (ctx) => ctx.leaveChat()); // or bot.leaveGroup(gid)
Python
@bot.command("leave")
async def leave(ctx: Context) -> None:
    await ctx.leave()  # or await bot.leave_group(gid)

The bot leaves with its own signed leave event, so members see a verified line.

Privacy mode

Privacy mode is on by default. Morsel's servers then deliver only these group messages to your bot:

  • commands: /cmd reaches every bot in the group, /cmd@yourbot reaches yours;
  • messages that mention your bot;
  • replies to your bot's messages;
  • presses of your bot's buttons;
  • the bot's own messages, and the group's system lines: membership, keys and settings.

Everything else never reaches the bot: not live, not in sync, not on the webhook, and no reactions, edits or pins of messages it never got. The sender's app marks which bots a message is for, and the server delivers it only to them.

Turn privacy mode off when your bot truly needs every message, for example to moderate:

TypeScript
await bot.setGroupPrivacy(false);
Python
await bot.set_group_privacy(False)

Or use Privacy mode on your bot's page in My bots. When it changes, every group the bot is in gets a line like Quiz night can now read all messages, and the group's info says so for as long as it lasts. People decide whether to stay. Keep it on unless you need it.

What your bot receives in a group

ctx.chatNotes
A message{ type: 'group', id: <gid> }ctx.from is the member who wrote. Every group message is signed by its sender, and the SDK drops any whose signature doesn't hold.
A button pressthe groupOnly the presser and the bot receive it. Other members never learn who pressed what.
bot_added, bot_removedthe groupctx.from is the manager, when known.

In Python, a group's ctx.chat is Chat(gid, "group"), and ctx.gid is its id. On bot_removed there's no chat to answer in, so use ctx.gid.

Answers and edits in a group

  • ctx.answer() to a press goes to the presser alone, as a private row naming the group. The group never sees it.
  • ctx.reply() and edits go to the group.
  • A reply keyboard can be shown to some members only, with selective. A tap on it is sent as a reply to your bot, so a privacy-mode bot still gets it.
  • ctx.requestPayment() in a group names the member who wrote.
  • Bots show no typing in groups. ctx.typing() does nothing there.

Limits

  • 20 messages a minute per group, on top of the group's own limits. Past that, 429 BOT_RATE_LIMIT with retryAfter. The SDK's send queue keeps under it and retries for you.
  • Edits for 48 hours, 100 a message, as in private chats.

Try one of these