Команды Telegram-бота: BotFather, setMyCommands и вебхук

Команды, которые пользователь видит, когда набирает / в чате с ботом, задаются в @BotFather. Отправьте ему /setcommands, выберите бота и пришлите список — по команде на строку, без слэша:

start - Запустить бота
help - Что умеет бот
settings - Настройки

Правила из Bot API:

• команда — от 1 до 32 символов: строчные латинские буквы, цифры и подчёркивание;
• описание — от 1 до 256 символов;
• в списке до 100 команд.

Telegram просит каждого бота поддерживать /start, /help и, если у бота есть настройки, /settings. Когда пользователь впервые открывает чат с ботом, он видит кнопку «Старт».

Меню — только подсказка. В сообщении может прийти любая команда, в том числе та, которой нет в списке, а какой список видел пользователь, бот не узнает. Проверяйте команды и права на своём сервере. В группе с несколькими ботами добавляйте к команде имя бота, /help@my_bot, чтобы она дошла до нужного.

Команды через API: setMyCommands

TOKEN="123456789:AA..."

curl -s "https://api.telegram.org/bot$TOKEN/setMyCommands" \
  -H 'Content-Type: application/json' \
  -d '{"commands": [
        {"command": "start", "description": "Запустить бота"},
        {"command": "help", "description": "Что умеет бот"}
      ]}'

В ответ придёт {"ok":true,"result":true}. getMyCommands возвращает текущий список, deleteMyCommands удаляет его.

language_code и scope показывают разным пользователям разные списки:

# Меню для тех, у кого Telegram на английском
curl -s "https://api.telegram.org/bot$TOKEN/setMyCommands" \
  -H 'Content-Type: application/json' \
  -d '{"language_code": "en", "commands": [
        {"command": "start", "description": "Start the bot"},
        {"command": "help", "description": "What the bot can do"}
      ]}'

# Меню для администраторов всех групп: start и help повторить
curl -s "https://api.telegram.org/bot$TOKEN/setMyCommands" \
  -H 'Content-Type: application/json' \
  -d '{"scope": {"type": "all_chat_administrators"}, "commands": [
        {"command": "start", "description": "Запустить бота"},
        {"command": "help", "description": "Что умеет бот"},
        {"command": "ban", "description": "Забанить пользователя"}
      ]}'

Типы scope: default, all_private_chats, all_group_chats, all_chat_administrators, chat, chat_administrators, chat_member. Каждый пользователь видит один список, списки не складываются: список для scope или языка заменяет всё меню. Telegram выбирает список самого узкого scope, для которого он задан: сначала на языке пользователя, потом без языка, а если ничего нет — default. В getMyCommands и deleteMyCommands передавайте те же scope и language_code.

Команды BotFather

Команда	Что делает
/newbot	создать бота и получить токен
/mybots	список ваших ботов с кнопками для настройки
/setname	поменять имя бота
/setdescription	текст «Что умеет этот бот?», до 512 символов
/setabouttext	текст в профиле бота, до 120 символов
/setuserpic	аватарка
/setcommands	меню команд
/setjoingroups	разрешить или запретить добавлять бота в группы
/setprivacy	режим приватности: какие сообщения из групп получает бот
/setinline	инлайн-режим
/token	новый токен, если старый утёк
/deletebot	удалить бота, отменить нельзя

BotFather со временем получает новые команды. Чтобы увидеть актуальный список, наберите / в чате с ним.

Адреса Bot API: токен и вебхук

Каждый метод доступен по адресу https://api.telegram.org/bot<токен>/МЕТОД, через GET или POST:

# Проверить токен: вернёт id, имя и username бота
curl -s "https://api.telegram.org/bot$TOKEN/getMe"

# Поставить вебхук: Telegram будет слать обновления на этот HTTPS-адрес
curl -s "https://api.telegram.org/bot$TOKEN/setWebhook" \
  -d url=https://example.com/telegram/webhook \
  -d secret_token=my-secret-123

# Состояние вебхука: url, pending_update_count, last_error_message
curl -s "https://api.telegram.org/bot$TOKEN/getWebhookInfo"

# Снять вебхук и выбросить накопившиеся обновления
curl -s "https://api.telegram.org/bot$TOKEN/deleteWebhook" \
  -d drop_pending_updates=true

• Вебхук работает на портах 443, 80, 88 и 8443, всегда по HTTPS, даже на 80-м.
• С secret_token каждый запрос от Telegram приходит с заголовком X-Telegram-Bot-Api-Secret-Token и этим значением. Сверяйте его и отбрасывайте запросы не от Telegram.
• Если сервер ответил не 2XX, Telegram повторит запрос и через несколько попыток сдастся.
• Пока стоит вебхук, getUpdates не работает: Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first. Чтобы перейти на опрос, вызовите deleteWebhook.

Токен в адресе попадает в историю терминала и логи сервера. Если он утёк, получите новый командой /token в BotFather.