Telegram Bot API

Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等

· 8 分钟阅读

Telegram Bot API 10.5 于 2026 年 11 月 22 日发布,是当前最新版本,共 194 个方法。10.x 系列从 2026 年 5 月 8 日的 Bot API 10.0 开始,陆续带来了访客模式、实况照片、支持流式草稿的富文本消息、临时消息、社群(Communities)、入群申请查询、消息内的交互式 HTML 小组件(10.4),以及 10.5 中的 setMySettings 方法和 getMe 返回的新对象 BotFullInfo。下面逐个版本介绍更新内容,附简短的 JSON 示例,并指出可能导致现有机器人出错的变更。

Telegram Bot API 10 版本概览

版本发布日期主要更新
10.02026 年 5 月 8 日访客模式、实况照片、投票支持媒体、删除表情回应
10.12026 年 6 月 11 日富文本消息与富文本草稿、入群申请查询
10.22026 年 7 月 14 日临时消息、社群、subscription 更新、Mini App 来源保护
10.32026 年 8 月 24 日EphemeralMessageParameters、可停止的草稿、DisabledButton、富文本消息中的按钮
10.42026 年 11 月 9 日HTML 小组件、在任意聊天中以临时消息回复回调查询、引用富文本消息、TON 钱包卡片、聊天分享主题
10.52026 年 11 月 22 日setMySettings、getMe 返回 BotFullInfo、callback_query_mode、机器人邀请链接、可展开引用支持块

Bot API 10.0:访客模式、实况照片和投票

访客模式。在 @BotFather 的 Mini App 中开启 Guest Mode 后,用户可以在机器人不是成员的聊天中提及它。机器人会收到 guest_message 更新,并可以用 answerGuestQuery 回复一次,传入消息中的 guest_query_id 和一个 InlineQueryResult:

{
  "guest_query_id": "<message.guest_query_id>",
  "result": {
    "type": "article",
    "id": "1",
    "title": "翻译",
    "input_message_content": {"message_text": "Bonjour tout le monde"}
  }
}

以访客身份工作的机器人无法访问聊天记录和成员列表,除非再次被提及或被回复,否则也看不到之后的消息。

Bot API 10.1:Telegram 富文本消息与入群申请查询

富文本消息适合输出报告、文档和 AI 回答等结构化内容。sendRichMessage 接收一个 rich_message 对象,内容放在 html 或 markdown 中(10.2 又增加了显式的 blocks 和 media 列表)。支持标题、列表和任务列表、表格、引用、可折叠详情、脚注、LaTeX 公式、地图、拼图、幻灯片和媒体块。限制:32768 个 UTF-8 字符、500 个块、16 层嵌套、50 个媒体、表格 20 列。

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "rich_message": {
      "markdown": "# 周报\n\n| 指标 | 数值 |\n|:-------|------:|\n| 用户 | **1204** |\n| 错误 | 3 |\n\n- [x] 部署 v2.1\n- [ ] 更新文档\n\n$$E = mc^2$$"
    }
  }'

sendRichMessageDraft 在生成过程中把部分富文本消息流式推送到私聊。草稿只是 30 秒的临时预览,最后要用 sendRichMessage 发送完整内容。editMessageText 现在也支持 rich_message。

入群申请查询。当你的机器人被设为某个聊天的守卫机器人时,chat_join_request 更新会带有 query_id。可以直接用 answerChatJoinRequestQuery 做出决定(approve、decline,或用 queue 交给其他管理员处理),也可以先用 sendChatJoinRequestWebApp 展示一个 Mini App;该 Mini App 会在初始化数据中收到 chat_join_request_query_id。

{"chat_join_request_query_id": "<chat_join_request.query_id>", "result": "approve"}

10.1 还为投票增加了链接类媒体。

Bot API 10.2:Telegram 临时消息、社群与 Mini App 安全

临时消息是群组中只有某一个用户和机器人可见的消息,可以让提示、欢迎语和个人结果不刷屏公共聊天。用户也可以发送别人看不到的临时命令(BotCommand.is_ephemeral)。发送规则:

临时消息有专门的方法:editEphemeralMessageText、editEphemeralMessageMedia、editEphemeralMessageCaption、editEphemeralMessageReplyMarkup 和 deleteEphemeralMessage:

{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 15}

Bot API 10.3:EphemeralMessageParameters、可停止的草稿和 DisabledButton

