Telegram Bot API

Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard

· 9 phút đọc

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 keyboardReply keyboard
ObjectInlineKeyboardMarkupReplyKeyboardMarkup
Hiển thị ở đâuDướ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ì saoCallback 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ề sauCó, bằng editMessageReplyMarkupKhông, gửi bàn phím mới hoặc ẩn đi
KênhHỗ 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ườngNút làm gì
callback_dataGửi callback query chứa chuỗi này tới bot, 1–64 byte
urlMở link HTTP hoặc tg://
web_appMở Mini App; chỉ trong chat riêng giữa người dùng và bot
login_urlMở 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_textCopy {"text": "…"} (1–256 ký tự) vào clipboard
payNú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_gameMở game; phải là nút đầu tiên của hàng đầu tiên
disabledMộ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_idBắt buộc, id của callback query
textNội dung thông báo, 0–200 ký tự; bỏ trống thì không hiện gì
show_alerttrue hiện hộp thoại alert thay vì thông báo ở đầu chat
urlURL game (cho nút callback_game) hoặc link dạng t.me/your_bot?start=XXXX
cache_timeSố 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:

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ườngTác dụng
resize_keyboardCo 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_persistentLuôn hiện bàn phím khi bàn phím thường bị ẩn
input_field_placeholderChữ gợi ý trong ô nhập, 1–64 ký tự
selectiveChỉ 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

  1. Mở sendMessage trong Bot API Tester và nhập token cùng chat id.
  2. Dán một trong các bàn phím JSON ở trên vào reply_markup rồi chạy.
  3. Bấm một nút callback trong Telegram, sau đó chạy getUpdates trong tester để xem update callback_query, và trả lời bằng answerCallbackQuery.

Sửa lỗi nút bấm bot Telegram

Hiện tượngNguyên nhân và cách sửa
Biểu tượng đang tải sau khi bấmChưa gọi answerCallbackQuery. Hãy trả lời mọi callback query.
Không nhận được update callback_queryallowed_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_INVALIDcallback_data rỗng hoặc dài quá 64 byte.
message is not modifiedLệ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 groupCá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.

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.