Команды бота Telegram: меню, setMyCommands и BotFather

Какой бывает команда

По документации Telegram, команда всегда начинается с / и содержит до 32 символов: латинские буквы, цифры и подчёркивания. Рекомендуются простые слова в нижнем регистре, например /next или /cancel. Лучше конкретные названия: /newrule понятнее, чем /new с вопросом «что именно?».

Приложения Telegram делают с командами три вещи:

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

Telegram просит поддержать три общие команды: /start (начало работы, туда же попадает параметр из ссылки), /help (справка) и /settings (настройки, если они есть).

Как задать список команд в BotFather

1. Откройте чат с @BotFather и отправьте /setcommands.
2. Выберите бота.
3. Пришлите список: по одной команде в строке в виде команда - описание.

Пример списка из трёх строк: start - Начать, help - Справка, settings - Настройки.

Все команды BotFather и интерактивное меню настроек /mybots описаны в статье как создать бота в ТГ.

setMyCommands: список команд из кода

Метод setMyCommands меняет список команд бота. Параметры:

• commands — обязательный. Список объектов BotCommand, не больше 100 штук. У каждого есть command (от 1 до 32 символов: строчные латинские буквы, цифры и подчёркивания, без косой черты) и description (от 1 до 256 символов).
• scope — для кого действует список. По умолчанию это BotCommandScopeDefault, то есть для всех.
• language_code — двухбуквенный код языка по ISO 639-1. Если он пуст, список применяется ко всем пользователям из этой области, для языка которых нет отдельного списка.

Пример запроса:

curl "https://api.telegram.org/bot<ТОКЕН>/setMyCommands" -H "Content-Type: application/json" -d '{"commands":[{"command":"start","description":"Начать"},{"command":"help","description":"Справка"}]}'

При успехе в ответе "result": true. Метод задаёт список целиком, поэтому передавайте все команды сразу. Прочитать текущий список можно методом getMyCommands, удалить — deleteMyCommands: после удаления людям снова покажут команды более широкой области.

Области и языки: разные команды разным людям

Команды можно показывать по-разному. Поддерживаются семь областей:

Какой список увидит человек, Telegram определяет по порядку, и берётся первый заданный. В личном чате с ботом проверяются chat, затем all_private_chats, затем default. В группах — chat_member, chat_administrators (только для администраторов), chat, all_chat_administrators (только для администраторов), all_group_chats и default. На каждом шаге сначала ищется список с языком пользователя (language_code), потом без языка.

Отсюда практический вывод: список для all_private_chats перекроет default в личных чатах. А если вы задали список для одного языка, людям с этим языком покажут именно его, а не общий.

Как бот получает команду

Команда приходит в обычном обновлении message: в text лежит /start, а в entities есть сущность типа bot_command. В группах команду адресуют конкретному боту через @: /command@имя_бота. Если у бота включён режим приватности, в группе он увидит только команды, адресованные ему, и общие команды вроде /start, когда он последним писал в эту группу.

Команда /start с параметром

Ссылка на бота открывает чат с ним: https://t.me/<имя_бота>. К ней можно добавить параметр start, и бот получит его вместе с командой:

• ссылка https://t.me/your_bot?start=airplane пришлёт боту /start airplane;
• допустимы символы A-Z, a-z, 0-9, _ и -, длина — до 64 символов; для двоичных и других данных Telegram советует кодировать их в base64url;
• ссылка с параметром startgroup предлагает выбрать группу, куда добавить бота, и бот получает /start@your_bot spaceship.

На параметре start держатся и реферальные ссылки ботов: об этом в статье про реферальные ссылки.

Почему команды не видны в меню

• Список не задан. Пока вы не вызвали setMyCommands или /setcommands, подсказки нет.
• Перекрыт более узкой областью. Список all_private_chats или список для языка пользователя важнее общего. Вызовите getMyCommands с нужными scope и language_code и посмотрите, что задано.
• Команда не соответствует формату. Только строчные латинские буквы, цифры и подчёркивания, до 32 символов.

Если команда видна, но бот молчит, дело в коде: список команд лишь подсказка, а обработчик пишется отдельно. Как получать события, рассказано в статье про getUpdates и webhook, а ответ отправляется методом sendMessage.

Что дальше

Команды удобны, когда у бота есть чем заняться: например, принимать оплату. Как подключить платежи звёздами, читайте в статье оплата звёздами в боте. Описание API бота Shiba Bank — в документации API.

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