临时消息的不兼容变更。在 13 个发送方法(sendMessage、sendPhoto、sendVideo、sendAnimation、sendAudio、sendDocument、sendLivePhoto、sendSticker、sendVideoNote、sendVoice、sendContact、sendLocation、sendVenue)中,10.2 的 receiver_user_id 和 callback_query_id 参数被统一替换为一个对象 ephemeral_message_parameters。sendRichMessage 也支持它,新增的 replace_callback_query_message 会让临时消息替换掉被点击按钮所在的消息显示:

{
  "chat_id": -1001234567890,
  "text": "只有你能看到这条消息。",
  "ephemeral_message_parameters": {
    "receiver_user_id": 123456789,
    "callback_query_id": "<callback_query.id>",
    "replace_callback_query_message": true
  }
}

可停止的草稿。向 sendMessageDraft 或 sendRichMessageDraft 传入 can_stop 会显示“停止”按钮。用户点击后,机器人会收到带有 chat 和 draft_id 的 stopped_message_generation 更新,可以据此中止模型生成。keep_on_stop 会让未完成的草稿再保留一段时间;如果需要保留下来,请把它作为普通消息发送。

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
text, last = "", 0.0
for chunk in generate_reply():          # 你的 LLM token 流
    text += chunk
    if time.monotonic() - last > 0.5:   # 不要每个 token 都发一次草稿
        requests.post(f"{API}/sendMessageDraft", json={"chat_id": 123456789,
                      "draft_id": 1, "text": text, "can_stop": True}, timeout=10)
        last = time.monotonic()
