Bot inline Telegram: cách bật inline mode và trả lời inline query
Bot inline Telegram trả lời truy vấn gõ ngay trong ô soạn tin: người dùng viết @your_bot kèm nội dung ở bất kỳ chat nào, bot nhận update inline_query và trả lời bằng answerInlineQuery, rồi người dùng chạm vào một kết quả để gửi đi. Để làm bot như vậy, bạn bật inline mode (bằng /setinline trong @BotFather hoặc, từ Bot API 10.5, bằng setMySettings), xử lý update inline_query và trả về tối đa 50 kết quả. Dưới đây là từng bước cùng ví dụ hoàn chỉnh bằng Python và JavaScript.
Inline mode hoạt động thế nào
Inline mode dùng được ở mọi chat, kể cả nơi bot không phải thành viên. Luồng xử lý:
- Người dùng gõ username của bot và truy vấn vào ô nhập, ví dụ
@your_bot hello. Lúc này chưa có gì được gửi vào chat. - Bot nhận update
inline_query. - Bot gọi
answerInlineQueryvới danh sách kết quả: bài viết (article), ảnh, GIF, video, sticker, vị trí và nhiều loại khác. - Người dùng chạm vào một kết quả. Tin nhắn được gửi bởi người dùng, username của bot hiện cạnh tên người gửi; trong Bot API, tin nhắn này có trường
via_bot. - Tùy chọn: bot nhận update
chosen_inline_resultcho biết kết quả nào đã được gửi.
Bật inline mode cho bot Telegram
Bot mới tạo mặc định tắt inline mode. Nếu chưa có bot, hãy bắt đầu với bài cách tạo bot Telegram. Sau đó chọn một trong hai cách.
Cách 1: @BotFather
- Gửi
/setinlinecho @BotFather và chọn bot. - Nhập placeholder mà người dùng thấy trong ô nhập sau khi gõ username của bot, ví dụ Nhập văn bản để định dạng…
- Tùy chọn:
/setinlinegeoyêu cầu vị trí người dùng kèm mỗi truy vấn;/setinlinefeedbackbật updatechosen_inline_result.
Cách 2: setMySettings (Bot API 10.5)
Từ Bot API 10.5, bot có thể tự đổi thiết lập của mình bằng setMySettings. Thiết lập nào không truyền sẽ giữ nguyên:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMySettings" \
-H "Content-Type: application/json" \
-d '{"supports_inline_queries": true, "inline_query_placeholder": "Nhập văn bản để định dạng…", "inline_feedback_share_denominator": 1}'
Các tham số liên quan đến inline:
supports_inline_queries—truebật inline mode,falsetắt.inline_query_placeholder— văn bản placeholder; chuỗi rỗng sẽ khôi phục placeholder mặc định.needs_inline_query_location— yêu cầu vị trí người dùng kèm mỗi inline query.inline_feedback_share_denominator— nhận 1 trên N kết quả được chọn; chỉ nhận giá trị 1, 10, 100 hoặc 1000, còn0sẽ ngừng gửi updatechosen_inline_result.
Muốn kiểm tra mà không cần viết code, mở setMySettings trong Bot API Tester, dán token và chạy, sau đó gọi getMe: kết quả BotFullInfo có supports_inline_queries và, nếu bạn đặt placeholder riêng, cả inline_query_placeholder.
Update inline_query
Trong lúc người dùng gõ, bot nhận các object InlineQuery với những trường sau:
| Trường | Ý nghĩa |
|---|---|
id | ID duy nhất của truy vấn; truyền vào answerInlineQuery dưới dạng inline_query_id |
from | Người dùng đã gõ truy vấn |
query | Nội dung truy vấn, tối đa 256 ký tự; có thể rỗng — khi đó hãy trả kết quả mặc định hoặc nổi bật |
offset | Vị trí bắt đầu của trang kết quả cần trả; do bot điều khiển qua next_offset |
chat_type | Tùy chọn: sender (chat riêng với người gửi truy vấn), private, group, supergroup hoặc channel; với secret chat thường không xác định |
location | Tùy chọn; chỉ có khi bot yêu cầu vị trí người dùng |
Nếu bạn truyền allowed_updates cho getUpdates hoặc setWebhook, nhớ thêm inline_query (và chosen_inline_result nếu cần), nếu không các update này sẽ không đến.
Tham số của answerInlineQuery
answerInlineQuery trả về True khi thành công. Mỗi truy vấn được trả không quá 50 kết quả.
| Tham số | Mô tả |
|---|---|
inline_query_id | Bắt buộc. id của truy vấn |
results | Bắt buộc. Mảng các object InlineQueryResult (≤ 50) |
cache_time | Thời gian tối đa (giây) kết quả được cache trên server; mặc định 300 |
is_personal | true chỉ cache kết quả cho người dùng này; mặc định bất kỳ ai gửi cùng truy vấn đều có thể nhận lại kết quả đó |
next_offset | Offset mà client gửi kèm truy vấn tiếp theo với cùng nội dung; chuỗi rỗng nếu hết kết quả; tối đa 64 byte |
button | InlineQueryResultsButton hiển thị phía trên danh sách kết quả |
Các loại kết quả inline
Client Telegram hỗ trợ 20 loại kết quả. Mười hai loại mô tả nội dung mới (article, photo, gif, mpeg4_gif, video, audio, voice, document, location, venue, contact, game), tám loại InlineQueryResultCached… dùng lại file đã có trên server Telegram qua file_id. Mỗi kết quả cần có type và id dài 1–64 byte. Hai loại hay dùng nhất:
- article — bắt buộc
titlevàinput_message_content; tùy chọndescription,url,thumbnail_url,reply_markup. Nội dung thường làInputTextMessageContentvớimessage_text(1–4096 ký tự) vàparse_modenếu cần. - photo — bắt buộc
photo_url(JPEG, tối đa 5 MB) vàthumbnail_url; tùy chọncaption(0–1024 ký tự),title,description.
Mọi URL trong kết quả inline đều hiện ra với người dùng cuối, nên hãy coi chúng là công khai. Quy tắc định dạng parse_mode giống hệt khi gửi tin nhắn qua Bot API.
Ví dụ: bot inline bằng Python và JavaScript
Bot này định dạng truy vấn thành chữ đậm, nghiêng hoặc monospace. Với truy vấn rỗng, bot hiện một nút mở chat riêng, ở đó /start trả lời kèm các nút để quay lại inline mode. Đặt biến môi trường BOT_TOKEN trước khi chạy.
import html
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
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 article(result_id, title, text, message_html):
return {
"type": "article",
"id": result_id, # 1-64 byte, không trùng trong một lần trả lời
"title": title,
"description": text[:100],
"input_message_content": {"message_text": message_html, "parse_mode": "HTML"},
}
def on_inline_query(query):
text = query["query"].strip()
if not text: # truy vấn rỗng: không có kết quả, chỉ có nút mở chat riêng
call("answerInlineQuery", inline_query_id=query["id"], results=[], cache_time=5,
button={"text": "Cách dùng bot này", "start_parameter": "help"})
return
safe = html.escape(text)
results = [
article("bold", "Chữ đậm", text, f"<b>{safe}</b>"),
article("italic", "Chữ nghiêng", text, f"<i>{safe}</i>"),
article("mono", "Monospace", text, f"<code>{safe}</code>"),
]
call("answerInlineQuery", inline_query_id=query["id"], results=results, cache_time=5)
def on_message(msg):
if msg.get("text", "").startswith("/start"): # kể cả "/start help" từ nút bấm
call("sendMessage", chat_id=msg["chat"]["id"],
text="Gõ username của tôi kèm văn bản ở bất kỳ chat nào để định dạng.",
reply_markup={"inline_keyboard": [[
{"text": "Thử ngay tại đây", "switch_inline_query_current_chat": "Hello"},
{"text": "Chọn chat", "switch_inline_query": "Hello"},
]]})
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "inline_query", "chosen_inline_result"])
for update in updates:
offset = update["update_id"] + 1
try:
if "inline_query" in update:
on_inline_query(update["inline_query"])
elif "chosen_inline_result" in update:
chosen = update["chosen_inline_result"]
print("chosen:", chosen["result_id"], "for query:", chosen["query"])
elif "message" in update:
on_message(update["message"])
except RuntimeError as err:
print(err)const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
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;
}
const escapeHtml = (s) => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
function article(id, title, text, messageHtml) {
return {
type: "article",
id, // 1-64 byte, không trùng trong một lần trả lời
title,
description: text.slice(0, 100),
input_message_content: { message_text: messageHtml, parse_mode: "HTML" },
};
}
async function onInlineQuery(query) {
const text = query.query.trim();
if (!text) { // truy vấn rỗng: không có kết quả, chỉ có nút mở chat riêng
await call("answerInlineQuery", {
inline_query_id: query.id, results: [], cache_time: 5,
button: { text: "Cách dùng bot này", start_parameter: "help" },
});
return;
}
const safe = escapeHtml(text);
const results = [
article("bold", "Chữ đậm", text, `<b>${safe}</b>`),
article("italic", "Chữ nghiêng", text, `<i>${safe}</i>`),
article("mono", "Monospace", text, `<code>${safe}</code>`),
];
await call("answerInlineQuery", { inline_query_id: query.id, results, cache_time: 5 });
}
async function onMessage(msg) {
if (msg.text?.startsWith("/start")) { // kể cả "/start help" từ nút bấm
await call("sendMessage", {
chat_id: msg.chat.id,
text: "Gõ username của tôi kèm văn bản ở bất kỳ chat nào để định dạng.",
reply_markup: { inline_keyboard: [[
{ text: "Thử ngay tại đây", switch_inline_query_current_chat: "Hello" },
{ text: "Chọn chat", switch_inline_query: "Hello" },
]] },
});
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: 30, allowed_updates: ["message", "inline_query", "chosen_inline_result"],
});
for (const update of updates) {
offset = update.update_id + 1;
try {
if (update.inline_query) await onInlineQuery(update.inline_query);
else if (update.chosen_inline_result) {
const chosen = update.chosen_inline_result;
console.log("chosen:", chosen.result_id, "for query:", chosen.query);
} else if (update.message) await onMessage(update.message);
} catch (err) {
console.error(err.message);
}
}
}Lưu bản JavaScript thành bot.mjs và chạy bằng Node.js 18+, sau đó gõ @your_bot hello ở bất kỳ chat nào. Các handler này cũng chạy được với webhook — xem bài cài webhook Telegram bot.
Phân trang bằng next_offset
Có hơn 50 kết quả phù hợp? Hãy trả theo trang: ở request đầu tiên offset rỗng, và next_offset của bạn sẽ được gửi lại khi người dùng cuộn xuống:
PAGE_SIZE = 20 # answerInlineQuery nhận tối đa 50 kết quả
def answer_page(query, items):
start = int(query["offset"] or 0) # ở request đầu tiên offset là ""
page = items[start:start + PAGE_SIZE]
more = start + PAGE_SIZE < len(items)
call("answerInlineQuery", inline_query_id=query["id"], results=page,
next_offset=str(start + PAGE_SIZE) if more else "") # "" = hết kết quảconst PAGE_SIZE = 20; // answerInlineQuery nhận tối đa 50 kết quả
async function answerPage(query, items) {
const start = Number(query.offset || 0); // ở request đầu tiên offset là ""
const page = items.slice(start, start + PAGE_SIZE);
const more = start + PAGE_SIZE < items.length;
await call("answerInlineQuery", {
inline_query_id: query.id, results: page,
next_offset: more ? String(start + PAGE_SIZE) : "", // "" = hết kết quả
});
}chosen_inline_result và inline feedback
Khi bật feedback, bot nhận object ChosenInlineResult gồm result_id, from, query, location (tùy chọn) và inline_message_id (tùy chọn). Do có cache, bot đông người dùng có thể nhận số kết quả được chọn nhiều hơn số truy vấn thực tế, nên khi tải cao chỉ nên nhận 1/10, 1/100 hoặc 1/1000.
inline_message_id chỉ có khi tin nhắn được gửi có inline keyboard. Hãy lưu lại để sau này sửa tin nhắn bằng editMessageText (truyền inline_message_id thay cho chat_id và message_id); lượt bấm nút trên tin nhắn đó đến dưới dạng callback_query với cùng inline_message_id.
Nút phía trên kết quả và quay lại chat
Tham số button hiển thị một InlineQueryResultsButton phía trên danh sách kết quả (hoặc thay cho chúng). Nút có text và đúng một trong hai trường:
start_parameter— mở chat riêng với bot và gửi/start <parameter>; 1–64 ký tự, chỉ gồmA-Z,a-z,0-9,_và-.web_app— mở một Mini App; Mini App có thể quay lại inline mode bằngswitchInlineQuery.
Cách dùng điển hình: yêu cầu người dùng liên kết tài khoản trước, sau đó gửi inline keyboard có nút switch_inline_query (người dùng chọn chat), switch_inline_query_current_chat (chèn @your_bot query vào chat hiện tại) hoặc switch_inline_query_chosen_chat (giới hạn lựa chọn trong người dùng, bot, nhóm hoặc kênh).
Xử lý sự cố
| Triệu chứng | Nguyên nhân thường gặp và cách sửa |
|---|---|
Gõ @your_bot mà không có gì xảy ra | Chưa bật inline mode: dùng /setinline hoặc setMySettings. |
Không nhận được update inline_query | Trước đó đã đặt allowed_updates mà thiếu inline_query (danh sách này được ghi nhớ), hoặc webhook đang bật nên getUpdates trả về 409 Conflict. |
| Vẫn hiện kết quả cũ | Cache phía server: giảm cache_time (mặc định 300 giây) và dùng is_personal cho kết quả theo từng người dùng. |
400 Bad Request: query is too old and response timeout expired or query ID is invalid | Trả lời quá muộn hoặc sai ID. Hãy trả lời ngay, việc chậm thì xử lý ở nền. |
Không có chosen_inline_result | Inline feedback đang tắt: dùng /setinlinefeedback hoặc inline_feedback_share_denominator. |
| Kết quả ảnh không hiện | photo_url phải là ảnh JPEG công khai tối đa 5 MB, và bắt buộc có thumbnail_url. |
Bot inline có nhiều người dùng cũng cần tuân thủ giới hạn của Telegram Bot API.
Câu hỏi thường gặp
Làm sao bật inline mode cho bot Telegram?
Gửi /setinline cho @BotFather, chọn bot và nhập placeholder. Từ Bot API 10.5, bot cũng có thể tự bật bằng setMySettings với supports_inline_queries: true (kèm inline_query_placeholder nếu muốn).
answerInlineQuery trả về được tối đa bao nhiêu kết quả?
Không quá 50 kết quả mỗi lần gọi. Danh sách dài hơn thì trả từng trang và truyền next_offset (tối đa 64 byte); client sẽ gửi lại giá trị này trong offset khi người dùng cuộn xuống.
Vì sao sửa code rồi mà kết quả inline vẫn không đổi?
Kết quả có thể được cache trên server Telegram trong cache_time giây, mặc định 300. Khi phát triển hãy đặt cache_time nhỏ, và dùng is_personal: true nếu kết quả phụ thuộc vào người dùng.
Bot inline có cần được thêm vào chat không?
Không. Người dùng gõ username của bot và nội dung truy vấn vào ô nhập của bất kỳ chat nào; bot nhận update inline_query, còn kết quả được chọn do chính người dùng gửi, kèm username của bot (via_bot).
Làm sao biết người dùng đã gửi kết quả inline nào?
Bật inline feedback bằng /setinlinefeedback trong @BotFather hoặc inline_feedback_share_denominator trong setMySettings (1, 10, 100 hoặc 1000). Khi đó bot nhận update chosen_inline_result với result_id và query.
Vì sao chosen_inline_result không có inline_message_id?
Trường này chỉ có khi tin nhắn được gửi có gắn inline keyboard. Hãy thêm reply_markup vào kết quả nếu muốn sửa tin nhắn sau này hoặc nhận callback query từ nó.
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.
Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard
Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.
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.
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.