Telegram Bot API

Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML

· 8 分钟阅读

Telegram 小组件(Widget)是机器人通过 sendWidget 方法在消息里发送的可交互 HTML 小块,由 2026 年 11 月 9 日发布的 Bot API 10.4 引入。一个小组件就是一个不超过 32 KB 的 HTML 文档,由 Telegram 客户端在用户设备上运行,完全不联网,并按当前聊天的样式绘制。典型用法:会自动更新状态的订单卡片、计数器、随投票实时变化的投票条、一点就能复制的优惠码。

目前在哪里可用:在正式(生产)环境中,机器人只能在与用户的私聊里发送小组件,而且这些消息以受保护内容(protected content)发送,无法转发。群组、内联模式(inline mode)和转发中的小组件目前只在测试服务器上可用。

Telegram 小组件是什么

代码与状态:chat_data 和 public_data

小组件 = 固定的代码 + 可变的状态。HTML 在发送时确定,之后不会改变,也没有任何方法能替换它。会变化的是状态,而且只有机器人能写入。小组件通过 TelegramWidget.chatData 和 TelegramWidget.publicData 读取状态,并在 chatDataChanged、publicDataChanged 事件触发时重新绘制。

项目聊天状态(chat_data)公共状态(public_data)
归属某一条原始消息静态小组件所在的消息;或共享小组件(在所有显示它的地方)
可见范围只在该聊天中(群组里所有成员共用一份)小组件显示的任何地方
转发后永远没有静态小组件:转发时的副本;共享小组件:实时的公共状态
大小最多 1024 字节文本最多 1024 字节文本
修改方法editMessageWidgetDataeditMessageWidgetData 或 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,发送后固定
引擎平台自带的 WebViewQuickJS 沙箱,由 Telegram 客户端绘制
网络可访问互联网无
与机器人通信你自己的后端,配合签名的 initDataTelegramWidget.request() → widget_query 更新
输入全部,包括键盘点击和指针事件,没有键盘

两套 API 重叠的部分,TelegramWidget 沿用了 Telegram.WebApp 的命名(themeParams、colorScheme、onEvent、openLink、HapticFeedback、ready),习惯可以直接迁移。比小组件更复杂的功能,用 openTelegramLink 打开你的机器人或 Mini App 即可。如果你在做 Mini App,可以用 Mini App Tester 调试 Telegram.WebApp。

用 sendWidget 发送第一个小组件

  1. 创建机器人并复制 Token(参见 创建 Telegram 机器人教程 和 Telegram Bot Token 获取方法)。
  2. 给机器人发送 /start,让它可以给你发消息,然后通过 getUpdates 拿到你的 chat id(参见 chat id 获取教程)。
  3. 调用 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):

  1. 机器人以 allow_queries: true 发送小组件。
  2. 用户点击时,小组件调用 TelegramWidget.request("like"),携带 1–64 字节数据。
  3. 机器人收到 widget_query 更新,包含 id、from、chat、message_id 和 data(来自共享小组件转发副本的请求是 shared_widget_query)。如果你设置了 allowed_updates,两种类型都要加上。
  4. 机器人在 15 秒内调用 answerWidgetQuery,可附带最多 1024 字节的 data,只有发起请求的那个小组件能收到。
  5. 要改变所有人看到的内容,机器人调用 editMessageWidgetData(或 editSharedWidgetData),小组件随后收到 chatDataChanged / publicDataChanged。

回应本身不会改变状态。请求限制为每个用户对每个机器人每 5 秒 5 次;机器人没有回应,小组件里会得到 TIMEOUT。完整可运行的代码见 Telegram 小组件示例。

静态小组件与共享小组件

不带 is_shared 发送的是静态小组件:代码和状态都保存在消息里,转发得到的是冻结的副本。带 is_shared 第一次发送时会创建一个共享小组件:一个带标识符的对象(返回消息中的 widget.id),可以被任意多条消息显示。用 sendSharedWidget 再次发送它,用 editSharedWidgetData 一次性更新所有消息里的公共状态,每秒最多一次。已经显示在屏幕上的小组件必须调用 TelegramWidget.watchPublicData() 才能收到新的公共状态;之后客户端按小组件的刷新周期轮询(默认 30 秒,可通过 cache_time 设为 5–3600 秒)。

Telegram 小组件限制一览

项目限制
HTML32768 字节;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 参考。

设计建议

别和网站小组件混淆

“Telegram widget”也常指较早的网站小组件:Telegram Login Widget(登录小组件)、帖子嵌入和分享按钮。它们是放在你自己网站上的脚本。Bot API 10.4 的小组件则完全不同:它是机器人发到聊天里的 HTML。网站小部件的接入方法见 Telegram 网站小部件教程。官方文档地址:core.telegram.org/bots/widgets。

下一步

常见问题

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