WebFixer24 Обсудить задачу

Команды Telegram-бота: как добавить, изменить и настроить список команд

Разбираем, как добавить и изменить команды Telegram-бота, настроить список через BotFather или API и проверить, почему команда отображается, но не выполняется.

Обновлено: Время чтения: около 10 минут

Команды помогают пользователю понять, что умеет Telegram-бот, и быстро запустить нужное действие: начать работу через /start, открыть справку через /help, посмотреть настройки или выполнить собственную команду проекта.

Но здесь легко перепутать две разные вещи. Список команд в интерфейсе Telegram и обработка этих команд самим ботом — не одно и то же. Можно добавить /catalog через BotFather и увидеть её в меню, но бот не начнёт выполнять эту команду, пока соответствующая логика не появится в коде.

Что такое команда Telegram-бота

Обычно команда начинается с /:

/start
/help
/catalog
/settings

Когда пользователь выбирает команду из меню или вводит её вручную, Telegram передаёт боту соответствующее сообщение. Дальше уже код бота должен определить команду и выполнить нужное действие.

Поэтому у команды фактически есть две части:

  1. описание команды в Telegram — название и короткая подсказка, которые видит пользователь;
  2. обработчик в коде — логика, которая реально выполняется после получения команды.

Например:

start - Начать работу
catalog - Открыть каталог
orders - Мои заказы
help - Помощь

Но сами ответы, открытие каталога и получение заказов должны быть реализованы отдельно.

↑ К оглавлению

Какие команды стоит добавить

Не нужно превращать меню в список из десятков технических действий.

Базовый вариант:

/start
/help
/settings

/settings имеет смысл добавлять, если у бота действительно есть пользовательские настройки.

У конкретного проекта могут быть свои команды:

/catalog
/order
/profile
/support

Название должно объяснять действие без дополнительной инструкции.

Если бот сложный, часть навигации удобнее сделать кнопками и меню внутри сообщений, а список команд оставить коротким.

↑ К оглавлению

Как добавить команды через BotFather

Для обычного бота самый простой способ — настроить список через @BotFather.

Путь:

/mybots
→ нужный бот
→ Edit Bot
→ Edit Commands

После этого отправляется список:

start - Начать работу
help - Помощь
catalog - Открыть каталог
orders - Мои заказы

После сохранения Telegram сможет показывать эти команды пользователю.

В BotFather название обычно указывается без /, а в интерфейсе Telegram оно отображается как /start, /help и т. д.

Ограничения имени команды

Имя Bot API-команды:

  • от 1 до 32 символов;
  • строчные английские буквы;
  • цифры;
  • _.

Корректные примеры:

start
my_orders
catalog2

Некорректные:

МоиЗаказы
my-orders

Описание команды лучше оставлять коротким и понятным.

↑ К оглавлению

Как изменить существующие команды

Открыть тот же раздел BotFather:

/mybots
→ нужный бот
→ Edit Bot
→ Edit Commands

и отправить актуальный полный список.

Например, было:

start - Начать
catalog - Каталог
help - Помощь

стало:

start - Начать работу
products - Каталог товаров
orders - Мои заказы
help - Помощь

Важно проверить и код бота.

Если /catalog переименовали в /products, а обработчик остался только для /catalog, пользователь увидит новую команду, но бот её не выполнит.

↑ К оглавлению

Почему команда появилась в меню, но бот на неё не отвечает

Добавление команды через BotFather не создаёт программную логику.

Например:

balance - Проверить баланс

Telegram покажет /balance. Но дальше приложение должно обработать полученный Update:

/balance
↓
получение Update
↓
распознавание команды
↓
запрос баланса
↓
ответ пользователю

Если обработчика /balance нет, команда сама по себе ничего полезного не выполнит.

Нужно разделять:

Команда отображается? Это конфигурация списка команд.

Бот выполняет команду? Это код, обработка Updates и backend.

Если бот вообще перестал отвечать на команды и сообщения, смотрите диагностику не отвечающего Telegram-бота.

↑ К оглавлению

Что проверить в обработчике команды

Общий принцип:

