Telegram Bot Commands: setMyCommands, Scopes, Menu Button and Deep Links

You set a Telegram bot's command list either in @BotFather with /setcommands, sending one command - description pair per line, or from code with the Bot API method setMyCommands. Each command is 1-32 characters of lowercase English letters, digits and underscores, each description is 1-256 characters, and one list holds at most 100 commands.

Last verified: November 2026 against the Bot API reference (through Bot API 10.3) and Telegram's bot features guide.

The registered list is what Telegram apps show when a user types / and what the menu button next to the message field opens. It does not create any behavior by itself: your code still has to handle /help when it arrives. Registering commands is about discoverability, and a bot with no registered commands leaves users guessing.

1. Open @BotFather and send /setcommands (or go through /mybots, pick the bot, then Edit Bot and Edit Commands).
2. Choose the bot from the list.
3. Send the whole list as one message, one command per line, command first, then a space, a hyphen, a space and the description.

start - Start the bot and see what it can do
help - How to use this bot
order - Check the status of an order
support - Talk to a person
settings - Language and notification settings
cancel - Cancel the current action

Write the command names without the leading slash, the way Telegram's own tutorial does. Sending /setcommands again replaces the whole list rather than appending to it, so always paste the complete set. The list you set here is the default list, equivalent to setMyCommands with the default scope and no language.

If a line is rejected, the cause is almost always the name: a capital letter, a hyphen, a space or a non-Latin character in the command itself. Descriptions are free text and can be written in any language.

The limits below come from the BotCommand object and setMyCommands in the Bot API reference. They apply to commands you register; Telegram's features guide notes that commands users type can contain Latin letters, numbers and underscores, but only lowercase names are accepted in the registered list.

Telegram's guidance is to make commands specific: /newlocation and /newrule rather than a generic /new that then asks a follow-up question. Specific commands are self-documenting in the menu and remove a conversational round trip. Keep names short enough to type on a phone; 32 characters is a ceiling, not a target.

Telegram asks every bot to support three global commands, and its apps add interface shortcuts for them:

• /start begins the interaction and carries deep-link parameters.
• /help explains what the bot does and lists its commands.
• /settings, if applicable, shows the user's settings and how to change them.

setMyCommands takes a JSON array of BotCommand objects plus optional scope and language_code. It returns true on success. Sending JSON in the body is cleaner than the URL query string because the list nests:

curl -s https://api.telegram.org/bot<TOKEN>/setMyCommands \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"command": "start",   "description": "Start the bot"},
      {"command": "help",    "description": "How to use this bot"},
      {"command": "order",   "description": "Check an order"},
      {"command": "support", "description": "Talk to a person"}
    ]
  }'

Run it at deploy time, not on every process start. The list is stored by Telegram per bot, so calling it from each of twenty workers on boot does nothing useful and burns requests. A small script in your release pipeline that sets every scope and language you support keeps the menu in version control alongside the handlers it describes.

The rest of the family:

Remember that deleteMyCommands with no arguments only deletes the default list. If you set lists for groups, admins or specific languages, each needs its own delete call with the same scope and language_code.

Scopes let one bot show a short menu to customers in private chats, a moderation menu to group admins, and a different list in one specific group. The API defines exactly seven scope types:

chat_id accepts a numeric ID or a supergroup @username; the reference notes that channel chats and channel direct-message chats are not supported for the chat-based scopes. A moderation menu for admins everywhere looks like this:

curl -s https://api.telegram.org/bot<TOKEN>/setMyCommands \
  -H "Content-Type: application/json" \
  -d '{
    "scope": {"type": "all_chat_administrators"},
    "commands": [
      {"command": "warn",  "description": "Warn the replied-to user"},
      {"command": "mute",  "description": "Mute the replied-to user"},
      {"command": "stats", "description": "Group activity summary"}
    ]
  }'

Which list a user actually sees

Telegram resolves the menu by walking a fixed order and returning the first list that is set. Lists do not merge: if an admin list exists, admins see only that list, not the admin list plus the group list. Repeat shared commands such as /help in every list.

Scopes control what is shown, not what is allowed. The features guide is explicit that updates carry no information about the scope a command came from, and may contain commands that do not exist in your bot at all. Anyone can type /mute. Check the sender's rights in your handler, for example with getChatMember, before acting on a privileged command.

Pass language_code with a two-letter ISO 639-1 code and the list applies only to users whose Telegram app language matches. Leave it empty and the list becomes the fallback for that scope, used for every language you have not covered. A sensible setup is an English (or primary-market) list with no language_code, plus one call per translated language:

