Telegram Bot API commands: setMyCommands and the command menu

What a command looks like

According to Telegram's documentation, a command always starts with / and has up to 32 characters: Latin letters, numbers and underscores. Simple lowercase words such as /next or /cancel are recommended. Be specific: /newrule is clearer than a /new that has to ask «new what?».

Telegram apps do three things with commands:

• highlight a command in messages, and tapping it sends the command again;
• show a list of suggestions with descriptions when a user types /;
• show a menu button next to the input field with all or some of the bot's commands.

Telegram asks every bot to support three global commands: /start (begins the interaction; a parameter from a link also arrives here), /help (a help message) and /settings (the user's settings, if there are any).

How to set the command list in BotFather

1. Open a chat with @BotFather and send /setcommands.
2. Choose your bot.
3. Send the list, one command per line, in the form command - description.

An example of three lines: start - Start the bot, help - Help, settings - Settings.

BotFather's other commands and the /mybots settings menu are covered in how to create a Telegram bot.

setMyCommands: setting the list from code

The setMyCommands method changes the list of the bot's commands. Its parameters:

• commands — required. A list of BotCommand objects, at most 100. Each has a command (1–32 characters: lowercase Latin letters, digits and underscores, without the slash) and a description (1–256 characters).
• scope — who the list is for. The default is BotCommandScopeDefault, which means everyone.
• language_code — a two-letter ISO 639-1 language code. If it is empty, the list applies to all users in that scope whose language has no list of its own.

An example request:

curl "https://api.telegram.org/bot<TOKEN>/setMyCommands" -H "Content-Type: application/json" -d '{"commands":[{"command":"start","description":"Start the bot"},{"command":"help","description":"Help"}]}'

On success the response has "result": true. The method sets the whole list, so send all the commands at once. getMyCommands reads the current list and deleteMyCommands removes it: after a deletion, the affected users are shown the commands of a wider scope.

Scopes and languages: different commands for different people

You can show different commands to different users. Seven scopes are supported:

Telegram works out which list a person sees by going through the scopes in order and returning the first list that is set. In a private chat with the bot it checks chat, then all_private_chats, then default. In groups it checks chat_member, chat_administrators (administrators only), chat, all_chat_administrators (administrators only), all_group_chats and default. At each step it looks first for a list with the user's language_code and then for one without a language.

In practice this means a list for all_private_chats overrides default in private chats, and if you set a list for one language, people with that language see it instead of the general one.

How a bot receives a command

A command arrives in an ordinary message update: text holds /start, and entities contains an entity of the type bot_command. In groups a command is addressed to a particular bot with an @: /command@bot_username. If the bot has privacy mode on, in a group it sees only the commands meant for it, and general commands such as /start when it was the last bot to write in that group.

The /start command with a parameter

A bot's link opens a chat with it: https://t.me/<bot_username>. You can add a start parameter, and the bot receives it together with the command:

• the link https://t.me/your_bot?start=airplane sends the bot /start airplane;
• the allowed characters are A-Z, a-z, 0-9, _ and -, up to 64 characters; Telegram recommends encoding binary and other content with base64url;
• a link with the startgroup parameter asks the user to choose a group to add the bot to, and the bot receives /start@your_bot spaceship.

Bots' referral links are built on the start parameter too: see referral links in Telegram.

Why the commands don't show in the menu

• The list isn't set. Until you call setMyCommands or /setcommands, there are no suggestions.
• A narrower scope overrides it. A list for all_private_chats, or one for the user's language, takes priority over the general one. Call getMyCommands with the scope and language_code you care about and see what is set.
• The command breaks the format. Only lowercase Latin letters, digits and underscores, up to 32 characters.

If a command shows but the bot stays silent, the problem is in the code: the list is only a hint, and the handler is written separately. How a bot receives events is explained in getUpdates vs webhook, and you answer with the sendMessage method.

What next

Commands are handy when a bot has something to do, such as taking payments. How to accept Stars is in accepting Stars in your bot. The API of the Shiba Bank bot is described in the API documentation.

Frequently asked questions