Telegram Bot API

Команды Telegram-бота: setMyCommands, области видимости и deep link для /start

· 8 мин чтения

Команды Telegram-бота — это /ключевые_слова вроде /start или /help: приложения Telegram подсвечивают их в сообщениях, подсказывают при вводе / и показывают в меню бота. Список задают командой /setcommands в @BotFather или методом setMyCommands, который умеет ещё и области видимости (свои команды для групп, админов или одного чата) и отдельные списки для разных языков. Сама команда приходит боту обычным текстовым сообщением, а /start может нести параметр из deep link. Ниже — всё это с примерами на curl, Python и JavaScript.

Как устроены команды Telegram-бота

Команда — это просто сообщение, текст которого начинается с /. Регистрация команд не меняет того, что получает бот: она только сообщает приложениям Telegram, что подсказывать. Правила для списка в setMyCommands (объект BotCommand):

Telegram просит всех разработчиков поддерживать глобальные команды /start (начало работы, через неё же приходят параметры deep link) и /help (что умеет бот и список команд), а также /settings, если у бота есть настройки. Конкретные команды вроде /newlocation лучше общей /new, которой нужны дополнительные аргументы.

Команды через @BotFather

Способ без кода, подходит для неизменного списка:

  1. Откройте @BotFather и отправьте /setcommands.
  2. Выберите бота.
  3. Пришлите список — по одной команде в строке в формате команда - описание:
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 работает так:

Бот на 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: такая команда, отправленная в группе, не видна другим участникам и ботам — её получает только ваш бот.

Советы по командам бота

Частые проблемы

СимптомВероятная причинаЧто сделать
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.