Telegram guest mode: answering groups your bot was never added to

Guest mode (Bot API 10.0, May 2026) removes the oldest wall in Telegram bot design: the requirement that a bot must be a member of a chat to talk in it. With the supports_guest_queries flag enabled, any group can summon your bot by @mention and receive one inline-style answer via answerGuestQuery, without the bot ever being added or reading the group's conversation.

I ship this in production on @roestwerk_bot: a customer can pull the shop into a school chat, a neighborhood group, or a delivery group by typing @roestwerk_bot coffee, and a product card appears. Nobody had to invite the bot; the bot saw nothing but the mention.

What does guest mode actually change?#

By default a bot participates only in chats where it is a member: added to the group, or messaged directly. Guest mode adds one narrow exception:

• Any group can trigger the bot with an @mention (optionally with query text after it, like @roestwerk_bot filterkaffee).
• The bot receives a guest_message update containing the mention and the query text. It does not receive the group's other messages, now or later.
• The bot answers through answerGuestQuery, which takes inline-result-style payloads: an article card with a thumbnail, a venue, a deep-link button into your Mini App.

The mental model from the user's side: a courier window. You knock, you get your answer, the courier never enters your house.

Enabling it: one flag, one handler#

Setup is deliberately small:

1. @BotFather → /mybots → your bot → Bot Settings → enable supports_guest_queries. This is the owner's permission for the bot to receive guest updates at all.
2. Handle the guest_message update and answer every query through answerGuestQuery.

One implementation caveat worth knowing before you start: as of grammY 1.46 the type definitions predate the guest_message update type, so you narrow the update by hand and register the handler as trailing middleware. The logic itself is twenty lines: match the mention text against the catalog, pick the top product, build the card.

What the bot can and cannot see#

The privacy shape is the feature's selling point, and it is worth stating precisely:

• Seen: the mention, the query text, the group and user ids attached to the guest update.
• Never seen: the rest of the group's conversation, before or after. The bot cannot lurk, and the group's history is out of reach in both directions.

For a café or shop this reads as free reach without spam: customers spread the bot into their own group chats, and the privacy concern that kills most "add our bot to your group" pitches does not apply, because there is nothing to read.

The limit the docs do not confirm#

Community sources mention a cap of roughly three guest answers per triggering message. The Bot API pages do not document the number. I treat it as unverified and confirm behavior live in a test group: create a group, do not add the bot, send an @mention from a second account, and watch what comes back. Rehearsing beats quoting an undocumented number in front of a client.

When guest mode is worth it#

Any bot whose value survives being compressed into one card: shops with a small catalog, appointment and pickup businesses, FAQ-style assistants. If the answer to a mention needs a conversation rather than a card, guest mode is the wrong shape and a deep link into a chat with the bot remains the flow. And since the answer rides the same Bot API as everything else, notifications and the rest of the bot keep working exactly as before; guest mode adds a door, it does not rearrange the house.