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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: 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.