Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура
Инлайн-клавиатура Telegram — это набор кнопок, прикреплённых к сообщению бота: вы передаёте объект InlineKeyboardMarkup в параметре reply_markup метода sendMessage, а нажатие на callback-кнопку приносит боту апдейт callback_query, на который нужно ответить методом answerCallbackQuery. Reply-клавиатура (ReplyKeyboardMarkup) работает иначе: она заменяет обычную клавиатуру пользователя готовыми вариантами ответа. В этом гайде — оба вида кнопок телеграм-бота, все типы кнопок, редактирование сообщения после нажатия и полный рабочий пример на Python и JavaScript.
Инлайн-клавиатура или reply-клавиатура
| Инлайн-клавиатура | Reply-клавиатура | |
|---|---|---|
| Объект | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| Где отображается | Под конкретным сообщением | Вместо клавиатуры пользователя |
| Что делает нажатие | 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 | Запускает игру; должна быть первой в первом ряду |
disabled | DisabledButton — неактивная кнопка, которая ничего не делает (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_alert | true — показать алерт вместо уведомления вверху чата |
url | URL игры (для кнопок 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 и вызовите:
editMessageText— чтобы изменить текст, при необходимости с новымreply_markup;editMessageReplyMarkup— чтобы заменить только клавиатуру; безreply_markupклавиатура удаляется.
Если новый текст и клавиатура совпадают с текущими, 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
- Откройте sendMessage в Bot API Tester и укажите токен и chat id.
- Вставьте одну из JSON-клавиатур выше в
reply_markupи выполните запрос. - Нажмите callback-кнопку в Telegram, затем выполните в тестере
getUpdates, чтобы увидеть апдейтcallback_query, и ответьте на него через answerCallbackQuery.
Частые проблемы с кнопками телеграм-бота
| Симптом | Причина и решение |
|---|---|
| После нажатия крутится индикатор загрузки | Нет вызова answerCallbackQuery. Отвечайте на каждый callback query. |
Не приходят апдейты callback_query | В allowed_updates нет callback_query, или апдейты забирает другой процесс (вебхук или второй экземпляр с polling). |
BUTTON_DATA_INVALID | callback_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.