Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询
Telegram 内联机器人(inline bot)直接响应用户在输入框里敲的查询:用户在任意聊天中输入 @your_bot 加一段文字,机器人收到 inline_query 更新,用 answerInlineQuery 返回结果列表,用户点一下其中一条就发送出去。实现步骤很简单:开启 Inline 模式(在 @BotFather 中用 /setinline,或从 Bot API 10.5 起调用 setMySettings),处理 inline_query 更新,并返回最多 50 条结果。下面逐步讲解,最后附上完整的 Python 和 JavaScript 示例。
Inline 模式的工作原理
Inline 模式在任何聊天中都能用,即使机器人并不是该聊天的成员。整体流程如下:
- 用户在输入框里输入机器人用户名和查询内容,例如
@your_bot hello。此时聊天中还没有发送任何内容。 - 机器人收到一个
inline_query更新。 - 机器人调用
answerInlineQuery返回结果列表:文章、图片、GIF、视频、贴纸、位置等。 - 用户点击某条结果。消息以用户本人的身份发出,发送者名字旁边会显示机器人的用户名;在 Bot API 中,这类消息带有
via_bot字段。 - (可选)机器人收到
chosen_inline_result更新,得知用户发送了哪条结果。
为 Telegram 机器人开启 Inline 模式
新建的机器人默认关闭 Inline 模式。还没有机器人的话,请先阅读创建 Telegram 机器人教程。之后任选以下一种方式。
方式一:通过 @BotFather
- 向 @BotFather 发送
/setinline,选择你的机器人。 - 输入占位提示文字,用户输入机器人用户名后会在输入框里看到它,例如 输入要格式化的文字…
- 可选:
/setinlinegeo让每次查询都请求用户位置;/setinlinefeedback开启chosen_inline_result更新。
方式二:调用 setMySettings(Bot API 10.5)
从 Bot API 10.5 起,机器人可以用 setMySettings 修改自己的设置。没有传入的设置项保持不变:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMySettings" \
-H "Content-Type: application/json" \
-d '{"supports_inline_queries": true, "inline_query_placeholder": "输入要格式化的文字…", "inline_feedback_share_denominator": 1}'
与 Inline 相关的参数:
supports_inline_queries——true开启 Inline 模式,false关闭。inline_query_placeholder—— 占位提示文字;传空字符串恢复默认值。needs_inline_query_location—— 每次内联查询都请求用户位置。inline_feedback_share_denominator—— 每 N 条被选中的结果接收 1 条;只能是 1、10、100 或 1000,传0则停止推送chosen_inline_result。
不写代码也能验证:在 Bot API Tester 中打开 setMySettings,填入 Token 并执行,然后调用 getMe:返回的 BotFullInfo 中包含 supports_inline_queries,如果设置了自定义占位文字,还会有 inline_query_placeholder。
inline_query 更新
用户输入时,机器人会收到 InlineQuery 对象,字段如下:
| 字段 | 含义 |
|---|---|
id | 查询的唯一 ID,作为 inline_query_id 传给 answerInlineQuery |
from | 输入查询的用户 |
query | 查询文本,最多 256 个字符;可能为空,此时可返回默认或热门结果 |
offset | 要返回的结果偏移量,由机器人通过 next_offset 控制 |
chat_type | 可选:sender(与查询发起人的私聊)、private、group、supergroup 或 channel;私密聊天中通常未知 |
location | 可选;仅当机器人请求用户位置时才有 |
如果在 getUpdates 或 setWebhook 中传了 allowed_updates,记得包含 inline_query(需要的话再加 chosen_inline_result),否则收不到这些更新。
answerInlineQuery 参数
answerInlineQuery 成功时返回 True。每次查询最多返回 50 条结果。
| 参数 | 说明 |
|---|---|
inline_query_id | 必填。查询的 id |
results | 必填。InlineQueryResult 对象数组(≤ 50) |
cache_time | 结果在服务器上缓存的最长秒数,默认 300 |
is_personal | true 表示只为当前用户缓存;默认情况下,发送相同查询的任何用户都可能拿到这份结果 |
next_offset | 客户端在下一次相同文本的查询中带回的偏移量;没有更多结果时传空字符串;最多 64 字节 |
button | 显示在结果上方的 InlineQueryResultsButton |
内联结果类型
Telegram 客户端支持 20 种结果类型。其中 12 种用于新内容(article、photo、gif、mpeg4_gif、video、audio、voice、document、location、venue、contact、game),另外 8 种 InlineQueryResultCached… 通过 file_id 复用已存储在 Telegram 服务器上的文件。每条结果都需要 type 和 1–64 字节的 id。最常用的两种:
- article —— 必填
title和input_message_content;可选description、url、thumbnail_url、reply_markup。内容通常是InputTextMessageContent,包含message_text(1–4096 个字符)和可选的parse_mode。 - photo —— 必填
photo_url(JPEG,最大 5 MB)和thumbnail_url;可选caption(0–1024 个字符)、title、description。
内联结果中的所有 URL 都会被最终用户看到,请把它们当作公开信息。parse_mode 的格式规则与用 Bot API 发送消息时相同。
示例:用 Python 和 JavaScript 实现内联机器人
这个机器人把查询文字格式化为粗体、斜体或等宽字体。查询为空时只显示一个按钮,点击后进入与机器人的私聊,/start 会回复几个切回 Inline 模式的按钮。运行前先设置环境变量 BOT_TOKEN。
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 字节,在同一次回答中唯一
"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: # 空查询:不返回结果,只显示一个打开私聊的按钮
call("answerInlineQuery", inline_query_id=query["id"], results=[], cache_time=5,
button={"text": "使用说明", "start_parameter": "help"})
return
safe = html.escape(text)
results = [
article("bold", "粗体", text, f"<b>{safe}</b>"),
article("italic", "斜体", text, f"<i>{safe}</i>"),
article("mono", "等宽", 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"): # 也包括按钮发来的 "/start help"
call("sendMessage", chat_id=msg["chat"]["id"],
text="在任意聊天中输入我的用户名和一段文字,即可格式化。",
reply_markup={"inline_keyboard": [[
{"text": "在这里试试", "switch_inline_query_current_chat": "你好"},
{"text": "选择聊天", "switch_inline_query": "你好"},
]]})
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 字节,在同一次回答中唯一
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) { // 空查询:不返回结果,只显示一个打开私聊的按钮
await call("answerInlineQuery", {
inline_query_id: query.id, results: [], cache_time: 5,
button: { text: "使用说明", start_parameter: "help" },
});
return;
}
const safe = escapeHtml(text);
const results = [
article("bold", "粗体", text, `<b>${safe}</b>`),
article("italic", "斜体", text, `<i>${safe}</i>`),
article("mono", "等宽", 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")) { // 也包括按钮发来的 "/start help"
await call("sendMessage", {
chat_id: msg.chat.id,
text: "在任意聊天中输入我的用户名和一段文字,即可格式化。",
reply_markup: { inline_keyboard: [[
{ text: "在这里试试", switch_inline_query_current_chat: "你好" },
{ text: "选择聊天", switch_inline_query: "你好" },
]] },
});
}
}
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);
}
}
}把 JavaScript 版本保存为 bot.mjs,用 Node.js 18+ 运行,然后在任意聊天中输入 @your_bot hello。同样的处理函数也可以配合 Webhook 使用,参见 Telegram Bot Webhook 设置教程。
用 next_offset 分页
匹配结果超过 50 条时就要分页:第一次请求中 offset 为空,用户向下滚动时,你返回的 next_offset 会被带回来:
PAGE_SIZE = 20 # answerInlineQuery 最多接受 50 条结果
def answer_page(query, items):
start = int(query["offset"] or 0) # 第一次请求时 offset 为 ""
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 "") # "" 表示没有更多结果const PAGE_SIZE = 20; // answerInlineQuery 最多接受 50 条结果
async function answerPage(query, items) {
const start = Number(query.offset || 0); // 第一次请求时 offset 为 ""
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) : "", // "" 表示没有更多结果
});
}chosen_inline_result 与内联反馈
开启反馈后,机器人会收到 ChosenInlineResult 对象,包含 result_id、from、query,以及可选的 location 和 inline_message_id。由于缓存的存在,热门机器人收到的“已选结果”可能比实际查询还多,所以负载高时建议只接收 1/10、1/100 或 1/1000。
只有发出的消息带有内联键盘时才会有 inline_message_id。把它保存下来,之后就能用 editMessageText 编辑这条消息(传 inline_message_id,不传 chat_id 和 message_id);这条消息上的按钮被点击时,会以 callback_query 的形式到达,并带有相同的 inline_message_id。
结果按钮与切回聊天
button 参数会在结果上方(或代替结果)显示一个 InlineQueryResultsButton。它包含 text,以及下面二者之一:
start_parameter—— 打开与机器人的私聊并发送/start <parameter>;1–64 个字符,只能使用A-Z、a-z、0-9、_和-。web_app—— 启动一个 Mini App,Mini App 可以用switchInlineQuery回到 Inline 模式。
典型用法:先让用户绑定账号,然后发送带内联键盘按钮的消息,按钮可以是 switch_inline_query(用户自选聊天)、switch_inline_query_current_chat(在当前聊天中填入 @your_bot 查询)或 switch_inline_query_chosen_chat(把可选范围限定为用户、机器人、群组或频道)。
常见问题排查
| 现象 | 可能原因及解决方法 |
|---|---|
输入 @your_bot 后没有任何反应 | 没有开启 Inline 模式:使用 /setinline 或 setMySettings。 |
收不到 inline_query 更新 | 之前设置过不含 inline_query 的 allowed_updates(该列表会被记住),或者 Webhook 处于启用状态,getUpdates 返回 409 Conflict。 |
| 一直显示旧结果 | 服务器端缓存:调小 cache_time(默认 300 秒),结果因人而异时使用 is_personal。 |
400 Bad Request: query is too old and response timeout expired or query ID is invalid | 回答太晚或 ID 不对。收到查询后立即回答,耗时操作放到后台。 |
收不到 chosen_inline_result | 内联反馈没有开启:使用 /setinlinefeedback 或 inline_feedback_share_denominator。 |
| 图片结果不显示 | photo_url 必须是公开可访问、不超过 5 MB 的 JPEG,并且必须提供 thumbnail_url。 |
访问量大的内联机器人还要注意 Telegram Bot API 限制。
常见问题
怎样为 Telegram 机器人开启 Inline 模式?
向 @BotFather 发送 /setinline,选择机器人并输入占位提示文字。从 Bot API 10.5 起,机器人也可以自己调用 setMySettings,传入 supports_inline_queries: true(可选再加 inline_query_placeholder)。
answerInlineQuery 一次最多能返回多少条结果?
每次调用最多 50 条。列表更长时分页返回,并传入 next_offset(最多 64 字节);用户向下滚动时,客户端会把它放在 offset 中发回来。
为什么改了代码,内联结果还是旧的?
结果可能会在 Telegram 服务器上缓存 cache_time 秒,默认 300 秒。开发阶段把 cache_time 设小一些;如果结果因用户而异,再加上 is_personal: true。
内联机器人需要先拉进聊天吗?
不需要。用户在任意聊天的输入框里输入机器人用户名和查询内容,机器人就会收到 inline_query 更新;选中的结果由用户本人发出,并标注机器人的用户名(via_bot)。
怎么知道用户最终发送了哪条内联结果?
在 @BotFather 用 /setinlinefeedback 开启内联反馈,或在 setMySettings 中设置 inline_feedback_share_denominator(1、10、100 或 1000)。之后机器人会收到带有 result_id 和 query 的 chosen_inline_result 更新。
为什么 chosen_inline_result 里没有 inline_message_id?
只有发出的消息带有内联键盘时才会有这个字段。如果之后要编辑这条消息或接收它的按钮回调,请在结果中加上 reply_markup。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。
Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。
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 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。
Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接
Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。
Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘
Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。
n8n Telegram 集成教程:连接机器人、触发工作流并发送消息
n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。
Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理
Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。
Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token
Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。
Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token
Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。
Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID
Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。
Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅
Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。
Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。
Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。
TelegramWidget JavaScript API:属性、事件、错误码与限制参考
TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。
Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端
Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。