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