How Telegram bot commands work, and how to set them up

What a bot command is

A command is a message that starts with /, followed by a word, like /start, /help or /settings. When a user sends one, the bot's program reads it and does whatever that command is meant to do.

Users can trigger a command in three ways:

• Typing it in the message field. As soon as they type /, Telegram shows the bot's command list with a short description of each.
• Tapping the menu button next to the message field and picking a command from the list.
• Tapping a command that appears in a message. Commands in a bot's messages show as links, so the bot can write "Send /help to see what I can do" and the user just taps it.

Commands can also carry extra text after a space. For example, a bot might accept /remind 10m stretch. How that extra text is used depends entirely on the bot's code.

What /start and /help do

/start is special. When someone opens a bot for the first time and taps the Start button, Telegram sends /start on their behalf. This is the moment the user agrees to talk to the bot: a bot can only message people who started it or wrote to it.

That makes the reply to /start the most important message your bot sends. It should say what the bot does and what to do next, ideally with buttons. See how to write a bot welcome message.

/start can also carry a hidden value. A link like https://t.me/your_bot?start=promo opens the bot and sends /start promo, so you can tell which link brought each user. The value can be up to 64 characters from A-Z, a-z, 0-9, _ and -. Read more in Telegram deep links.

/help is a convention rather than a rule. Telegram doesn't do anything special with it, but users expect it to work, so every bot should answer it with a short explanation and a way to reach a person if needed.

Other commands are up to you. One case is required: bots that take payments in Telegram Stars must respond to /paysupport, offer terms (for example with /terms), and provide customer support.

The rules for command names

So /my_orders works, while /my-orders and /mis_pedidos_ñ don't. A bot that speaks Arabic, Russian or Chinese still needs Latin command names. Only the descriptions shown next to them in the menu can be in the user's language.

Stick to lowercase. It's easier to type on a phone, and it's what users are used to seeing.

How to set commands with /setcommands

The command list people see in the menu is set in @BotFather. It's just a list: it doesn't make the commands work. Your bot's code still has to answer each one.

1. Open @BotFather and send /setcommands.
2. Pick your bot from the list.
3. Send the whole list in one message, one command per line, in the format command - Description, without the slash.

For example:

start - Open the main menu
help - How to use this bot
language - Change the language
support - Talk to a person

Each time you send /setcommands, the new list replaces the old one, so always send the full list. Changes can take a moment to appear, and some apps only refresh the list after the chat is reopened. The other profile settings are covered in how to change your bot's name, photo and commands.

Developers can also set the list from the bot's own code through the Bot API. That's how bots set the more detailed lists described next.

The menu button, languages and scopes

The menu button sits next to the message field in a bot's chat. By default, it opens the command list. It can instead open a Mini App, a web interface that runs inside Telegram. If you do that, people lose the quick list of commands from the menu, so make sure the Mini App or the bot's buttons cover the same ground. See what Telegram Mini Apps are.

Command lists don't have to be the same for everyone. Telegram lets a bot set different lists:

• By language. A user whose Telegram is set to Spanish can see Spanish descriptions, while an English user sees English ones. The command names stay the same.
• By scope. A bot can show one list in private chats, another in groups, and a third only to a group's admins. Admin-only tools like /ban then stay out of ordinary members' menus.

Hiding a command from the menu doesn't secure it. Anyone can still type it, so the bot's code must check who is asking before doing anything sensitive.

Commands in groups

In a group with several bots, a plain /help is ambiguous. Telegram solves this with the bot's username: /help@your_bot goes to that specific bot. When someone picks a command from the list in a group, Telegram apps often add the username for them.

This matters because of privacy mode, which is on by default. In a group, a bot in privacy mode receives only commands meant for it, replies to its own messages, messages sent through it in inline mode and service messages. It doesn't see ordinary chat. That's why commands are the main way to talk to a bot in a group, and why a bot sometimes seems to ignore people. If a bot doesn't respond, the fixes are in how to add a bot to a group.

A good group command often works as a reply. In the Translator template, for example, someone replies to any message with /en or /es and the bot translates that message. It's two or three characters to type, and it needs no extra explanation.

How to design good commands

Most users never type a command beyond /start. They tap buttons. So treat commands as shortcuts for people who know what they want, not as your main interface. A few rules help:

• Keep the menu short. Three to six commands is plenty for most bots. A list of twenty is a sign the bot needs buttons instead.
• Use plain verbs or nouns. /orders, /language and /support say what they do. Avoid abbreviations people have to learn, unless they're for power users.
• Write descriptions as actions. "Change the language" beats "Language settings menu".
• Make /start safe to repeat. Users send it again when they're lost, so it should always bring them back to the main menu without resetting their data.
• Answer unknown commands. If someone types a command that doesn't exist, reply with a hint like "I don't know that one. Try /help."
• Hide admin tools. Use scopes to keep owner and moderator commands out of public menus, and check permissions in code.

Example command sets

Some commands only make sense for the owner. In the Contact Bot template, the team sends quick replies with /r1, /r2 and so on. In Tell Me, a user replies /ban to block a sender. And bots made with Echo Maker use /start for two jobs: users get the bot's menu, while the owner gets the admin panel.