Telegram Bot API

Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询

· 8 分钟阅读

Telegram 内联机器人(inline bot)直接响应用户在输入框里敲的查询:用户在任意聊天中输入 @your_bot 加一段文字,机器人收到 inline_query 更新,用 answerInlineQuery 返回结果列表,用户点一下其中一条就发送出去。实现步骤很简单:开启 Inline 模式(在 @BotFather 中用 /setinline,或从 Bot API 10.5 起调用 setMySettings),处理 inline_query 更新,并返回最多 50 条结果。下面逐步讲解,最后附上完整的 Python 和 JavaScript 示例。

Inline 模式的工作原理

Inline 模式在任何聊天中都能用,即使机器人并不是该聊天的成员。整体流程如下:

  1. 用户在输入框里输入机器人用户名和查询内容,例如 @your_bot hello。此时聊天中还没有发送任何内容。
  2. 机器人收到一个 inline_query 更新。
  3. 机器人调用 answerInlineQuery 返回结果列表:文章、图片、GIF、视频、贴纸、位置等。
  4. 用户点击某条结果。消息以用户本人的身份发出,发送者名字旁边会显示机器人的用户名;在 Bot API 中,这类消息带有 via_bot 字段。
  5. (可选)机器人收到 chosen_inline_result 更新,得知用户发送了哪条结果。

为 Telegram 机器人开启 Inline 模式

新建的机器人默认关闭 Inline 模式。还没有机器人的话,请先阅读创建 Telegram 机器人教程。之后任选以下一种方式。

方式一:通过 @BotFather

  1. 向 @BotFather 发送 /setinline,选择你的机器人。
  2. 输入占位提示文字,用户输入机器人用户名后会在输入框里看到它,例如 输入要格式化的文字…
  3. 可选:/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 相关的参数:

不写代码也能验证:在 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_personaltrue 表示只为当前用户缓存;默认情况下,发送相同查询的任何用户都可能拿到这份结果
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。最常用的两种:

内联结果中的所有 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, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

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,以及下面二者之一:

典型用法:先让用户绑定账号,然后发送带内联键盘按钮的消息,按钮可以是 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 校验代码。