Telegram Bot API

Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура

· 9 мин чтения

Инлайн-клавиатура Telegram — это набор кнопок, прикреплённых к сообщению бота: вы передаёте объект InlineKeyboardMarkup в параметре reply_markup метода sendMessage, а нажатие на callback-кнопку приносит боту апдейт callback_query, на который нужно ответить методом answerCallbackQuery. Reply-клавиатура (ReplyKeyboardMarkup) работает иначе: она заменяет обычную клавиатуру пользователя готовыми вариантами ответа. В этом гайде — оба вида кнопок телеграм-бота, все типы кнопок, редактирование сообщения после нажатия и полный рабочий пример на Python и JavaScript.

Инлайн-клавиатура или reply-клавиатура

Инлайн-клавиатураReply-клавиатура
ОбъектInlineKeyboardMarkupReplyKeyboardMarkup
Где отображаетсяПод конкретным сообщениемВместо клавиатуры пользователя
Что делает нажатиеCallback query, открывает ссылку, Mini App, инлайн-режим, копирует текст…Отправляет текст кнопки сообщением или делится контактом, геопозицией, пользователями, чатом
Можно изменить позжеДа, через editMessageReplyMarkupНет, только отправить новую или убрать
КаналыПоддерживаетсяНе поддерживается

Обе клавиатуры передаются в один и тот же параметр reply_markup, как и ReplyKeyboardRemove и ForceReply. У сообщения может быть только один из этих четырёх объектов.

Как отправить инлайн-клавиатуру Telegram

inline_keyboard — это массив рядов, каждый ряд — массив кнопок:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Выберите вариант:",
    "reply_markup": {
      "inline_keyboard": [
        [{"text": "Нравится", "callback_data": "like"}, {"text": "Помощь", "callback_data": "help"}],
        [{"text": "Документация Bot API", "url": "https://core.telegram.org/bots/api"}]
      ]
    }
  }'

Кроме text, у каждой кнопки должно быть ровно одно поле, задающее её тип:

ПолеЧто делает кнопка
callback_dataОтправляет боту callback query с этой строкой, 1–64 байта
urlОткрывает HTTP- или tg://-ссылку
web_appЗапускает Mini App; только в личном чате пользователя с ботом
login_urlОткрывает HTTPS-адрес и авторизует пользователя на вашем сайте
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chatВставляет username бота и запрос в поле ввода другого чата, текущего чата или чата выбранного типа
copy_textКопирует {"text": "…"} (1–256 символов) в буфер обмена
payКнопка оплаты; только в сообщениях-счетах, должна быть первой в первом ряду
callback_gameЗапускает игру; должна быть первой в первом ряду
disabledDisabledButton — неактивная кнопка, которая ничего не делает (Bot API 10.3)

Два необязательных поля меняют внешний вид кнопки (Bot API 9.4, работают и на кнопках reply-клавиатуры): style со значением "danger" (красная), "success" (зелёная) или "primary" (синяя) и icon_custom_emoji_id — кастомный эмодзи перед текстом. Кастомные эмодзи доступны, только если бот вообще может их использовать: он купил дополнительные юзернеймы на Fragment или у его владельца есть Telegram Premium и сообщение отправлено напрямую в личный чат, группу или супергруппу.

Как проектировать callback_data

Лимит в 64 байта считается в байтах, а не в символах, поэтому делайте значения короткими и машиночитаемыми, например like, page:3 или del:8812, а настоящие данные храните в базе. В документации отдельно предупреждают: в сообщении может не оказаться кнопки с полученным data, так что относитесь к нему как к недоверенному вводу — разбирайте, проверяйте и убеждайтесь, что пользователь вправе выполнить действие. Слишком длинное значение отклоняется уже при отправке клавиатуры, обычно с ошибкой Bad Request: BUTTON_DATA_INVALID.

Отвечайте на каждое нажатие через answerCallbackQuery

Нажатие на callback-кнопку порождает апдейт с полем callback_query: id, from (пользователь), data и, для сообщений, отправленных ботом, message с исходным сообщением. После нажатия клиенты Telegram показывают индикатор загрузки, пока бот не вызовет answerCallbackQuery, поэтому вызывайте его всегда, даже без параметров, кроме id.

ПараметрНазначение
callback_query_idОбязательный, id callback query
textТекст уведомления, 0–200 символов; если не указан, ничего не показывается
show_alerttrue — показать алерт вместо уведомления вверху чата
urlURL игры (для кнопок callback_game) или ссылка вида t.me/your_bot?start=XXXX
cache_timeСколько секунд результат может кешироваться на клиенте, по умолчанию 0

Отвечайте быстро: на устаревший запрос API вернёт Bad Request: query is too old and response timeout expired or query ID is invalid. Подробности — в справочнике answerCallbackQuery.

Редактирование сообщения после нажатия