/start   → startHandler
/help    → helpHandler
/catalog → catalogHandler

Если команда видна, но не работает, проверить:

  1. получает ли приложение Update;
  2. распознаётся ли сообщение как команда;
  3. совпадает ли имя с зарегистрированным обработчиком;
  4. не возникает ли исключение внутри обработчика;
  5. отправляется ли ответ;
  6. не менялась ли маршрутизация после обновления кода.

Полезно смотреть логи приложения именно во время отправки команды.

↑ К оглавлению

Особенность /start

/start может приходить не только как:

/start

но и с параметром deep link:

/start promo

Такой сценарий используют для:

  • реферальных ссылок;
  • определения источника;
  • привязки пользователя;
  • запуска определённого сценария;
  • передачи небольшого параметра.

Например, https://t.me/example_bot?start=promo может привести к /start promo. Поэтому обработчик не должен без необходимости рассчитывать только на полное совпадение всей строки с /start.

↑ К оглавлению

Команды в группах

В группе команда может выглядеть:

/help@example_bot

Это позволяет Telegram различать команды нескольких ботов.

Если бот работает и в личных сообщениях, и в группах, это нужно учитывать при разборе команды.

↑ К оглавлению

Как настроить команды через Telegram Bot API

Для программного управления списком используется:

setMyCommands

Пример:

{
  "commands": [
    { "command": "start", "description": "Начать работу" },
    { "command": "catalog", "description": "Открыть каталог" },
    { "command": "help", "description": "Помощь" }
  ]
}

Запрос:

POST https://api.telegram.org/bot<TOKEN>/setMyCommands

Токен бота должен храниться только в защищённой конфигурации приложения.

Не публиковать его:

  • в frontend;
  • исходниках;
  • документации;
  • скриншотах.

Через setMyCommands можно задать до 100 команд. Но для обычного пользовательского бота обычно лучше оставить только действительно нужные команды.

↑ К оглавлению

Как посмотреть текущий список через API

Используется:

getMyCommands

Это полезно, когда:

  • BotFather показывает одно;
  • пользователь видит другое;
  • команды задавались программно;
  • используются разные scopes или языки.

Лучше проверить фактическую конфигурацию, чем ориентироваться только на интерфейс.

↑ К оглавлению

Как удалить список команд

Используется:

deleteMyCommands

Удаление может относиться к определённому scope и языку, а не обязательно ко всей конфигурации бота.

↑ К оглавлению

Разные команды для личных чатов, групп и администраторов

Bot API поддерживает scopes.

Наборы команд можно различать, например:

  • для всех пользователей;
  • личных чатов;
  • групп;
  • администраторов;
  • конкретного чата;
  • конкретного пользователя в конкретном чате.

Например, обычный пользователь видит:

/help
/profile

а администратор:

/report
/moderate
/settings

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

↑ К оглавлению

Команды для разных языков

setMyCommands поддерживает language_code.

Например, русский список может быть таким:

catalog - Каталог
help - Помощь

А английский:

catalog - Catalog
help - Help

При диагностике старых или разных списков нужно учитывать язык интерфейса пользователя.

↑ К оглавлению

BotFather или setMyCommands: что выбрать

Для небольшого бота проще BotFather.

Подходит, если:

  • команд мало;
  • список меняется редко;
  • всем нужен один набор;
  • нет сложной локализации.

setMyCommands удобнее, если:

  • несколько языков;
  • разные команды для групп/личных чатов;
  • отдельный набор администраторов;
  • конфигурация должна разворачиваться автоматически.

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

↑ К оглавлению

Почему отображается старый список команд

Проверить:

  1. что возвращает getMyCommands;
  2. какой scope используется;
  3. задан ли language_code;
  4. не вызывает ли приложение setMyCommands при запуске;
  5. нет ли более специфичного набора для конкретного чата или пользователя;
  6. действительно ли изменена та конфигурация, которую получает пользователь.

Не нужно сразу переписывать обработчики. Сначала определить источник отображаемого списка.

↑ К оглавлению

Меню команд и кнопка Menu — не всегда одно и то же