{
  "language_code": "es",
  "commands": [
    {"command": "start", "description": "Iniciar el bot"},
    {"command": "help",  "description": "Cómo usar este bot"},
    {"command": "order", "description": "Consultar un pedido"}
  ]
}

Translate descriptions, not command names. Command names are restricted to lowercase English letters, digits and underscores in every language, and keeping /order identical everywhere means one handler, consistent support documentation, and links that work for everyone. The same applies per scope: language-specific lists sit above the plain list at every level of the resolution order shown above.

In private chats, Telegram shows a menu button beside the message field. By default it opens the bot's command list. setChatMenuButton changes that, either for one private chat (pass chat_id) or as the bot-wide default (omit it). The menu_button object is one of three types:

curl -s https://api.telegram.org/bot<TOKEN>/setChatMenuButton \
  -H "Content-Type: application/json" \
  -d '{"menu_button": {"type": "web_app", "text": "Open store",
       "web_app": {"url": "https://shop.example.com/tg"}}}'

Replacing the menu with a Mini App hides the command list behind typing /, so do it only when the app is the primary interface. A per-chat override is useful for onboarding: show a Mini App button to a user mid-checkout, then reset that chat to commands when they finish. For buttons inside messages rather than beside the input field, inline keyboards are the better tool; the Telegram keyboard builder lays them out and checks callback_data limits.

Every bot has a link, https://t.me/<bot_username>, and you can append a parameter that reaches your bot as part of /start:

Per Telegram's deep linking documentation, the parameter allows A-Z, a-z, 0-9, _ and -, up to 64 characters. Telegram recommends base64url for anything binary. Common uses are campaign attribution (?start=ig_bio), linking a Telegram account to a web account with a one-time code, and landing a user directly in a flow (?start=order_8812).

Parse it defensively. Your /start handler should split on the first space, treat the remainder as untrusted input, and still work when the payload is missing, because users also start bots by tapping Start with no link involved. For account linking, use a short-lived random code that maps to the account server-side rather than putting a user ID or email in the link. The Telegram link generator builds and validates both link types.

In a group with several bots, /help is ambiguous. Telegram's convention is the suffixed form /help@your_bot, which the docs list as a command "explicitly meant" for that bot. Your parser should accept both forms and should ignore commands addressed to a different bot.

/order 8812            -> command "order", args "8812"
/order@your_bot 8812   -> same, explicitly addressed to you
/order@other_bot 8812  -> not for you, ignore

Privacy mode decides which of those messages reach you at all. It is on by default, and a bot in privacy mode receives, per the docs:

• commands explicitly meant for it, such as /command@this_bot;
• general commands such as /start, if this bot was the last bot to send a message to the group;
• inline messages sent via the bot, and replies to messages meant for it;
• plus, regardless of privacy mode, all service messages.

So a bare /help in a busy group with other bots may never arrive. Bots added as administrators receive all messages. Disabling privacy mode with BotFather's /setprivacy also works, but the change only takes effect after the bot is removed and re-added to the group, a step that accounts for many "it works in DMs but not in my group" reports covered in why a Telegram bot is not responding.

Ephemeral commands

Bot API 10.2 (July 2026) added an optional is_ephemeral field to BotCommand. When a command is declared ephemeral, the user's message invoking it is delivered to your bot but stays invisible to other group members and other bots, so someone can run /balance in a public group without broadcasting it. Bots can answer with ephemeral messages visible only to that user. The details and timing rules are in our Bot API 10 breakdown.

1. Handle /start, /help and, if you have settings, /settings. Make /start work with and without a payload.
2. Name commands with lowercase letters, digits and underscores, 32 characters or fewer, and make each one specific.
3. Set the default list, then narrower lists only where the audience truly differs. Repeat shared commands in every list, because lists do not merge.
4. Add language_code lists for translated descriptions, keeping command names identical.
5. Set lists from a deploy script with setMyCommands, and verify with getMyCommands for each scope.
6. Enforce permissions in the handler; scopes only hide menu entries.
7. Parse /cmd@your_bot and ignore commands addressed to other bots.
8. Decide deliberately between the commands menu button and a Mini App button.

Message length, callback data, polling and request ceilings that commands run into are collected on the Telegram limits page, and any error string a command handler hits is explained in the Bot API error codes guide. If you would rather design the conversation than the command router, Conferbot's Telegram integration builds flows visually on top of the same Bot API.