Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
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.0 | 2026 年 5 月 8 日 | 访客模式、实况照片、投票支持媒体、删除表情回应 |
| 10.1 | 2026 年 6 月 11 日 | 富文本消息与富文本草稿、入群申请查询 |
| 10.2 | 2026 年 7 月 14 日 | 临时消息、社群、subscription 更新、Mini App 来源保护 |
| 10.3 | 2026 年 8 月 24 日 | EphemeralMessageParameters、可停止的草稿、DisabledButton、富文本消息中的按钮 |
| 10.4 | 2026 年 11 月 9 日 | HTML 小组件、在任意聊天中以临时消息回复回调查询、引用富文本消息、TON 钱包卡片、聊天分享主题 |
| 10.5 | 2026 年 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"}
}
}
以访客身份工作的机器人无法访问聊天记录和成员列表,除非再次被提及或被回复,否则也看不到之后的消息。
- 表情回应与管理员:
deleteMessageReaction删除群组中的一个表情回应;deleteAllMessageReactions删除某个用户或聊天最近的最多 10000 个表情回应。getChatAdministrators新增return_bots参数。 - 投票:投票、选项和测验解析中可以加入媒体(
media、explanation_media),并新增members_only和country_codes。最少选项数从 2 个降为 1 个。 - 实况照片:
sendLivePhoto发送带短视频的照片;实况照片也可用于sendMediaGroup、editMessageMedia和付费媒体。 - 其他:
getManagedBotAccessSettings和setManagedBotAccessSettings、getUserPersonalChatMessages;双方都允许时,机器人之间可以通过用户名互发消息;sendMessageDraft允许空text,用于显示“Thinking...”占位。
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)。发送规则:
- 任何机器人都可以在符合条件的操作发生后 15 秒内以临时消息回应:回调查询(通过其 id)或收到的临时消息(通过
reply_parameters.ephemeral_message_id)。 - 担任聊天管理员的机器人可以随时向任何非机器人成员发送临时消息。
- 消息不保证送达,尤其是用户离线时。
临时消息有专门的方法:editEphemeralMessageText、editEphemeralMessageMedia、editEphemeralMessageCaption、editEphemeralMessageReplyMarkup 和 deleteEphemeralMessage:
{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 15}
- 社群(Communities):围绕同一主题关联起来的超级群组、频道和机器人,对应
Community类型、community_chat_added和community_chat_removed服务消息以及ChatFullInfo.community。 - 订阅:新的
subscription更新会通知用户付费订阅的变化。 - Mini App 来源保护:从与 Mini App 域名不同的源调用 Mini App 方法会被拦截。2026 年 7 月 20 日起对所有 Mini App 启用,可在 @BotFather 中关闭。实际影响见 Telegram Mini App 测试教程。
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 });- 禁用按钮:
InlineKeyboardButton新增disabled字段,取值为DisabledButton对象,例如{"text": "已售罄", "disabled": {}},点击后不会有任何反应。InlineKeyboardMarkup和ReplyKeyboardMarkup也新增了force_reply。 - 富文本消息:消息内按钮(
<tg-button>、<tg-button-row>)、紧凑表格、可展开的块引用和文档块。 - 管理员:
ChatAdministratorRights和promoteChatMember中新增can_send_welcome_messages权限。 - 编辑临时消息:
editEphemeralMessageMedia支持上传新文件,editEphemeralMessageCaption支持show_caption_above_media,editEphemeralMessageText支持rich_message。
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>"}
}
- 引用富文本消息:
TextQuote.rich_texts和ReplyParameters.quote_rich_texts。 - TON 钱包:
TonWalletCard和ChatFullInfo.ton_wallet_card、ton_wallet_transfer服务消息;StoryAreaPosition更名为AreaPosition。 - 聊天分享主题:
ChatFullInfo.share_theme和新方法getChatShareThemeBackdrops。 - 礼物:
getUniqueGift按名称返回唯一礼物;deleteBusinessAccountGift删除受管理商业账号的普通礼物,且不会因此获得 Stars。 - 实体与认证:
MessageEntity新增ton_address和bank_card_number类型;verifyUser和verifyChat新增custom_description_parse_mode和custom_description_entities。 - 其他:
paid_messages_waived服务消息;Premium 用户最多可以为自己拥有的 2 个机器人设置以 agent、ai、app、game 或 gay 结尾的附加用户名;支持指向与机器人私聊中话题的链接https://t.me/<bot_username>/<message_thread_id>。
Bot API 10.5:setMySettings、BotFullInfo 和机器人邀请链接
用代码修改机器人设置。新方法 setMySettings 可以修改过去只能在 @BotFather 中调整的设置。所有参数都是可选的,只传需要修改的即可;成功时返回 True:
- 内联模式:
supports_inline_queries、inline_query_placeholder、needs_inline_query_location和inline_feedback_share_denominator(每 1、10、100 或 1000 个被选中的内联结果接收 1 个;0 表示关闭)。 - 群组与隐私:
can_join_groups和can_read_all_group_messages(true表示关闭隐私模式)。 - 功能:
can_connect_to_business、can_manage_bots、supports_guest_queries、supports_join_request_queries,以及用于机器人间通信的can_communicate_with_bots。 - 私聊话题:
has_topics_enabled、allows_users_to_create_topics和has_topic_sidebar。 - 回调查询:
callback_query_mode决定机器人如何接收它所发消息中按钮的回调查询。"default"始终使用message字段;"auto"在机器人无法访问该消息时改用inline_message_id;"inline"始终用inline_message_id代替message。
{
"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 类型的强类型代码。
- 机器人邀请链接:机器人所有者可以通过
https://t.me/botinvite/<bot_username>一次邀请最多 10 个用户与机器人私聊,之后机器人就可以给这些用户发消息。WriteAccessAllowed新增inviter字段。 - 可展开引用(不兼容变更):
RichBlockExpandableBlockQuotation和InputRichBlockExpandableBlockQuotation中的text字段被blocks取代,可展开引用现在可以包含任意富文本块。
如何把机器人升级到 Bot API 10.5
- 把所用的库(python-telegram-bot、aiogram、grammY、Telegraf 等)升级到更新日志中注明支持 Bot API 10.5 的版本。
- 把 10.2 风格的
receiver_user_id和callback_query_id移到ephemeral_message_parameters中。 - 如果显式传了
allowed_updates列表,加入你要处理的新类型:guest_message、subscription、stopped_message_generation、widget_query、shared_widget_query。 - 放宽投票校验:现在允许只有一个选项。
- Mini App 中确保所有
Telegram.WebApp调用都在注册的域名上执行。 - 如果代码中按名称引用了
StoryAreaPosition类型,改为AreaPosition。 - 把
getMe的结果当作BotFullInfo处理,不要再从其他User对象中读取can_join_groups等 getMe 专属字段。 - 在富文本消息中用
blocks而不是text构建可展开引用。 - 如果把
callback_query_mode改成"auto"或"inline",回调处理代码要能在缺少message时处理inline_message_id。 - 在 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 校验代码。