Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard
Inline keyboard Telegram là bộ nút gắn vào tin nhắn của bot: bạn truyền object InlineKeyboardMarkup vào tham số reply_markup của sendMessage, và mỗi lần người dùng bấm nút callback, bot nhận một update callback_query mà bạn bắt buộc phải trả lời bằng answerCallbackQuery. Còn reply keyboard (ReplyKeyboardMarkup) thì thay bàn phím chữ của người dùng bằng các câu trả lời định sẵn. Bài này đi qua cả hai loại nút bấm của bot Telegram, mọi kiểu nút, cách sửa tin nhắn sau khi bấm và một ví dụ chạy được hoàn chỉnh bằng Python và JavaScript.
Inline keyboard hay reply keyboard
| Inline keyboard | Reply keyboard | |
|---|---|---|
| Object | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| Hiển thị ở đâu | Dưới một tin nhắn cụ thể | Thay chỗ bàn phím của người dùng |
| Bấm vào thì sao | Callback query, mở URL, Mini App, inline mode, copy văn bản… | Gửi chữ trên nút thành tin nhắn, hoặc chia sẻ liên hệ, vị trí, người dùng, chat |
| Sửa được về sau | Có, bằng editMessageReplyMarkup | Không, gửi bàn phím mới hoặc ẩn đi |
| Kênh | Hỗ trợ | Không hỗ trợ |
Cả hai đều truyền qua cùng tham số reply_markup, cùng với ReplyKeyboardRemove và ForceReply. Mỗi tin nhắn chỉ mang một trong bốn object này.
Gửi inline keyboard Telegram
inline_keyboard là mảng các hàng, mỗi hàng là một mảng nút:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"text": "Chọn một mục:",
"reply_markup": {
"inline_keyboard": [
[{"text": "Thích", "callback_data": "like"}, {"text": "Trợ giúp", "callback_data": "help"}],
[{"text": "Tài liệu Bot API", "url": "https://core.telegram.org/bots/api"}]
]
}
}'
Ngoài text, mỗi nút phải có đúng một trường xác định kiểu nút:
| Trường | Nút làm gì |
|---|---|
callback_data | Gửi callback query chứa chuỗi này tới bot, 1–64 byte |
url | Mở link HTTP hoặc tg:// |
web_app | Mở Mini App; chỉ trong chat riêng giữa người dùng và bot |
login_url | Mở URL HTTPS và đăng nhập người dùng vào website của bạn |
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat | Điền username của bot và một truy vấn vào ô nhập của chat khác, chat hiện tại hoặc chat thuộc loại được chọn |
copy_text | Copy {"text": "…"} (1–256 ký tự) vào clipboard |
pay | Nút thanh toán; chỉ trong tin nhắn hóa đơn, phải là nút đầu tiên của hàng đầu tiên |
callback_game | Mở game; phải là nút đầu tiên của hàng đầu tiên |
disabled | Một DisabledButton không làm gì cả (Bot API 10.3) |
Hai trường tùy chọn thay đổi giao diện nút (Bot API 9.4, dùng được cả cho nút reply keyboard): style với "danger" (đỏ), "success" (xanh lá) hoặc "primary" (xanh dương), và icon_custom_emoji_id để đặt custom emoji trước chữ. Custom emoji chỉ hoạt động nếu bot được phép dùng: bot đã mua username bổ sung trên Fragment, hoặc chủ bot có Telegram Premium và tin nhắn được gửi trực tiếp vào chat riêng, group hoặc supergroup.
Thiết kế callback_data
Giới hạn 64 byte tính theo byte chứ không theo ký tự, nên hãy giữ giá trị ngắn và dễ cho máy đọc, ví dụ like, page:3 hay del:8812, còn dữ liệu thật để trong database. API cũng cảnh báo rằng tin nhắn có thể không còn nút nào mang data bạn nhận được, nên hãy coi nó là dữ liệu người dùng không đáng tin: parse, kiểm tra hợp lệ và xác nhận người dùng có quyền thực hiện thao tác. Giá trị quá dài sẽ bị từ chối ngay khi gửi bàn phím, thường với lỗi Bad Request: BUTTON_DATA_INVALID.
Trả lời mọi lần bấm bằng answerCallbackQuery
Bấm nút callback tạo ra một update có trường callback_query: id, from (người dùng), data và, với tin nhắn do bot gửi, message chứa tin nhắn gốc. Sau khi bấm, client Telegram hiện biểu tượng đang xử lý cho tới khi bot gọi answerCallbackQuery, nên hãy gọi nó mỗi lần, kể cả khi không có tham số nào ngoài id.
| Tham số | Ý nghĩa |
|---|---|
callback_query_id | Bắt buộc, id của callback query |
text | Nội dung thông báo, 0–200 ký tự; bỏ trống thì không hiện gì |
show_alert | true hiện hộp thoại alert thay vì thông báo ở đầu chat |
url | URL game (cho nút callback_game) hoặc link dạng t.me/your_bot?start=XXXX |
cache_time | Số giây client được cache kết quả, mặc định 0 |
Hãy trả lời nhanh: query cũ sẽ lỗi Bad Request: query is too old and response timeout expired or query ID is invalid. Chi tiết xem ở tài liệu answerCallbackQuery.
Sửa tin nhắn sau khi bấm
Cập nhật tin nhắn có sẵn nhanh và gọn hơn gửi tin mới, và Telegram khuyên dùng cách này cho phần cài đặt và phân trang. Lấy chat.id và message_id từ callback_query.message rồi gọi:
editMessageTextđể đổi văn bản, có thể kèmreply_markupmới;editMessageReplyMarkupđể chỉ thay bàn phím; bỏreply_markupđể xóa bàn phím.
Nếu văn bản và bàn phím mới giống hệt hiện tại, API trả về Bad Request: message is not modified, nên hãy so sánh trước khi sửa hoặc bỏ qua riêng lỗi này.
Ví dụ đầy đủ: menu inline với nút callback
Bot này trả lời /start bằng một menu, đếm lượt thích theo từng tin nhắn, hiện alert cho nút Trợ giúp và sửa tin nhắn mỗi khi có thay đổi. Bot dùng long polling getUpdates nên chạy được trên localhost mà không cần webhook. Đặt biến môi trường BOT_TOKEN trước.
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {} # (chat_id, message_id) -> số lượt thích
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"Thích ({count})", "callback_data": "like", "style": "success"},
{"text": "Đặt lại", "callback_data": "reset", "style": "danger"}],
[{"text": "Trợ giúp", "callback_data": "help"},
{"text": "Tài liệu 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="Nút không xác định")
return
if data == "help":
call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
text="Thích để cộng một, Đặt lại để đếm lại từ đầu.")
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="Cảm ơn!" if data == "like" else "Đã đặt lại bộ đếm")
if new != old: # tránh lỗi "message is not modified"
likes[key] = new
call("editMessageText", chat_id=key[0], message_id=key[1],
text=f"Lượt thích: {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="Lượt thích: 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" -> số lượt thích
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: `Thích (${count})`, callback_data: "like", style: "success" },
{ text: "Đặt lại", callback_data: "reset", style: "danger" }],
[{ text: "Trợ giúp", callback_data: "help" },
{ text: "Tài liệu 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: "Nút không xác định" });
return;
}
if (data === "help") {
await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
text: "Thích để cộng một, Đặt lại để đếm lại từ đầu." });
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" ? "Cảm ơn!" : "Đã đặt lại bộ đếm" });
if (next !== old) { // tránh lỗi "message is not modified"
likes.set(key, next);
await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
text: `Lượt thích: ${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: "Lượt thích: 0",
reply_markup: menu(0) });
}
}
}Lưu bản JavaScript thành bot.mjs (vì dùng await ở cấp cao nhất) và chạy bằng Node.js 18+. Bộ đếm nằm trong bộ nhớ; bot thật sẽ lưu vào database. Bỏ các trường style nếu muốn dùng màu nút mặc định.
Reply keyboard trong Telegram
Reply keyboard đưa ra các câu trả lời định sẵn. Nút văn bản thường, cũng có thể viết gọn chỉ bằng một chuỗi, sẽ gửi chữ trên nút vào chat như thể người dùng tự gõ, nên bot xử lý nó như mọi tin nhắn khác:
{
"keyboard": [
["Danh mục", "Giỏ hàng"],
[{"text": "Chia sẻ số điện thoại", "request_contact": true},
{"text": "Gửi vị trí", "request_location": true}]
],
"resize_keyboard": true,
"one_time_keyboard": true,
"input_field_placeholder": "Chọn một mục"
}
| Trường | Tác dụng |
|---|---|
resize_keyboard | Co chiều cao theo số hàng; mặc định bàn phím cao bằng bàn phím chuẩn |
one_time_keyboard | Ẩn bàn phím sau một lần bấm; người dùng mở lại được bằng biểu tượng bàn phím |
is_persistent | Luôn hiện bàn phím khi bàn phím thường bị ẩn |
input_field_placeholder | Chữ gợi ý trong ô nhập, 1–64 ký tự |
selective | Chỉ hiện bàn phím cho người được @nhắc tên hoặc người gửi tin nhắn được reply |
Các nút đặc biệt chỉ hoạt động trong chat riêng: request_contact gửi số điện thoại của người dùng dưới dạng liên hệ, request_location gửi vị trí hiện tại, request_poll mời người dùng tạo poll, và web_app mở Mini App. request_users (KeyboardButtonRequestUsers) và request_chat (KeyboardButtonRequestChat) mở trình chọn và trả kết quả trong tin nhắn hệ thống users_shared và chat_shared; cả hai cần request_id, một số nguyên có dấu 32 bit, duy nhất trong tin nhắn:
{"keyboard": [[
{"text": "Chọn người dùng", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
{"text": "Chọn group của tôi", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}
ReplyKeyboardRemove và ForceReply
Reply keyboard hiển thị cho tới khi bot gửi bàn phím khác. Để ẩn nó, gửi một tin nhắn với {"remove_keyboard": true}. ForceReply, {"force_reply": true, "input_field_placeholder": "Thành phố của bạn"}, mở giao diện trả lời tin nhắn của bot như thể người dùng vừa bấm Reply. Cách này tiện để nhập dữ liệu từng bước trong group, vì câu trả lời vẫn tới bot kể cả khi bật privacy mode. Giống reply keyboard, cả hai object này đều không dùng được trong kênh.
Thử trong Bot API Tester
- Mở sendMessage trong Bot API Tester và nhập token cùng chat id.
- Dán một trong các bàn phím JSON ở trên vào
reply_markuprồi chạy. - Bấm một nút callback trong Telegram, sau đó chạy
getUpdatestrong tester để xem updatecallback_query, và trả lời bằng answerCallbackQuery.
Sửa lỗi nút bấm bot Telegram
| Hiện tượng | Nguyên nhân và cách sửa |
|---|---|
| Biểu tượng đang tải sau khi bấm | Chưa gọi answerCallbackQuery. Hãy trả lời mọi callback query. |
Không nhận được update callback_query | allowed_updates không có callback_query, hoặc tiến trình khác đang lấy update (webhook hoặc instance polling thứ hai). |
BUTTON_DATA_INVALID | callback_data rỗng hoặc dài quá 64 byte. |
message is not modified | Lệnh sửa không làm thay đổi văn bản hay bàn phím. |
query is too old… | Trả lời quá muộn, ví dụ sau khi khởi động lại bot xử lý các update cũ. |
| Nút liên hệ hoặc vị trí không phản hồi trong group | Các nút này chỉ có trong chat riêng. |
Danh sách đầy đủ các thông báo lỗi có trong bài lỗi Telegram Bot API. Định dạng văn bản và các tùy chọn khác của sendMessage có trong bài API gửi tin nhắn Telegram, còn nút chuyển sang inline đi cùng với inline mode.
Câu hỏi thường gặp
Inline keyboard và reply keyboard trong Telegram khác nhau thế nào?
Inline keyboard (InlineKeyboardMarkup) gắn vào một tin nhắn cụ thể; bấm nút không gửi gì vào chat. Reply keyboard (ReplyKeyboardMarkup) thay thế bàn phím chữ của người dùng; nút văn bản đơn giản sẽ gửi chữ trên nút thành một tin nhắn thường.
callback_data dài tối đa bao nhiêu?
1–64 byte. Tính bằng byte chứ không phải ký tự: chữ không phải Latin, kể cả chữ tiếng Việt có dấu, chiếm từ 2 byte trở lên trong UTF-8. Hãy lưu khóa ngắn như item:42 và giữ dữ liệu thật trên server.
Vì sao bấm nút xong nút cứ hiện biểu tượng đang tải?
Bot chưa gọi answerCallbackQuery. Client Telegram hiện thanh tiến trình cho tới khi bạn trả lời, nên hãy gọi method này cho mọi callback query, kể cả khi không có text.
Làm sao đổi các nút sau khi người dùng bấm?
Gọi editMessageReplyMarkup với chat_id và message_id lấy từ callback_query.message để chỉ thay bàn phím, hoặc editMessageText để đổi cả văn bản lẫn bàn phím.
Làm sao ẩn reply keyboard?
Gửi một tin nhắn có reply_markup là {"remove_keyboard": true} (ReplyKeyboardRemove). Nếu chỉ muốn ẩn sau một lần bấm mà vẫn giữ bàn phím để mở lại, hãy dùng one_time_keyboard.
Có thêm nút vào tin nhắn trong kênh được không?
Inline keyboard thì được. Reply keyboard, ReplyKeyboardRemove và ForceReply không được hỗ trợ trong kênh.
Bài viết liên quan
Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên
Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.
Cách deploy bot Telegram: VPS, Docker và hosting serverless
Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.
Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế
Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.
Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục
Giải thích lỗi Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nguyên nhân, cách sửa và code xử lý.
Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn
Giới hạn Telegram Bot API: 30 tin/giây, 1 tin/giây mỗi chat, 20 tin/phút trong group, xử lý lỗi 429 retry_after, dung lượng file và độ dài tin nhắn.
Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start
Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.
Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn
Kết nối n8n với Telegram: dùng token bot làm Access Token, Telegram Trigger cần webhook HTTPS công khai, gửi tin nhắn theo chat id và cách sửa lỗi hay gặp.
API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript
Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.
Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ
Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.
Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n
Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.
Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic
Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.
Bot inline Telegram: cách bật inline mode và trả lời inline query
Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.
Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao
Nhận thanh toán Telegram Stars trong bot: sendInvoice với XTR, pre_checkout_query, successful_payment, hoàn tiền, gói thuê bao và code Python/JS.
Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram
Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.
Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ
Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.
TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn
Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.
Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python
Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.
Widget Telegram: HTML tương tác ngay trong tin nhắn của bot
Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.
Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật
Hướng dẫn test Telegram Mini App: chạy mock trên trình duyệt, localhost qua tunnel HTTPS, môi trường test, DevTools từng nền tảng và xác thực initData.