Telegram Bot API

TelegramWidget JavaScript API:属性、事件、错误码与限制参考

· 10 分钟阅读

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 属性

属性类型说明
profileInteger客户端执行的小组件规范版本:当前为 1
colorSchemeStringlight 或 dark,即聊天的配色方案(也可通过 --tg-color-scheme 获取)
themeParamsObject气泡的配色,值为 #rrggbb 字符串,键名与 Mini App 的 themeParams 相同
isActiveBoolean小组件当前可见(!document.hidden)
isPreviewBoolean发送前显示的内联结果预览:不响应点击,不能发请求
isForwardBoolean是转发的副本
chatTypeStringprivate、group、supergroup、channel;在转发或预览中为 null
viewerObject正在查看的用户:id、first_name、last_name、username、is_premium;只在小组件允许发请求的地方提供,否则为 null
publicDataString公共状态,最多 1024 字节,或 null。只读
chatDataString聊天状态,最多 1024 字节,或 null;在转发中始终为 null。只读
contentSafeAreaInsetObjecttop、right、bottom、left、cornerLeft、cornerRight:被消息时间遮挡的区域
walletObjectTelegram 钱包,或 null(客户端没有钱包、不允许发请求、预览中)
HapticFeedbackObject触感反馈,见下文

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-schemelight 或 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,那里永远无法认领手势。

小组件规范移除了哪些功能

被移除的功能不会让小组件崩溃:相应的元素、声明或事件被丢弃,其余部分照常运行。CSS.supports() 和 @supports 按规范返回结果。

Telegram 小组件限制

项目限制值超出后
HTML32768 字节;zlib level 9 压缩后 4096 字节INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data、public_data各 1024 字节 UTF-8INPUT_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–3600flood wait;小于 5 时报 invalid cache time specified
CPU每秒 300 ms JavaScript;单个任务 500 ms被限速;小组件被停止
内存8 MB小组件被停止
DOM 节点2000 个小组件被停止
定时器64 个活动定时器RangeError
localStorage、sessionStorage每条消息每个存储区 4 KBQuotaExceededError
气泡宽 200 px 到气泡最大宽度,高 50–600 px被裁剪

被停止的小组件会保留最后一帧,并显示“Widget stopped”标记,再次显示时会重建;连续崩溃两次后,会一直保持停止状态,直到客户端重启。

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_LARGEHTML 超过 32768 字节或压缩后超过 4096 字节
INPUT_MEDIA_WIDGET_HTML_INVALIDhtml 不是有效的 UTF-8 或包含 NUL 字符
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_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 的区别。