TelegramWidget JavaScript API:属性、事件、错误码与限制参考
Telegram widget API 指的是 Telegram 客户端提供给每个 Bot API 10.4 小组件的 window.TelegramWidget 对象,以及 Bot API 一侧的 widget_query 更新和 answerWidgetQuery 方法。本文依据官方 Telegram 小组件文档,列出 TelegramWidget 的全部属性、方法、事件和错误码,以及 CSS 变量、手势规则和各项限制。
可用范围:在正式(生产)环境中,小组件目前只能在与机器人的私聊中使用,而且无法转发(以受保护内容发送)。群组、内联模式和转发只在测试服务器上可用,所以isForward、chatType: "group"这类属性目前主要在测试服务器上才有意义。
刚接触小组件?先阅读 Telegram 小组件入门和 Telegram widget 示例。
TelegramWidget 对象从哪里来
小组件不需要任何 script 标签。在 Telegram 中,window.TelegramWidget 在小组件的第一段脚本运行前就已存在;在 Telegram 之外(普通浏览器)它是 undefined。规范版本内新增的方法用 typeof 检测:
const W = window.TelegramWidget; // 普通浏览器中为 undefined
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// 根据 state 绘制;null 表示“还没有状态”
}
if (W) W.onEvent('chatDataChanged', render);
render();
TelegramWidget 属性
| 属性 | 类型 | 说明 |
|---|---|---|
profile | Integer | 客户端执行的小组件规范版本:当前为 1 |
colorScheme | String | light 或 dark,即聊天的配色方案(也可通过 --tg-color-scheme 获取) |
themeParams | Object | 气泡的配色,值为 #rrggbb 字符串,键名与 Mini App 的 themeParams 相同 |
isActive | Boolean | 小组件当前可见(!document.hidden) |
isPreview | Boolean | 发送前显示的内联结果预览:不响应点击,不能发请求 |
isForward | Boolean | 是转发的副本 |
chatType | String | private、group、supergroup、channel;在转发或预览中为 null |
viewer | Object | 正在查看的用户:id、first_name、last_name、username、is_premium;只在小组件允许发请求的地方提供,否则为 null |
publicData | String | 公共状态,最多 1024 字节,或 null。只读 |
chatData | String | 聊天状态,最多 1024 字节,或 null;在转发中始终为 null。只读 |
contentSafeAreaInset | Object | top、right、bottom、left、cornerLeft、cornerRight:被消息时间遮挡的区域 |
wallet | Object | Telegram 钱包,或 null(客户端没有钱包、不允许发请求、预览中) |
HapticFeedback | Object | 触感反馈,见下文 |
TelegramWidget 方法
| 方法 | 作用 |
|---|---|
request(data[, options]) | 向机器人发送 1–64 字节数据。返回 Promise,成功时为 { result }(机器人的回应或 null),失败时抛出 WidgetRequestError。只能在点击处理函数中调用,或在允许的地方于后台调用。options 可以是 { wallet: true } |
watchPublicData() / unwatchPublicData() | 开始 / 停止在屏幕可见期间实时轮询共享小组件的公共状态。对静态小组件和预览无效 |
copyText(text) | 点击时复制 1–256 个字符,客户端会弹出显示该文本的提示 |
openLink(url) | 在用户确认后打开 https: URL(≤ 256 个字符,不能是 t.me 域名) |
openTelegramLink(url) | 在 Telegram 内打开 https://t.me/… 链接,效果与点击消息中的链接相同 |
setResizeAnchor(edge) | top(默认)或 bottom:高度变化时气泡的哪条边保持不动 |
ready() | 可选:告诉客户端首屏已经绘制完成 |
onEvent(type, handler) / offEvent(type, handler) | 添加 / 移除事件处理函数(每种事件最多 16 个) |
isProfileAtLeast(n) | 返回 profile >= n |
除 isProfileAtLeast、request 和钱包方法外,所有方法都是同步的。HapticFeedback 提供 impactOccurred(style)(light、medium、heavy、rigid、soft)、notificationOccurred(type)(error、success、warning)和 selectionChanged()。小组件中没有 sendMessage,也不会被告知自己的 widget_id。
事件
| 事件 | 触发时机 |
|---|---|
themeChanged | 聊天主题改变;colorScheme、themeParams 和 CSS 变量已经是新值 |
activated / deactivated | 小组件变为可见 / 隐藏(在 visibilitychange 之后触发) |
chatDataChanged | 机器人修改了聊天状态,chatData 已是新值。转发中永不触发 |
publicDataChanged | 机器人修改了公共状态;对于屏幕上的共享小组件,只在调用了 watch 期间触发。两者同时改变时在 chatDataChanged 之后触发 |
contentSafeAreaChanged | 消息时间遮挡的区域发生变化(说明文字被添加、删除或移动,出现“已编辑”标记) |
处理函数调用时 this 绑定到 TelegramWidget,且不带参数,所以要从对象上读取新值。
WidgetRequestError 错误码
button.addEventListener('click', () => {
status.textContent = '发送中…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? '完成'; },
(error) => { status.textContent = '错误:' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | 含义 |
|---|---|
NOT_ALLOWED | 没有 allow_queries、静态小组件的转发、在不允许后台请求的地方没有点击、预览,或客户端不支持投递请求 |
BUSY | 该小组件的另一个请求或钱包调用正在进行中 |
RATE_LIMITED | 距上次后台调用不足 5 秒,或超过每个用户对每个机器人每 5 秒 5 次 |
TIMEOUT | 机器人 15 秒内没有回应(宕机、太慢,或收不到 widget_query / shared_widget_query) |
FAILED | 其他原因:机器人被屏蔽或删除、消息已不存在、网络故障 |
INVALID_ANSWER | 机器人的回应超出了限制 |
REJECTED、BAD_REQUEST | 仅限钱包调用:用户拒绝,或钱包拒绝了交易或数据 |
数据为空或超过 64 字节时,会在发送前直接抛出 TypeError。
机器人一侧:widget_query 与 answerWidgetQuery
来自原始消息的请求以 Update 中的 widget_query 字段到达;来自共享小组件转发副本的请求则是 shared_widget_query。如果你给 getUpdates 或 setWebhook 传了 allowed_updates,两者都要包含。
{
"update_id": 100000001,
"widget_query": {
"id": "8123456789012345678",
"from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
"chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
"message_id": 4242,
"chat_instance": "901234567890123456",
"type": {"type": "data"},
"data": "refresh"
}
}
通过机器人(内联模式)发送的消息产生的 widget_query,用 inline_message_id 和 chat_type 代替 chat 和 message_id;共享小组件的请求还带有 widget_id。shared_widget_query 只包含 id、from、type、data 和 widget_id。每个请求都要用 answerWidgetQuery 回应(widget_query_id,可选最多 1024 字节的 data);状态则另外用 editMessageWidgetData 或 editSharedWidgetData 修改。from 和 widget_id 由 Telegram 设置,无法伪造,但 data 要当作不可信输入处理。
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
-H "Content-Type: application/json" \
-d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'
CSS 变量
| 变量 | 含义 |
|---|---|
--tg-theme-bg-color、--tg-theme-text-color、--tg-theme-hint-color、--tg-theme-link-color | 气泡背景、正文、次要文字、链接 |
--tg-theme-button-color、--tg-theme-button-text-color | 客户端主按钮 |
--tg-theme-secondary-bg-color、--tg-theme-accent-text-color、--tg-theme-subtitle-text-color、--tg-theme-destructive-text-color、--tg-theme-section-separator-color | 第二层背景、强调色、副标题、危险操作、分隔线 |
--tg-color-scheme | light 或 dark |
--tg-text-font-size、--tg-text-line-height、--tg-text-padding | 消息文字大小(约 15px)、行高(约 1.35)、气泡文字内边距(约 8px 12px) |
--tg-button-bg、--tg-button-text、--tg-button-radius、--tg-button-font、--tg-button-padding、--tg-button-height、--tg-button-pressed-opacity、--tg-button-disabled-opacity | 默认 <button> 使用的客户端按钮样式 |
--tg-content-safe-area-inset-*、--tg-content-safe-area-corner-left / -right | 绘制消息时间的区域(与 env(safe-area-inset-*) 相同) |
客户端以 !important 把这些变量设置在根元素上,你只能在自己的元素上重新定义它们。prefers-color-scheme、light-dark() 和 color-scheme 跟随聊天主题,而不是系统主题。
手势与 touch-action
单击和双击始终归小组件;垂直拖动始终用于滚动聊天(小组件会收到 pointercancel)。长按和水平拖动按元素用 CSS touch-action 认领:auto 交给聊天(消息菜单、滑动回复),pan-y 把水平拖动交给小组件,none 把长按(contextmenu)和水平拖动都交给小组件。经验法则:长按按钮、游戏控件或 canvas 用 touch-action: none,水平滑块或轮播用 pan-y,其他地方保持 auto。请使用指针事件(pointer events),触摸事件(touch events)不会送达。控件要避开前缘 20 px,那里永远无法认领手势。
小组件规范移除了哪些功能
- 表单控件(
input、select、textarea);<button>是唯一的控件。没有键盘事件和焦点。 - 所有网络 API(
fetch、XMLHttpRequest、WebSocket等会抛出NetworkDisabledError)、外部脚本、样式、字体和图片,以及location和history。 vh等相对高度单位、overflow: auto / scroll(变为hidden)、position: sticky、@font-face、:has()、CSS 嵌套。alert、confirm、prompt、navigator.clipboard(请用copyText)、iframe、video、audio、WebGL。
被移除的功能不会让小组件崩溃:相应的元素、声明或事件被丢弃,其余部分照常运行。CSS.supports() 和 @supports 按规范返回结果。
Telegram 小组件限制
| 项目 | 限制值 | 超出后 |
|---|---|---|
| HTML | 32768 字节;zlib level 9 压缩后 4096 字节 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data、public_data | 各 1024 字节 UTF-8 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| 请求数据 | 1–64 字节 | 小组件中抛出 TypeError |
| 回应数据 | 1024 字节 | WIDGET_RESULT_TOO_LARGE |
| 回应时限 | 15 秒 | TIMEOUT;迟到的回应:query is too old |
| 请求频率 | 每个用户对每个机器人每 5 秒 5 次 | RATE_LIMITED |
| 共享小组件编辑 | 每秒 1 次;刷新周期默认 30 秒,cache_time 5–3600 | flood wait;小于 5 时报 invalid cache time specified |
| CPU | 每秒 300 ms JavaScript;单个任务 500 ms | 被限速;小组件被停止 |
| 内存 | 8 MB | 小组件被停止 |
| DOM 节点 | 2000 个 | 小组件被停止 |
| 定时器 | 64 个活动定时器 | RangeError |
localStorage、sessionStorage | 每条消息每个存储区 4 KB | QuotaExceededError |
| 气泡 | 宽 200 px 到气泡最大宽度,高 50–600 px | 被裁剪 |
被停止的小组件会保留最后一帧,并显示“Widget stopped”标记,再次显示时会重建;连续崩溃两次后,会一直保持停止状态,直到客户端重启。
存储、链接、触感反馈与 copyText
- Web Storage 属于这台设备上的这条消息。应用重启后仍然保留,不会发送给机器人,也不会在设备间同步。请把
setItem包在try/catch中。 - 链接:
openLink、openTelegramLink、copyText和request都需要真实的点击:在click处理函数中同步调用,不要放在await或定时器之后。一次点击只解锁一次这类调用。无效 URL 会抛出TypeError;点击<a href="https://…">也同样有效。 - 触感反馈只在小组件可见时播放,单次连发最多 5 次、每秒最多 10 次;手指按在小组件上时及抬起后 5 秒内不受额外限制。桌面端和网页版不会播放。
- copyText 复制 1–256 个字符,并且总会弹出显示所复制文本的提示。
TON 钱包支付简介
小组件可以请用户通过 Telegram 内置钱包付款,数据格式沿用 TON Connect。只在 TelegramWidget.wallet 不为 null 时显示支付按钮。点击时,小组件调用 request(data, { wallet: true });机器人收到的请求中 type 为 {"type": "data", "wallet_card": …},机器人回应一笔新生成的交易。小组件在回应的处理函数中调用 wallet.sendTransaction(),10 秒内无需再次点击:
TelegramWidget.request('pay:42', { wallet: true })
.then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
.then((a) => show(a.result), (e) => showError(e.code));
之后机器人会收到类型为 sent_transaction、带有消息哈希的请求,必须在链上核实这笔交易。出现 TIMEOUT 时付款可能已经完成,所以应向机器人查询订单状态,而不是再付一次。
小组件相关的 Bot API 错误
| 错误 | 原因 |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML 超过 32768 字节或压缩后超过 4096 字节 |
INPUT_MEDIA_WIDGET_HTML_INVALID | html 不是有效的 UTF-8 或包含 NUL 字符 |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data 或 public_data 超过 1024 字节 |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | 状态文本无效(发送时 / 编辑时) |
message is not modified | 编辑没有任何变化;按成功处理 |
可以在 Bot API Tester 中用自己的 Token 试用这些方法,并查看 sendWidget 的参数说明。其他 Bot API 方法见 方法参考;还没有 Token 的话,请看 Telegram Bot Token 获取方法。
常见问题
使用 TelegramWidget 需要引入脚本吗?
不需要。在 Telegram 中,window.TelegramWidget 在小组件的第一段脚本运行之前就已存在,状态、主题和上下文都已就绪。在 Telegram 之外它是 undefined,在浏览器中打开小组件时要先判断。
WidgetRequestError 的 NOT_ALLOWED 是什么意思?
这条消息不允许发送请求:小组件发送时没有 allow_queries,它是静态小组件的转发或预览,或者在不允许后台请求的地方没有通过点击调用 request()。
机器人必须多快回应 widget_query?
15 秒内,使用 answerWidgetQuery。超时后小组件的 Promise 以 TIMEOUT 失败,迟到的回应会被 query is too old 拒绝。即使处理出错,也要回应每一个请求。
小组件能自己修改 chatData 或 publicData 吗?
不能。两者在小组件中都是只读的。只有机器人能通过 sendWidget、editMessageWidgetData 或 editSharedWidgetData 写入状态;小组件只能用 TelegramWidget.request() 向机器人发请求。
有 TelegramWidget.sendMessage 方法吗?
没有。小组件中不存在 sendMessage:任何内容都不会以用户的名义发到聊天里。小组件只能向自己的机器人发请求、复制文本、打开链接和播放触感反馈。
相关教程
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 帖子、评论区小部件和分享按钮,附常见问题排查。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。