requests.post(f"{API}/sendMessage", json={"chat_id": 123456789, "text": text}, timeout=10)
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const post = (method, body) => fetch(`${API}/${method}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(10_000),
});

let text = "", last = 0;
for await (const chunk of generateReply()) {  // 你的 LLM token 流
  text += chunk;
  if (Date.now() - last > 500) {               // 不要每个 token 都发一次草稿
    await post("sendMessageDraft", { chat_id: 123456789,
      draft_id: 1, text, can_stop: true });
    last = Date.now();
  }
}
await post("sendMessage", { chat_id: 123456789, text });

Bot API 10.4:Telegram 小组件、任意聊天中的临时回复与 TON 钱包

小组件(Widgets)。机器人现在可以在消息中发送小型交互式 HTML 模块。一个小组件就是一个 HTML 文档(最大 32768 字节,zlib 压缩后最大 4096 字节),客户端在无网络访问的沙箱中运行它;再加上只能由机器人修改的状态:针对单条消息的 chat_data,以及在所有展示位置共享的 public_data。新方法:sendWidget、sendSharedWidget、answerWidgetQuery、editMessageWidgetData 和 editSharedWidgetData;新更新类型:widget_query 和 shared_widget_query;内联模式新增 InputWidgetMessageContent 和 InputSharedWidgetMessageContent(目前仅限测试服务器)。

{
  "chat_id": 123456789,
  "html": "<h3>订单 #1042</h3><p>玛格丽特披萨 × 2,柠檬水 × 1</p><p><strong>合计:$23.50</strong></p>",
  "caption": "订单 #1042:$23.50"
}

在正式环境中,小组件目前只能用于私聊,并以受保护内容的形式发送,因此无法转发;群组、内联模式和转发只能在测试服务器上使用。小组件消息不能通过 copyMessage / copyMessages 复制,can_send_other_messages 权限现在也涵盖小组件。详见 Telegram 小组件详解。

在任意聊天中以临时消息回复回调查询(频道私信聊天除外)。在 ephemeral_message_parameters 中只传 callback_query_id、不传 receiver_user_id,消息就只对点击按钮的用户显示。发送方法中的 receiver_user_id 和 chat_id 参数现在都变为可选。仍然需要调用 answerCallbackQuery。

{
  "text": "这条回复只有你能看到。",
  "ephemeral_message_parameters": {"callback_query_id": "<callback_query.id>"}
}

Bot API 10.5:setMySettings、BotFullInfo 和机器人邀请链接

用代码修改机器人设置。新方法 setMySettings 可以修改过去只能在 @BotFather 中调整的设置。所有参数都是可选的,只传需要修改的即可;成功时返回 True:

{
  "supports_inline_queries": true,
  "inline_query_placeholder": "搜索菜谱...",
  "can_join_groups": false,
  "has_topics_enabled": true,
  "callback_query_mode": "auto"
}

把它发送到 https://api.telegram.org/bot<token>/setMySettings,或者在 Bot API Tester 中用自己的 Token 试一试,然后调用 getMe 查看结果。

BotFullInfo(不兼容变更)。getMe 现在返回新的 BotFullInfo 对象而不是 User,原先只有 getMe 才返回的字段已从 User 中移除。BotFullInfo 还新增了 active_usernames、inline_query_placeholder、needs_inline_query_location 和 has_topic_sidebar。从 getMe 结果中读取 can_join_groups、can_read_all_group_messages、supports_inline_queries 等字段的代码不受影响,因为这些字段都在 BotFullInfo 中。会出问题的是在其他 User 对象上读取这些字段的代码,以及把 getMe 结果声明为 User 类型的强类型代码。

如何把机器人升级到 Bot API 10.5

  1. 把所用的库(python-telegram-bot、aiogram、grammY、Telegraf 等)升级到更新日志中注明支持 Bot API 10.5 的版本。
  2. 把 10.2 风格的 receiver_user_id 和 callback_query_id 移到 ephemeral_message_parameters 中。
  3. 如果显式传了 allowed_updates 列表,加入你要处理的新类型:guest_message、subscription、stopped_message_generation、widget_query、shared_widget_query。
  4. 放宽投票校验:现在允许只有一个选项。
  5. Mini App 中确保所有 Telegram.WebApp 调用都在注册的域名上执行。
  6. 如果代码中按名称引用了 StoryAreaPosition 类型,改为 AreaPosition。
  7. 把 getMe 的结果当作 BotFullInfo 处理,不要再从其他 User 对象中读取 can_join_groups 等 getMe 专属字段。
  8. 在富文本消息中用 blocks 而不是 text 构建可展开引用。
  9. 如果把 callback_query_mode 改成 "auto" 或 "inline",回调处理代码要能在缺少 message 时处理 inline_message_id。
  10. 在 Bot API Tester 中用自己的 Token 试用新方法:setMySettings、sendWidget、sendRichMessage、deleteEphemeralMessage 和 answerChatJoinRequestQuery。

临时消息和普通消息的基础用法相同,可以通过 Telegram Bot API 发送消息教程温习一下;Telegram Bot API 限制汇总把富文本消息的限制和传统限制列在了一起。完整的版本历史见官方 Bot API changelog。

常见问题

Telegram Bot API 最新版本是多少?

Bot API 10.5,于 2026 年 11 月 22 日发布,共 194 个方法。它是 10.x 系列的第六个版本,该系列始于 2026 年 5 月 8 日发布的 Bot API 10.0。10.5 新增了让机器人修改自身设置的 setMySettings,getMe 改为返回 BotFullInfo。上一个版本 10.4(2026 年 11 月 9 日)新增了消息内的 HTML 小组件。

Telegram 的富文本消息(rich messages)是什么?

富文本消息(Bot API 10.1)是通过 sendRichMessage 发送的结构化消息,支持标题、列表、表格、LaTeX 公式、媒体块、地图,从 10.3 起还支持按钮。内容以 HTML、Markdown 或块结构放在 rich_message 中,最多 32768 个 UTF-8 字符。

Telegram 机器人的临时消息(ephemeral messages)是什么?

临时消息(Bot API 10.2)是群组或超级群组中只有某一个用户和机器人能看到的消息。从 10.3 起,通过 sendMessage 等发送方法的 ephemeral_message_parameters 发送;从 10.4 起,机器人还可以在任何聊天(频道私信聊天除外)中以临时消息回复回调查询。消息不保证送达,尤其是用户离线时。

Telegram 机器人如何流式输出 AI 回复?

在私聊中用同一个 draft_id 反复调用 sendMessageDraft 或 sendRichMessageDraft,最后用 sendMessage 或 sendRichMessage 发送最终文本,因为草稿只是 30 秒的临时预览。加上 can_stop 后,用户会看到“停止”按钮,机器人会收到 stopped_message_generation 更新。

Telegram Bot API 10.5 的 setMySettings 是做什么的?

setMySettings 让机器人不经过 @BotFather 就能修改自身设置:内联模式、隐私模式、加入群组、商业连接、访客查询和入群申请查询、私聊话题、机器人间通信以及 callback_query_mode。只需传入要修改的字段,成功时返回 True。当前值可以通过 getMe 获取,它现在返回 BotFullInfo。

Telegram Bot API 10.0 的访客模式是什么?

访客模式让机器人在自己不是成员的聊天中被提及时也能回复。机器人会收到 guest_message 更新,并可以用 answerGuestQuery 回复一次,但无法访问聊天记录。该功能在 @BotFather 的 Mini App 中开启。

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 错误码大全:每种报错的含义与解决方法

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 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询

Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。

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 校验代码。