Рядом с полем ввода Telegram может показывать кнопку Menu. Она может открывать команды, но может быть настроена и на запуск Web App.

Если у проекта есть Telegram Mini App, это особенно важно.

Нужно отдельно различать:

  • список команд;
  • menu button;
  • логику самого бота;
  • Mini App.
↑ К оглавлению

Как проверить команды после изменения

1. Открыть меню команд

Проверить правильные названия и описания.

2. Выполнить каждую команду

Проверять реальную реакцию бота.

3. Проверить /start

Включая deep link, если он используется.

4. Проверить нужные типы чатов

Если бот работает в группах.

5. Проверить разные языки

Если есть локализованные команды.

6. Посмотреть логи

Должно быть видно получение команды и выполнение обработчика.

↑ К оглавлению

Если команда не работает после обновления бота

Если проблема появилась после изменения кода или зависимостей, список Telegram может быть ни при чём.

Проверить:

  • запускается ли обработчик;
  • не изменилась ли маршрутизация;
  • приходит ли Update;
  • нет ли ошибки до отправки ответа;
  • middleware/filters;
  • webhook или polling;
  • работу обычных сообщений.

Если одна команда не работает, а остальные отвечают — вероятнее локальная проблема обработчика.

Если не отвечают вообще все команды и сообщения — диагностировать работу бота целиком.

↑ К оглавлению

Короткая последовательность диагностики

  1. проверить команду в меню Telegram;
  2. получить текущий список через getMyCommands;
  3. проверить scope и язык;
  4. отправить команду вручную;
  5. убедиться, что Update дошёл до приложения;
  6. проверить распознавание команды;
  7. проверить запуск обработчика;
  8. посмотреть ошибку в логах;
  9. проверить отправку ответа;
  10. повторить тест после исправления.
↑ К оглавлению

Частые вопросы

Как добавить команды Telegram-боту?

Самый простой способ — открыть @BotFather, выбрать нужного бота, перейти в Edit Bot → Edit Commands и отправить список команд с короткими описаниями. Программно список можно задать через метод setMyCommands Bot API.

Почему команда есть в меню, но бот её не выполняет?

Список в меню и обработчик в коде — разные вещи. BotFather только сообщает Telegram, какую команду показывать. Чтобы бот ответил, приложение должно получить Update, распознать команду и выполнить соответствующий обработчик.

Как изменить команды Telegram-бота?

В @BotFather нужно открыть тот же раздел Edit Commands и отправить актуальный полный список. Если список меняется через API, проверьте вызовы setMyCommands и фактическую конфигурацию через getMyCommands.

Как удалить команды?

Для удаления используется метод deleteMyCommands. Удаление может относиться к определённому scope и языку, поэтому при необходимости нужно проверить, какая именно конфигурация удаляется.

Почему у разных пользователей отображаются разные команды?

Причиной могут быть разные scopes: личный чат, группа, администратор, конкретный чат или пользователь. Также на отображение влияет language_code и локализация списка команд.

Почему /start иногда приходит с дополнительным текстом?

Команда /start может содержать параметр deep link, например /start promo. Такой параметр используют для реферальных ссылок, определения источника и запуска отдельного сценария, поэтому обработчик не должен без необходимости ожидать только точное совпадение всей строки.

Сколько команд можно установить через Bot API?

Через setMyCommands можно задать до 100 команд. Для обычного пользовательского бота обычно лучше оставить только действительно нужные команды.

Что делать, если перестали работать сразу все команды?

Нужно диагностировать работу бота целиком: проверить получение Update, webhook или polling, маршрутизацию, middleware и логи, а также работу обычных сообщений. Если не отвечают все команды и сообщения, проблема, вероятно, шире одного обработчика.

↑ К оглавлению

Если нужно разобраться с существующим ботом

Если список команд настроен неправильно, команды отображаются, но не выполняются, или после изменений часть сценариев перестала работать, сначала имеет смысл определить, где именно находится сбой: в конфигурации Telegram, получении Updates или обработчиках приложения.

Часто существующего бота можно исправить точечно — без переписывания всего проекта.

Через платформу KWORK Здесь, без регистрации
↑ К оглавлению