Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Widget)是机器人通过 sendWidget 方法在消息里发送的可交互 HTML 小块,由 2026 年 11 月 9 日发布的 Bot API 10.4 引入。一个小组件就是一个不超过 32 KB 的 HTML 文档,由 Telegram 客户端在用户设备上运行,完全不联网,并按当前聊天的样式绘制。典型用法:会自动更新状态的订单卡片、计数器、随投票实时变化的投票条、一点就能复制的优惠码。
目前在哪里可用:在正式(生产)环境中,机器人只能在与用户的私聊里发送小组件,而且这些消息以受保护内容(protected content)发送,无法转发。群组、内联模式(inline mode)和转发中的小组件目前只在测试服务器上可用。
Telegram 小组件是什么
- 一个 HTML 文档。样式和脚本都写在内联的
<style>和<script>里,图片只能用data:URL 或内联 SVG。UTF-8 编码后最多 32768 字节,用 zlib level 9 压缩后最多 4096 字节。不写<html>和<body>、只发一个片段也可以。 - 运行在沙箱中。JavaScript 由轻量引擎 QuickJS 执行,而不是 WebView。客户端会按“小组件规范”(widget profile)检查小组件对页面的每一次修改,只绘制允许的内容,因此同一个小组件在 iOS、Android、macOS、Telegram Desktop 和网页版上看起来都一样。
- 离线运行。
fetch、XMLHttpRequest、WebSocket等网络 API 会抛出NetworkDisabledError。外部脚本、样式表、字体和图片一律不会加载,也没有内置任何库。 - 原生外观。聊天配色以
--tg-theme-*CSS 变量提供,不加样式的<button>会被绘制成客户端自己的按钮。 - 没有键盘输入。
input、select、textarea会被移除。小组件只响应点击、指针事件、水平拖动和长按。
代码与状态:chat_data 和 public_data
小组件 = 固定的代码 + 可变的状态。HTML 在发送时确定,之后不会改变,也没有任何方法能替换它。会变化的是状态,而且只有机器人能写入。小组件通过 TelegramWidget.chatData 和 TelegramWidget.publicData 读取状态,并在 chatDataChanged、publicDataChanged 事件触发时重新绘制。
| 项目 | 聊天状态(chat_data) | 公共状态(public_data) |
|---|---|---|
| 归属 | 某一条原始消息 | 静态小组件所在的消息;或共享小组件(在所有显示它的地方) |
| 可见范围 | 只在该聊天中(群组里所有成员共用一份) | 小组件显示的任何地方 |
| 转发后 | 永远没有 | 静态小组件:转发时的副本;共享小组件:实时的公共状态 |
| 大小 | 最多 1024 字节文本 | 最多 1024 字节文本 |
| 修改方法 | editMessageWidgetData | editMessageWidgetData 或 editSharedWidgetData |
| 示例 | 进行中的游戏、订单状态 | 投票结果、价格 |
两者都是服务器不做解析的纯文本,通常使用 JSON。在小组件中,没有状态或状态被清空时值为 null。
小组件在哪里运行:生产环境与测试服务器
| 位置 | 如何到达 | 请求(需 allow_queries) | 生产环境 |
|---|---|---|---|
| 与机器人的私聊 | sendWidget、sendSharedWidget | 点击时和后台均可 | 可用 |
| 普通群组或超级群组 | sendWidget | 仅点击时 | 仅测试服务器 |
| 除频道外的任意聊天(通过机器人发送) | 内联模式(InputWidgetMessageContent、InputSharedWidgetMessageContent) | 仅点击时 | 仅测试服务器 |
| 转发(包括频道) | 用户转发 | 仅点击时,且仅限共享小组件 | 仅测试服务器 |
机器人不能在频道中发布小组件。不支持小组件的客户端会把消息显示为“不支持的媒体”并附带说明文字。小组件消息不能用 copyMessage 或 copyMessages 复制;在群组中,can_send_other_messages 权限同样覆盖小组件。
Telegram 小组件与 Mini App 的区别
| 项目 | Mini App | 小组件 |
|---|---|---|
| 位置 | 从按钮、菜单或链接打开的 WebView | 消息气泡内,随聊天滚动始终可见 |
| 代码 | 部署在你服务器上的网页 | 消息内最多 32 KB 的 HTML,发送后固定 |
| 引擎 | 平台自带的 WebView | QuickJS 沙箱,由 Telegram 客户端绘制 |
| 网络 | 可访问互联网 | 无 |
| 与机器人通信 | 你自己的后端,配合签名的 initData | TelegramWidget.request() → widget_query 更新 |
| 输入 | 全部,包括键盘 | 点击和指针事件,没有键盘 |
两套 API 重叠的部分,TelegramWidget 沿用了 Telegram.WebApp 的命名(themeParams、colorScheme、onEvent、openLink、HapticFeedback、ready),习惯可以直接迁移。比小组件更复杂的功能,用 openTelegramLink 打开你的机器人或 Mini App 即可。如果你在做 Mini App,可以用 Mini App Tester 调试 Telegram.WebApp。
用 sendWidget 发送第一个小组件
- 创建机器人并复制 Token(参见 创建 Telegram 机器人教程 和 Telegram Bot Token 获取方法)。
- 给机器人发送
/start,让它可以给你发消息,然后通过getUpdates拿到你的 chat id(参见 chat id 获取教程)。 - 调用 sendWidget。
html参数是字符串,建议以 JSON 格式发送请求:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>你的优惠码</h3><p>点击按钮即可复制。</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "你的优惠码:PROMO10"
}'
用 Python 的 requests 或 JavaScript 的 fetch 实现同样的请求:
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>你的优惠码</h3>
<p>点击按钮即可复制。</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "你的优惠码:PROMO10",
}, timeout=10)
print(r.json()) # result:已发送的 Message,包含 "widget" 字段const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>你的优惠码</h3>
<p>点击按钮即可复制。</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;
const r = await fetch(`${API}/sendWidget`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: 123456789,
html,
caption: "你的优惠码:PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result:已发送的 Message,包含 "widget" 字段这个小组件一行 CSS 都没有,看起来仍像一条普通消息,按钮也是原生样式。TelegramWidget 无需引入任何脚本就存在;copyText 能生效,是因为它在点击事件的处理函数中被调用。你也可以把这段 HTML 粘贴到 Bot API Tester 的 sendWidget 表单,用自己的 Token 直接发送。
sendWidget 的其他参数:width 和 height(以逻辑像素表示的尺寸锚点)、chat_data 和 public_data(初始状态)、allow_queries、is_shared,以及常规的 caption、reply_markup、reply_parameters、message_thread_id 和 protect_content。
小组件如何与机器人通信
请求的工作方式类似于放在小组件里的回调按钮(callback button):
- 机器人以
allow_queries: true发送小组件。 - 用户点击时,小组件调用
TelegramWidget.request("like"),携带 1–64 字节数据。 - 机器人收到
widget_query更新,包含id、from、chat、message_id和data(来自共享小组件转发副本的请求是shared_widget_query)。如果你设置了allowed_updates,两种类型都要加上。 - 机器人在 15 秒内调用 answerWidgetQuery,可附带最多 1024 字节的
data,只有发起请求的那个小组件能收到。 - 要改变所有人看到的内容,机器人调用 editMessageWidgetData(或
editSharedWidgetData),小组件随后收到chatDataChanged/publicDataChanged。
回应本身不会改变状态。请求限制为每个用户对每个机器人每 5 秒 5 次;机器人没有回应,小组件里会得到 TIMEOUT。完整可运行的代码见 Telegram 小组件示例。
静态小组件与共享小组件
不带 is_shared 发送的是静态小组件:代码和状态都保存在消息里,转发得到的是冻结的副本。带 is_shared 第一次发送时会创建一个共享小组件:一个带标识符的对象(返回消息中的 widget.id),可以被任意多条消息显示。用 sendSharedWidget 再次发送它,用 editSharedWidgetData 一次性更新所有消息里的公共状态,每秒最多一次。已经显示在屏幕上的小组件必须调用 TelegramWidget.watchPublicData() 才能收到新的公共状态;之后客户端按小组件的刷新周期轮询(默认 30 秒,可通过 cache_time 设为 5–3600 秒)。
Telegram 小组件限制一览
| 项目 | 限制 |
|---|---|
| HTML | 32768 字节;zlib level 9 压缩后 4096 字节 |
chat_data、public_data | 各 1024 字节 |
| 请求数据 / 回应数据 | 1–64 字节 / 最多 1024 字节 |
| 回应请求的时限 | 15 秒 |
| 请求频率 | 每个用户对每个机器人每 5 秒 5 次 |
| 气泡尺寸 | 宽 200 px 到气泡最大宽度,高 50–600 px,超出部分被裁剪 |
| 共享小组件编辑 | 每秒 1 次 |
| 内存 / DOM 节点 | 8 MB / 2000 个 |
包括 CPU 配额、定时器和存储在内的完整列表,见 TelegramWidget API 参考。
设计建议
- 始终附带说明文字(caption)。聊天列表、通知、搜索以及不支持小组件的客户端显示的都是它。
- 使用主题变量。颜色基于
--tg-theme-*变量,并在浅色和深色聊天主题下都测试一遍;prefers-color-scheme跟随的是聊天主题,而不是系统主题。 - 立即绘制首屏:直接根据
chatData/publicData渲染,没有任何东西需要加载。 - 控制体积。按服务器的方式计算压缩后大小:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html。 - 不要放机密信息。把代码和公共状态都当作公开内容;在群组中,所有成员都能看到聊天状态。
- 按宽度布局,使用
%、flex 或 grid。不支持vh,小组件内部也不能滚动。 - 展示请求的每种结果:“发送中…”、机器人的回应,以及每一种错误码。
别和网站小组件混淆
“Telegram widget”也常指较早的网站小组件:Telegram Login Widget(登录小组件)、帖子嵌入和分享按钮。它们是放在你自己网站上的脚本。Bot API 10.4 的小组件则完全不同:它是机器人发到聊天里的 HTML。网站小部件的接入方法见 Telegram 网站小部件教程。官方文档地址:core.telegram.org/bots/widgets。
下一步
- Telegram 小组件示例:订单卡片、带请求的计数器、共享的实时投票,附 Python 机器人代码。
- TelegramWidget JavaScript API:属性、方法、事件、错误码、CSS 变量和各项限制。
- Bot API 方法参考:查看
sendWidget、answerWidgetQuery等 10.4 新方法的参数。
常见问题
Telegram 小组件是什么?
Bot API 10.4(2026 年 11 月 9 日)新增的功能:机器人可以在消息气泡里放一个可交互的小块内容。小组件是一个自包含的 HTML 文档(内联 CSS 和 JavaScript),由 Telegram 客户端在用户设备上的沙箱中运行,完全无法联网。
Telegram 小组件可以在群组里用吗?
正式环境暂时不行。目前在生产环境中,机器人只能在与用户的私聊里发送小组件,而且无法转发。群组、内联模式和转发目前只在测试服务器上可用。
机器人怎么发送小组件?
调用 sendWidget,传入 chat_id 和 html(字符串,1–32768 字节,zlib level 9 压缩后不超过 4096 字节),可选 caption、chat_data、public_data 和 allow_queries。返回已发送的 Message,其中包含 widget 字段。
小组件里能发 HTTP 请求吗?
不能。fetch、XMLHttpRequest、WebSocket 等所有网络 API 都会抛出 NetworkDisabledError。唯一的出口是 TelegramWidget.request(),它把 1–64 字节的数据作为 widget_query 更新发给你的机器人。
小组件和 Mini App 有什么区别?
Mini App 是你自己托管的网页,从按钮或链接打开,在 WebView 中运行,可以联网。小组件直接显示在消息气泡里,HTML 最多 32 KB 且发送后固定不变,不能联网,只能通过请求与自己的机器人通信。
发送后还能修改小组件的 HTML 吗?
不能。代码发送后就固定了,能变的只有状态:用 editMessageWidgetData 或 editSharedWidgetData 更新 chat_data / public_data;要换布局就发送一个新的小组件。说明文字(caption)可以用 editMessageCaption 修改。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
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 测试服务器:如何在 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 代码。