Как настроить команды, кнопку меню и описание Telegram-бота

Коротко: что настраивается и где

У бота есть четыре элемента «витрины», и каждый можно задать в BotFather или через Bot API:

BotFather удобен для разовой настройки. API нужен, когда команды отличаются по языкам, ролям или чатам, и когда настройки должны храниться в коде вместе с ботом.

Команды: setMyCommands

Команда — латиница в нижнем регистре, цифры и подчёркивания, до 32 символов; описание — до 256 символов. Держите список коротким: 3–7 команд, которые действительно нужны.

curl -X POST "https://api.telegram.org/bot<TOKEN>/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"command": "start", "description": "Начать"},
      {"command": "orders", "description": "Мои заказы"},
      {"command": "help", "description": "Помощь"}
    ],
    "scope": {"type": "all_private_chats"},
    "language_code": "ru"
  }'

Области (scope)

Параметр scope позволяет показывать разные команды в разных местах:

• default — по умолчанию везде;
• all_private_chats — во всех личных чатах;
• all_group_chats — во всех группах;
• all_chat_administrators — администраторам всех групп;
• chat, chat_administrators, chat_member — конкретный чат, его администраторы или конкретный участник.

Telegram выбирает самую точную подходящую область. Например, в группе администратор увидит команды из chat_administrators, если они заданы, а обычный участник — из all_group_chats или default. Так удобно скрывать служебные команды вроде /stats от обычных пользователей.

Языки

Параметр language_code задаёт список для пользователей с этим языком интерфейса Telegram. Сначала задайте список без language_code — он станет запасным, затем переводы для ru, en, uz и других нужных языков. Учтите, что язык берётся из настроек приложения, а не из выбора внутри вашего бота.

Кнопка меню

Кнопка слева от поля ввода бывает трёх типов:

• commands — открывает список команд;
• web_app — запускает Mini App;
• default — поведение по умолчанию.

{
  "menu_button": {
    "type": "web_app",
    "text": "Каталог",
    "web_app": {"url": "https://example.com/app"}
  }
}

Без chat_id метод setChatMenuButton меняет кнопку по умолчанию для всех личных чатов, с chat_id — только для конкретного пользователя. Это можно использовать, чтобы показывать Mini App только после регистрации. Текст кнопки делайте коротким и конкретным: «Каталог», «Записаться», а не «Открыть».

Описание и короткое описание

Описание (до 512 символов) пользователь видит в пустом чате с ботом — над кнопкой Start. Это главный текст, который убеждает нажать. Ответьте в нём на три вопроса: что бот делает, чем полезен, что произойдёт после Start. В BotFather к описанию можно добавить картинку или короткую анимацию.

Короткое описание (до 120 символов) показывается в профиле бота и в превью, когда ссылку на бота пересылают. Одно предложение о пользе.

Оба текста задаются по языкам через language_code, как и команды. Имя бота тоже можно локализовать через setMyName.

Аватар и первое впечатление

До нажатия Start пользователь видит имя, аватар, короткое описание в профиле, описание с картинкой в чате и кнопку меню. Чек-лист:

• аватар читается в маленьком круге: логотип или знак без мелкого текста;
• имя говорит, что это за бот, а не только название бренда;
• описание объясняет пользу, а не приветствует;
• все тексты переведены на языки вашей аудитории;
• команды и кнопка меню совпадают с тем, что реально умеет бот.