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
- A manager adds the bot. Your bot gets
bot_added, with the group's id and who added it. - The SDK opens the group's keys, which are wrapped for the bot's address like any member's.
- It accepts the group with the bot's own signed
joinin the group's membership log, exactly as a person's app does. - Then your handlers run, and the bot can read and write.
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));@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
bot.command('leave', (ctx) => ctx.leaveChat()); // or bot.leaveGroup(gid)@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:
/cmdreaches every bot in the group,/cmd@yourbotreaches 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:
await bot.setGroupPrivacy(false);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.chat | Notes | |
|---|---|---|
| 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 press | the group | Only the presser and the bot receive it. Other members never learn who pressed what. |
bot_added, bot_removed | the group | ctx.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_LIMITwithretryAfter. The SDK's send queue keeps under it and retries for you. - Edits for 48 hours, 100 a message, as in private chats.