Изменить существующее сообщение быстрее и аккуратнее, чем отправлять новое, — Telegram рекомендует так делать для настроек и пагинации. Возьмите chat.id и message_id из callback_query.message и вызовите:

Если новый текст и клавиатура совпадают с текущими, API вернёт Bad Request: message is not modified, поэтому сравнивайте перед редактированием или игнорируйте именно эту ошибку.

Полный пример: инлайн-меню с callback-кнопками

Бот отвечает на /start меню, считает лайки для каждого сообщения, показывает алерт по кнопке «Помощь» и редактирует сообщение при каждом изменении. Он работает через long polling getUpdates, поэтому запускается на localhost без вебхука. Сначала задайте переменную окружения BOT_TOKEN.

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {}  # (chat_id, message_id) -> число лайков


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def menu(count):
    return {"inline_keyboard": [
        [{"text": f"Нравится ({count})", "callback_data": "like", "style": "success"},
         {"text": "Сбросить", "callback_data": "reset", "style": "danger"}],
        [{"text": "Помощь", "callback_data": "help"},
         {"text": "Документация Bot API", "url": "https://core.telegram.org/bots/api"}],
    ]}


def on_callback(cq):
    msg, data = cq.get("message"), cq.get("data")
    if not msg or data not in ("like", "reset", "help"):
        call("answerCallbackQuery", callback_query_id=cq["id"], text="Неизвестная кнопка")
        return
    if data == "help":
        call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
             text="«Нравится» добавляет лайк, «Сбросить» обнуляет счётчик.")
        return
    key = (msg["chat"]["id"], msg["message_id"])
    old = likes.get(key, 0)
    new = old + 1 if data == "like" else 0
    call("answerCallbackQuery", callback_query_id=cq["id"],
         text="Спасибо!" if data == "like" else "Счётчик сброшен")
    if new != old:  # избегаем "message is not modified"
        likes[key] = new
        call("editMessageText", chat_id=key[0], message_id=key[1],
             text=f"Лайков: {new}", reply_markup=menu(new))


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "callback_query"])
    for update in updates:
        offset = update["update_id"] + 1
        if "callback_query" in update:
            on_callback(update["callback_query"])
        elif update.get("message", {}).get("text") == "/start":
            chat_id = update["message"]["chat"]["id"]
            call("sendMessage", chat_id=chat_id, text="Лайков: 0", reply_markup=menu(0))
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const likes = new Map(); // "chatId:messageId" -> число лайков

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

function menu(count) {
  return { inline_keyboard: [
    [{ text: `Нравится (${count})`, callback_data: "like", style: "success" },
     { text: "Сбросить", callback_data: "reset", style: "danger" }],
    [{ text: "Помощь", callback_data: "help" },
     { text: "Документация Bot API", url: "https://core.telegram.org/bots/api" }],
  ] };
}

async function onCallback(cq) {
  const msg = cq.message;
  const data = cq.data;
  if (!msg || !["like", "reset", "help"].includes(data)) {
    await call("answerCallbackQuery", { callback_query_id: cq.id, text: "Неизвестная кнопка" });
    return;
  }
  if (data === "help") {
    await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
      text: "«Нравится» добавляет лайк, «Сбросить» обнуляет счётчик." });
    return;
  }
  const key = `${msg.chat.id}:${msg.message_id}`;
  const old = likes.get(key) ?? 0;
  const next = data === "like" ? old + 1 : 0;
  await call("answerCallbackQuery", { callback_query_id: cq.id,
    text: data === "like" ? "Спасибо!" : "Счётчик сброшен" });
  if (next !== old) { // избегаем "message is not modified"
    likes.set(key, next);
    await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
      text: `Лайков: ${next}`, reply_markup: menu(next) });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", { offset, timeout: 30,
    allowed_updates: ["message", "callback_query"] });
  for (const update of updates) {
    offset = update.update_id + 1;
    if (update.callback_query) {
      await onCallback(update.callback_query);
    } else if (update.message?.text === "/start") {
      await call("sendMessage", { chat_id: update.message.chat.id, text: "Лайков: 0",
        reply_markup: menu(0) });
    }
  }
}

Сохраните JavaScript-версию как bot.mjs (в ней используется top-level await) и запустите в Node.js 18+. Счётчик хранится в памяти; в настоящем боте его место — в базе данных. Уберите поля style, если нужны стандартные цвета кнопок.

Reply-клавиатура в Telegram

Reply-клавиатура предлагает готовые ответы. Простая текстовая кнопка (её можно записать и просто строкой) отправляет свой текст в чат так, будто пользователь набрал его сам, и бот обрабатывает его как обычное сообщение:

{
  "keyboard": [
    ["Каталог", "Корзина"],
    [{"text": "Отправить телефон", "request_contact": true},
     {"text": "Отправить геопозицию", "request_location": true}]
  ],
  "resize_keyboard": true,
  "one_time_keyboard": true,
  "input_field_placeholder": "Выберите раздел"
}
ПолеЭффект
resize_keyboardПодгоняет высоту под число рядов; по умолчанию клавиатура такой же высоты, как стандартная
one_time_keyboardСкрывает клавиатуру после нажатия; пользователь может снова открыть её значком клавиатуры
is_persistentВсегда показывает клавиатуру, когда обычная клавиатура скрыта
input_field_placeholderПодсказка в поле ввода, 1–64 символа
selectiveПоказывает клавиатуру только упомянутым пользователям или автору сообщения, на которое отвечает бот

Специальные кнопки работают только в личных чатах: request_contact отправляет номер телефона пользователя как контакт, request_location — его текущую геопозицию, request_poll предлагает создать опрос, web_app запускает Mini App. request_users (KeyboardButtonRequestUsers) и request_chat (KeyboardButtonRequestChat) открывают окно выбора и возвращают результат в служебных сообщениях users_shared и chat_shared; обоим нужен request_id — знаковое 32-битное число, уникальное в пределах сообщения:

{"keyboard": [[
  {"text": "Выбрать пользователя", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
  {"text": "Выбрать мою группу", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}

ReplyKeyboardRemove и ForceReply

Reply-клавиатура остаётся на экране, пока бот не пришлёт другую. Чтобы убрать её, отправьте сообщение с {"remove_keyboard": true}. ForceReply — {"force_reply": true, "input_field_placeholder": "Ваш город"} — открывает интерфейс ответа на сообщение бота, как если бы пользователь нажал «Ответить». Это удобно для пошагового ввода в группах: ответ дойдёт до бота даже при включённом режиме приватности. Как и reply-клавиатура, оба объекта не работают в каналах.

Попробуйте в Bot API Tester

  1. Откройте sendMessage в Bot API Tester и укажите токен и chat id.
  2. Вставьте одну из JSON-клавиатур выше в reply_markup и выполните запрос.
  3. Нажмите callback-кнопку в Telegram, затем выполните в тестере getUpdates, чтобы увидеть апдейт callback_query, и ответьте на него через answerCallbackQuery.

Частые проблемы с кнопками телеграм-бота

СимптомПричина и решение
После нажатия крутится индикатор загрузкиНет вызова answerCallbackQuery. Отвечайте на каждый callback query.
Не приходят апдейты callback_queryВ allowed_updates нет callback_query, или апдейты забирает другой процесс (вебхук или второй экземпляр с polling).
BUTTON_DATA_INVALIDcallback_data пустое или длиннее 64 байт.
message is not modifiedРедактирование не меняет ни текст, ни клавиатуру.
query is too old…Ответ пришёл слишком поздно, например после перезапуска бот обработал старые апдейты.
Кнопка контакта или геопозиции не работает в группеТакие кнопки доступны только в личных чатах.

Полный список сообщений об ошибках — в гайде ошибки Telegram Bot API. Форматирование и другие параметры sendMessage разобраны в гайде как отправить сообщение через Bot API, а кнопки переключения в инлайн-режим пригодятся вместе с инлайн-ботом.

Частые вопросы

Чем инлайн-клавиатура отличается от reply-клавиатуры в Telegram?

Инлайн-клавиатура (InlineKeyboardMarkup) прикреплена к конкретному сообщению, и нажатие на её кнопки ничего не отправляет в чат. Reply-клавиатура (ReplyKeyboardMarkup) заменяет обычную клавиатуру пользователя; простая текстовая кнопка отправляет свой текст как обычное сообщение.

Какой максимальный размер callback_data?

1–64 байта. Именно байта, а не символа: кириллица в UTF-8 занимает 2 байта на букву. Храните в кнопке короткие ключи вроде item:42, а сами данные — на сервере.

Почему после нажатия на кнопку крутится индикатор загрузки?

Бот не вызвал answerCallbackQuery. Клиенты Telegram показывают индикатор, пока бот не ответит, поэтому отвечайте на каждый callback query, даже без text.

Как изменить кнопки после нажатия?

Вызовите editMessageReplyMarkup с chat_id и message_id из callback_query.message, чтобы заменить только клавиатуру, или editMessageText, чтобы поменять текст и клавиатуру сразу.

Как убрать reply-клавиатуру?

Отправьте сообщение с reply_markup равным {"remove_keyboard": true} (ReplyKeyboardRemove). Если нужно лишь скрыть её после одного нажатия, оставив доступной, используйте one_time_keyboard.

Можно ли добавить кнопки к сообщениям в канале?

Инлайн-клавиатуру — да. Reply-клавиатура, ReplyKeyboardRemove и ForceReply в каналах не поддерживаются.

Как создать бота в Телеграм: от @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-бота: setMyCommands, области видимости и deep link для /start

Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.

Интеграция 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.