The short answer
- 1Commands are / plus 1-32 lowercase letters, digits or underscores.
- 2Register in @BotFather, or with setMyCommands to split by scope and language.
- 3Hiding a command from a list does not block it; check rights when you handle it.
In this article
What a command is
A command is a short word that starts with /. When someone types / in the message field, or taps the menu button, the list of commands your bot registered appears with their descriptions.
Showing that list and handling the command are separate jobs. Registration controls the list; your program handles the command by reading the text of the message it receives.
| Rule | Detail |
|---|---|
| Command name | 1 to 32 characters: lowercase English letters, digits and underscores only |
| Description | Up to 256 characters, shown next to the name in the list |
| Count | Up to 100 commands per scope and language |
| Worth having | /start, /help and /settings, which the official documentation recommends for every bot |
Give each command one clear job. /newlocation is easier to tap than /new followed by a word the user has to type.
Two ways to register them
With @BotFather
Choose your bot, open the command editor (/setcommands), and send one line per command in the form command - description. No code needed. If you have not made a bot yet, see creating a bot with BotFather.
With setMyCommands
Registering from your program lets you split the list by scope and language.
curl https://api.telegram.org/bot123456:ABC-EXAMPLE/setMyCommands \
-H "Content-Type: application/json" \
-d '{"commands":[
{"command":"start","description":"Get started"},
{"command":"help","description":"How this bot works"}
]}'Add "language_code":"de" to the same request with German descriptions, and German-language users see that list instead. getMyCommands shows what is registered and deleteMyCommands removes it; both take the same scope and language values. The token and values here are examples; see your first Bot API requests.
Splitting the list by scope
| scope type | Who sees the list |
|---|---|
default | Everywhere no more specific list applies |
all_private_chats | All private chats with the bot |
all_group_chats | All groups and supergroups |
all_chat_administrators | Administrators in all groups |
chat / chat_administrators / chat_member | One specific chat, its administrators, or one user in it |
When several scopes apply to one user, the narrowest one wins. Within the same scope, a list for the user's app language comes before a list with no language. So registering a default list in English plus a list for each language you support is enough; Telegram picks the right one.
Commands in groups
When a group has several bots, a command can name its target: /help@your_bot. A bot with group privacy mode on still receives commands meant for it; see bot privacy mode. To open a mini app from the menu button instead of the command list, see the bot menu button.
FAQ
How do I add commands to my Telegram bot?
In @BotFather use /setcommands and send one 'command - description' line each, or call setMyCommands from your code.
Can I show different commands to group admins?
Yes. Register a list with the all_chat_administrators or chat_administrators scope; admins see it instead of the default.
Does hiding a command stop people from using it?
No. Anyone can still type it. Check in your code that the sender is allowed before acting.
Sources
At a glance
- 1Rules
Names up to 32 chars, descriptions up to 256, 100 per list.
- 2Scope
The narrowest matching scope wins, then the user's language.
- 3Security
Re-check the sender before running admin commands.
Updated
