Команды Telegram-бота: setMyCommands, области видимости и deep link для /start
Команды Telegram-бота — это /ключевые_слова вроде /start или /help: приложения Telegram подсвечивают их в сообщениях, подсказывают при вводе / и показывают в меню бота. Список задают командой /setcommands в @BotFather или методом setMyCommands, который умеет ещё и области видимости (свои команды для групп, админов или одного чата) и отдельные списки для разных языков. Сама команда приходит боту обычным текстовым сообщением, а /start может нести параметр из deep link. Ниже — всё это с примерами на curl, Python и JavaScript.
Как устроены команды Telegram-бота
Команда — это просто сообщение, текст которого начинается с /. Регистрация команд не меняет того, что получает бот: она только сообщает приложениям Telegram, что подсказывать. Правила для списка в setMyCommands (объект BotCommand):
command: 1–32 символа, только строчные латинские буквы, цифры и подчёркивания, без начального слэша.description: 1–256 символов, показывается рядом с командой в подсказках.- Не больше 100 команд в одном списке.
Telegram просит всех разработчиков поддерживать глобальные команды /start (начало работы, через неё же приходят параметры deep link) и /help (что умеет бот и список команд), а также /settings, если у бота есть настройки. Конкретные команды вроде /newlocation лучше общей /new, которой нужны дополнительные аргументы.
Команды через @BotFather
Способ без кода, подходит для неизменного списка:
- Откройте @BotFather и отправьте
/setcommands. - Выберите бота.
- Пришлите список — по одной команде в строке в формате
команда - описание:
start - Запустить бота
help - Как пользоваться ботом
settings - Ваши настройки
Если бота ещё нет, начните с гайда как создать бота в Telegram.
Команды через setMyCommands
setMyCommands делает то же самое из кода: список команд хранится в репозитории и обновляется при деплое. Параметры: commands (обязательный, массив BotCommand), scope (необязательный, по умолчанию — область default) и language_code (необязательный двухбуквенный код ISO 639-1). Метод возвращает true:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
-H "Content-Type: application/json" \
-d '{"commands":[{"command":"start","description":"Запустить бота"},{"command":"help","description":"Как пользоваться ботом"}]}'
Чтобы попробовать без кода, откройте setMyCommands в Bot API Tester, вставьте токен, заполните команды и нажмите Execute. Затем вызовите getMyCommands и проверьте сохранённый список.
Области видимости и языки
Область (scope) определяет, кто увидит список. Типов BotCommandScope семь:
type области | Кто видит список | Доп. поля |
|---|---|---|
default | Все, если не подошёл более узкий список | — |
all_private_chats | Все личные чаты с ботом | — |
all_group_chats | Все группы и супергруппы | — |
all_chat_administrators | Администраторы всех групп и супергрупп | — |
chat | Один конкретный чат | chat_id |
chat_administrators | Администраторы одной группы или супергруппы | chat_id |
chat_member | Один участник одной группы или супергруппы | chat_id, user_id |
chat_id — числовой id или @username супергруппы; каналы и чаты личных сообщений каналов не поддерживаются. У каждой области могут быть списки для разных языков: с language_code список получают пользователи с этим языком приложения, без него — все в области, для чьего языка нет отдельного списка.
Telegram показывает первый заданный список, двигаясь от самой узкой области к общей. В личном чате порядок такой: chat → all_private_chats → default; в группах — chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default (админские области действуют только для администраторов). На каждом шаге список с языком пользователя важнее списка без языка.
Скрипт ниже задаёт список по умолчанию, английский перевод и дополнительные команды для админов групп, а затем читает один из списков:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=10).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
# Список по умолчанию для всех
call("setMyCommands", commands=[
{"command": "start", "description": "Запустить бота"},
{"command": "help", "description": "Как пользоваться ботом"},
{"command": "settings", "description": "Ваши настройки"},
])
# Те же команды для пользователей с английским интерфейсом Telegram
call("setMyCommands", language_code="en", commands=[
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "How to use the bot"},
{"command": "settings", "description": "Your settings"},
])
# Дополнительные команды для администраторов всех групп
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
{"command": "help", "description": "Как пользоваться ботом"},
{"command": "stats", "description": "Статистика группы"},
])
print(call("getMyCommands", scope={"type": "all_chat_administrators"}))const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
// Список по умолчанию для всех
await call("setMyCommands", {
commands: [
{ command: "start", description: "Запустить бота" },
{ command: "help", description: "Как пользоваться ботом" },
{ command: "settings", description: "Ваши настройки" },
],
});
// Те же команды для пользователей с английским интерфейсом Telegram
await call("setMyCommands", {
language_code: "en",
commands: [
{ command: "start", description: "Start the bot" },
{ command: "help", description: "How to use the bot" },
{ command: "settings", description: "Your settings" },
],
});
// Дополнительные команды для администраторов всех групп
await call("setMyCommands", {
scope: { type: "all_chat_administrators" },
commands: [
{ command: "help", description: "Как пользоваться ботом" },
{ command: "stats", description: "Статистика группы" },
],
});
console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));Области управляют только тем, что пользователь видит. В апдейте не указано, из какой области пришла команда, а ввести можно любую команду, в том числе незарегистрированную. Всегда проверяйте на сервере, что команда существует и пользователю можно её выполнять (например, права админа — через getChatMember).
getMyCommands и deleteMyCommands
getMyCommands возвращает массив BotCommand для заданных scope и language_code или пустой массив, если команды не заданы. deleteMyCommands удаляет список для этой области и языка; затронутые пользователи увидят следующий по порядку список:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"all_chat_administrators"}}'
Обработка команд и параметр /start
Команды приходят обычными апдейтами message с текстом в том виде, в каком его ввёл пользователь. В группах команда может быть адресована конкретному боту — /command@your_bot, поэтому часть с @username нужно отрезать, а команды для других ботов — пропускать. Deep link работает так:
https://t.me/your_bot?start=airplaneоткрывает чат с ботом, и бот получает/start airplane.https://t.me/your_bot?startgroup=spaceshipпредлагает выбрать группу, в которую добавить бота; бот получает/start@your_bot spaceship.- Параметр — до 64 символов, допустимы только
A-Z,a-z,0-9,_и-. Для бинарных и прочих данных Telegram рекомендует base64url.
Бот на long polling, который разбирает команды, обрабатывает /start с параметром и без и генерирует deep link в base64url:
import base64
import os
import re
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
BOT_USERNAME = requests.get(f"{API}/getMe", timeout=10).json()["result"]["username"]
COMMAND_RE = re.compile(r"^/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+(.*))?$", re.S)
def make_start_link(payload: str) -> str:
# base64url без дополнения "=": остаются только A-Z a-z 0-9 _ - (максимум 64 символа)
code = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
return f"https://t.me/{BOT_USERNAME}?start={code}"
def read_start_param(code: str) -> str:
return base64.urlsafe_b64decode(code + "=" * (-len(code) % 4)).decode()
def parse_command(text):
m = COMMAND_RE.match(text)
if not m or (m[2] and m[2].lower() != BOT_USERNAME.lower()):
return None # не команда или команда для другого бота
return m[1].lower(), (m[3] or "").strip()
def send(chat_id, text):
requests.post(f"{API}/sendMessage", json={"chat_id": chat_id, "text": text}, timeout=10)
print("Ссылка для приглашения:", make_start_link("ref:42"))
offset = 0
while True:
resp = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
for update in resp["result"]:
offset = update["update_id"] + 1
msg = update.get("message")
parsed = parse_command(msg.get("text", "")) if msg else None
if not parsed:
continue
name, args = parsed
chat_id = msg["chat"]["id"]
if name == "start" and args:
try:
send(chat_id, "Добро пожаловать! Вы пришли по ссылке: " + read_start_param(args))
except ValueError:
send(chat_id, "Добро пожаловать! Неизвестный параметр start.")
elif name == "start":
send(chat_id, "Добро пожаловать! Отправьте /help, чтобы узнать, что я умею.")
elif name == "help":
send(chat_id, "/start - запустить бота\n/help - эта справка\n/settings - ваши настройки")
elif name == "settings":
send(chat_id, "Настроек пока нет.")const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const BOT_USERNAME = (await (await fetch(`${API}/getMe`)).json()).result.username;
const COMMAND_RE = /^\/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+([\s\S]*))?$/;
function makeStartLink(payload) {
// base64url в Node без дополнения "=": остаются только A-Z a-z 0-9 _ - (максимум 64 символа)
const code = Buffer.from(payload).toString("base64url");
return `https://t.me/${BOT_USERNAME}?start=${code}`;
}
function readStartParam(code) {
return Buffer.from(code, "base64url").toString("utf8");
}
function parseCommand(text) {
const m = COMMAND_RE.exec(text);
if (!m || (m[2] && m[2].toLowerCase() !== BOT_USERNAME.toLowerCase())) {
return null; // не команда или команда для другого бота
}
return { name: m[1].toLowerCase(), args: (m[3] ?? "").trim() };
}
async function send(chatId, text) {
await fetch(`${API}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ chat_id: chatId, text }),
});
}
console.log("Ссылка для приглашения:", makeStartLink("ref:42"));
let offset = 0;
while (true) {
const resp = await (await fetch(`${API}/getUpdates?offset=${offset}&timeout=30`)).json();
for (const update of resp.result) {
offset = update.update_id + 1;
const msg = update.message;
const parsed = msg ? parseCommand(msg.text ?? "") : null;
if (!parsed) continue;
const { name, args } = parsed;
const chatId = msg.chat.id;
if (name === "start" && args) {
await send(chatId, "Добро пожаловать! Вы пришли по ссылке: " + readStartParam(args));
} else if (name === "start") {
await send(chatId, "Добро пожаловать! Отправьте /help, чтобы узнать, что я умею.");
} else if (name === "help") {
await send(chatId, "/start - запустить бота\n/help - эта справка\n/settings - ваши настройки");
} else if (name === "settings") {
await send(chatId, "Настроек пока нет.");
}
}
}JavaScript-версию сохраните как bot.mjs и запускайте в Node.js 18+ (в ней используется await верхнего уровня). Параметр start — недоверенные данные: ссылку может собрать кто угодно, поэтому не кладите в неё секрет, который сам по себе даёт доступ. getUpdates не работает, пока установлен вебхук; для продакшена см. гайд как настроить вебхук Telegram-бота.
Команды в группах и режим приватности
В группах боты по умолчанию работают в режиме приватности. Тогда они получают команды, явно адресованные им (/command@your_bot), общие команды вроде /start — только если из всех ботов последним в группу писал именно этот, ответы на свои сообщения и служебные сообщения. Если в группе несколько ботов, просите пользователей выбирать команды из списка: так к ним добавляется @your_bot. Чтобы получать все сообщения, сделайте бота администратором или отключите режим приватности командой /setprivacy в @BotFather.
Кнопка меню
В личных чатах кнопка меню рядом с полем ввода по умолчанию открывает список команд. Методом setChatMenuButton её можно переключить на Mini App или вернуть к командам; без chat_id меняется вариант по умолчанию для всех чатов:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button":{"type":"commands"}}'
Другие типы — web_app (с полями text и web_app) и default. С Bot API 10.2 у BotCommand есть ещё поле is_ephemeral: true: такая команда, отправленная в группе, не видна другим участникам и ботам — её получает только ваш бот.
Советы по командам бота
- Держите список коротким. Регистрируйте то, что действительно нужно людям; редкие админские инструменты лучше вынести в область для администраторов.
- Пишите описания через действие. «Создать напоминание» понятнее, чем «Напоминания».
- Задавайте команды при деплое. Вызов
setMyCommandsиз скрипта деплоя держит меню в синхроне с кодом, который эти команды обрабатывает. - Вежливо отвечайте на неизвестные команды в личных чатах, например подсказкой про
/help. - Для выбора используйте кнопки. В многошаговых сценариях инлайн-клавиатура часто удобнее команд с аргументами.
Частые проблемы
| Симптом | Вероятная причина | Что сделать |
|---|---|---|
400 с BOT_COMMAND_INVALID | Заглавные буквы, дефисы, начальный / или больше 32 символов в command | Используйте 1–32 строчные латинские буквы, цифры и подчёркивания, без слэша |
| Команды заданы, но пользователь видит другой список | Приоритет у более узкой области или у списка для языка пользователя | Проверьте каждую область и язык через getMyCommands |
Бот игнорирует /start в группе | Режим приватности, а последним писал другой бот | Отправьте /start@your_bot или измените режим приватности |
| Параметр start не доходит | Символы вне A-Z a-z 0-9 _ - (например, дополнение =) или больше 64 символов | Кодируйте в base64url, убирайте дополнение, сокращайте данные |
401 Unauthorized | Неверный или отозванный токен | См. гайд по токену бота |
Частые вопросы
Как добавить команды в Telegram-бота?
Отправьте /setcommands в @BotFather и выберите бота или вызовите метод Bot API setMyCommands со списком объектов BotCommand. После этого приложения Telegram подсказывают команды, когда пользователь вводит /, и показывают их в меню.
Какие символы можно использовать в команде бота?
В setMyCommands текст команды — от 1 до 32 символов: только строчные латинские буквы, цифры и подчёркивания. Описание — от 1 до 256 символов. В одном списке (для области и языка) — не больше 100 команд.
Как передать параметр в /start?
Через deep link вида https://t.me/your_bot?start=airplane: бот получит сообщение /start airplane. Параметр — до 64 символов из A-Z, a-z, 0-9, _ и -; другие данные кодируйте в base64url.
Почему бот не видит команды в группе?
В режиме приватности (включён по умолчанию) бот в группе получает команды, адресованные ему, например /command@your_bot, а общие вроде /start — только если из всех ботов последним в группе писал именно он. Используйте форму с @your_bot, сделайте бота админом или отключите режим через /setprivacy.
Как показать админам группы отдельные команды?
Вызовите setMyCommands со scope {"type": "all_chat_administrators"} для всех групп или {"type": "chat_administrators", "chat_id": ...} для одной. Права всё равно проверяйте на сервере: в апдейте нет информации об области команды.
Как удалить все команды бота?
Вызовите deleteMyCommands для каждой области и каждого language_code, которые вы задавали. После удаления пользователи увидят следующий по порядку список, например команды по умолчанию.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг
Как задеплоить Telegram-бота: polling или вебхук, сервис systemd на VPS, Docker, Cloudflare Workers с secret_token и чек-лист перед запуском.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить
Ошибки Telegram Bot API с решениями: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 и retry_after. Таблица причин и код обработки.
Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов
Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура
Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.
Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений
Как подключить Telegram к n8n: токен бота в Access Token, вебхук Telegram Trigger по публичному HTTPS, отправка сообщений по chat id и разбор ошибок.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы
Как сделать инлайн-бота Telegram: включить inline mode через @BotFather или setMySettings, обработать inline_query и ответить через answerInlineQuery.
Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки
Приём оплаты в Telegram Stars в боте: sendInvoice с XTR, pre_checkout_query, successful_payment, возвраты, подписки и пример на Python и JS.
Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.