Команди 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через 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.