Design a Telegram inline bot: queries, results, and private setup
Turn Telegram Inline Mode into testable requirements for empty queries, results, caching, private setup, location permission, and feedback.
If a bot's main job is “find one result and share it into this conversation,” users may not need to open its private chat first. Telegram's Inline Mode lets someone type “@botusername query” in any private chat, group, or channel, choose a result, and send it.
This works well for searching stickers, documents, products, places, templates, or knowledge entries. It is a poor fit for long forms, sensitive settings, or multi-step approvals. A useful specification goes beyond “enable Inline Mode” and defines queries, result cards, empty states, caching, and the switch to private chat.
Inline Mode is not a group bot
Telegram's Inline Bots documentation explains that an inline bot does not have to be a member of the current chat. The bot receives the inline query after the user types its username and search text. The selected result is sent only after the user taps it.
Telegram's 2016 feature announcement adds an important privacy boundary: inline bots do not see the other messages in the chat; they receive only what the user types after the bot username. This is different from adding a bot to a group and granting it visibility into messages.
Do not write “search the current conversation” unless another authorized data source actually provides that content. If search depends on a private account, preferences, or authorization, move setup to the bot's private chat and then return the user to Inline Mode.
Define five core rules
1. What does an empty query show?
When a user types only “@botusername,” the bot can show:
- recently used items;
- favorites;
- three example searches;
- public popular results that contain no sensitive data;
- a prompt to finish setup in private chat.
A blank panel often looks like a broken bot. Even when there are no default results, explain the shortest usable query.
2. What must each result contain?
Fix a title, summary, sent-message payload, and stable ID for each result type. Images and files can support recognition, but should not carry the only meaningful description. Titles need to remain distinguishable on a narrow screen, and summaries must not expose information that should stay private.
If results depend on an external service, distinguish “no matches” from “the service failed.” They require different user actions.
3. How is a query normalized?
Specify trimming, case handling, full-width punctuation, aliases, and minimum and maximum lengths. Decide whether a misspelling returns suggestions, approximate matches, or a clear no-result state.
4. How long may results be cached?
Telegram notes that inline results can be cached and that selection feedback may not correspond one-for-one with incoming requests. Public, static search can tolerate a longer cache. Inventory, prices, one-time invitations, and user-specific data need stricter rules.
Do not specify only “cache for 60 seconds.” Define whether the cache key includes user, language, region, and permission state, and which changes invalidate it immediately.
5. Which actions require private chat?
Account linking, preferences, history, sensitive data, and consequential writes usually belong in private chat. Telegram supports a “Switch to PM” control above inline results. After setup, the bot can offer a button that returns the user to Inline Mode.
A requirement example to adapt
Create a resource-search bot. A user can type “@mybot keywords” in any chat. An empty query shows three public examples, never personal history. Return at most 10 results with a title, two-line summary, and source date. Selecting one sends its title, summary, and original link. Ignore case and surrounding whitespace; queries shorter than two characters ask for more text. Cache public results for five minutes, but never put user favorites in the public cache. When an account is not linked, show “Set up in private chat.” Linking and unlinking are private-chat actions only. Use different messages for a search timeout and a genuine no-result response.
The data source and permission model still need to be filled in, but the main Inline Mode behavior is now testable.
Treat privacy and location as explicit decisions
An inline bot can request location for local results, but Telegram requires the option to be enabled through the official @BotFather, and the client asks the user for permission. Do not describe nearby search as passive location collection. Do not retain location unless the purpose, retention period, and deletion path are documented.
An inline query is not anonymous. The bot must still filter results for the requesting user. Being invoked in someone else's group is not permission to reveal private records.
Acceptance matrix
Test at least:
- an empty query, normal query, too-short query, and no-result query;
- invocation from a private chat, group, and channel composer;
- unconfigured and configured users;
- whether the sent message matches the preview;
- repeated cached queries across language and permission boundaries;
- upstream timeout, rate limit, and malformed data;
- returning to the original inline flow after private setup;
- a denied location request with a non-location fallback or clear exit.
BotFatherV2 can create and modify Telegram Serverless bots through an AI conversation, but that does not guarantee that every Inline Mode method is already covered by its fixed SDK. Put inline queries, result types, caching, and private setup in the requirements, inspect the generation report, and test the published bot in real Telegram clients. AI-assisted development also does not give the running bot an LLM automatically.
BotFatherV2 is an independent product and is not affiliated with Telegram's official @BotFather.
Sources
- Telegram, Inline Bots, no publication date shown, accessed October 11, 2026.
- Telegram Team, Introducing Inline Bots, January 4, 2016, accessed October 11, 2026.