Telegram Bot API

Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码

· 12 分钟阅读

下面的 Telegram widget 示例都是完整可运行的:每个示例包含小组件的 HTML(远低于 4 KB 压缩上限)、基于 requests 和长轮询的 Python 机器人代码,以及用户实际看到的效果。从静态订单卡片开始,再用计数器加入请求,最后用共享小组件做一个实时投票。如果你还不了解 Telegram 小组件,请先阅读 Telegram 小组件入门。

开始之前:在正式(生产)环境中,小组件目前只能在与机器人的私聊中使用,并以受保护内容发送,无法转发。群组、内联模式和转发只在测试服务器上可用。下面所有示例都在私聊中运行。

准备工作:安装了 requests 的 Python 3(pip install requests)、机器人 Token(获取方法)和你的 chat id。把每个小组件保存为文件,放在机器人脚本旁边。写代码之前,也可以先把任意小组件粘贴到 Bot API Tester 的 sendWidget 表单,直接在聊天里看看效果。

示例 1:静态订单卡片(不发请求)

一张订单摘要卡片,机器人随订单进度更新其中的状态行。小组件从不向机器人发请求,所以发送时不带 allow_queries。状态保存在 chat_data 中,小组件启动时绘制一次,之后每次 chatDataChanged 事件再重绘。消息还带有说明文字,小组件下方有一个内联键盘按钮。

order.html(928 字节,压缩后 576 字节):

<style>
h3{margin:0 0 6px}
.row{display:flex;justify-content:space-between;gap:12px}
.st{margin-top:10px;padding:6px 10px;border-radius:8px;background:var(--tg-theme-secondary-bg-color)}
.hint{color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<h3>订单 #1042</h3>
<div class="row"><span>2 × 玛格丽特披萨</span><span>$19.00</span></div>
<div class="row"><span>1 × 柠檬水</span><span>$4.50</span></div>
<div class="row"><strong>合计</strong><strong>$23.50</strong></div>
<div class="st"><span id="st">已接单</span> <span class="hint" id="at"></span></div>
<script>
const W = window.TelegramWidget;
function render() {
  let s = null;
  try { s = JSON.parse(W.chatData); } catch (e) {}
  if (!s) return;
  document.getElementById('st').textContent = s.status;
  document.getElementById('at').textContent = s.at ? '更新于 ' + s.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>

bot_order.py:发送卡片,然后修改三次状态:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789  # 你与机器人的私聊
HTML = open("order.html", encoding="utf-8").read()


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not r["ok"]:
        if "message is not modified" in r.get("description", ""):
            return True  # 小组件已经是这个状态
        raise RuntimeError(f"{method}: {r['description']}")
    return r["result"]


msg = call(
    "sendWidget",
    chat_id=CHAT_ID,
    html=HTML,
    chat_data=json.dumps({"status": "已接单"}, ensure_ascii=False),
    caption="订单 #1042:$23.50",
    reply_markup={"inline_keyboard": [[
        {"text": "查看订单", "url": "https://example.com/orders/1042"},
    ]]},
)

for status in ["制作中", "配送中", "已送达"]:
    time.sleep(60)  # 实际项目中:在订单系统通知状态变化时再更新
    call(
        "editMessageWidgetData",
        chat_id=CHAT_ID,
        message_id=msg["message_id"],
        chat_data=json.dumps({"status": status, "at": time.strftime("%H:%M")}, ensure_ascii=False),
    )
// bot_order.mjs
import { readFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const CHAT_ID = 123456789; // 你与机器人的私聊
const HTML = await readFile("order.html", "utf-8");

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (!r.ok) {
    if ((r.description ?? "").includes("message is not modified")) {
      return true; // 小组件已经是这个状态
    }
    throw new Error(`${method}: ${r.description}`);
  }
  return r.result;
}

function hhmm() {
  return new Date().toTimeString().slice(0, 5); // 相当于 time.strftime("%H:%M")
}

const msg = await call("sendWidget", {
  chat_id: CHAT_ID,
  html: HTML,
  chat_data: JSON.stringify({ status: "已接单" }),
  caption: "订单 #1042:$23.50",
  reply_markup: { inline_keyboard: [[
    { text: "查看订单", url: "https://example.com/orders/1042" },
  ]] },
});

for (const status of ["制作中", "配送中", "已送达"]) {
  await sleep(60_000); // 实际项目中:在订单系统通知状态变化时再更新
  await call("editMessageWidgetData", {
    chat_id: CHAT_ID,
    message_id: msg.message_id,
    chat_data: JSON.stringify({ status, at: hhmm() }),
  });
}

用户看到的效果:一张使用聊天配色的卡片,列出商品、合计和“已接单”,下面是说明文字“订单 #1042:$23.50”和“查看订单”按钮。之后每分钟,状态行会静默地变成“制作中”,旁边是灰色的“更新于 19:40”,依此类推:小组件编辑不会显示“已编辑”标记,也不会产生通知。注意“更新于”这个时间:状态应该读起来像一张快照,而不是让人盯着等的进度条。

示例 2:通过 widget_query 请求的计数器

一个带 +1 和 重置 按钮的计数器。点击时调用 TelegramWidget.request();机器人更新计数,用 editMessageWidgetData 写入 chat_data,并通过 answerWidgetQuery 回应同样的值,让小组件立刻显示。版本号 r 让小组件忽略晚于新状态到达的旧状态。

counter.html(1224 字节,压缩后 731 字节):

<style>
.n{font-size:2.4em;font-weight:600;text-align:center;font-variant-numeric:tabular-nums}
.row{display:flex;gap:8px}
.row button{flex:1}
#m{min-height:1.35em;margin-top:6px;text-align:center;color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<div class="n" id="n">0</div>
<div class="row"><button id="like">+1</button><button id="reset">重置</button></div>
<div id="m"></div>
<script>
const W = window.TelegramWidget, $ = (id) => document.getElementById(id);
let rev = -1;
function show(text) {
  let s = null;
  try { s = JSON.parse(text); } catch (e) {}
  if (!s || typeof s.n !== 'number' || s.r < rev) return false;
  rev = s.r;
  $('n').textContent = s.n;
  return true;
}
function ask(data) {
  if (!W) return;
  $('m').textContent = '发送中…';
  W.request(data).then((a) => {
    $('m').textContent = show(a.result) ? '' : '请发送 /start 获取新的计数器';
  }, (e) => {
    $('m').textContent = e.code === 'TIMEOUT' ? '机器人没有响应' : '未发送:' + e.code;
  });
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
  W.onEvent('chatDataChanged', () => show(W.chatData));
  show(W.chatData);
}
</script>

小组件代码中的要点:

bot_counter.py:长轮询,allowed_updates 中包含 widget_query:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
HTML = open("counter.html", encoding="utf-8").read()
counters = {}  # (chat_id, message_id) -> {"n": 计数, "r": 版本号}


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if r["ok"]:
        return r["result"]
    if "message is not modified" in r.get("description", ""):
        return True  # 状态没有变化:按成功处理
    print(f"{method} failed: {r.get('description')}")
    return None


def dump(state):
    return json.dumps(state, separators=(",", ":"))


def send_counter(chat_id):
    state = {"n": 0, "r": 0}
    msg = call("sendWidget", chat_id=chat_id, html=HTML, chat_data=dump(state),
               caption="点 +1 开始计数", allow_queries=True)
    if msg:
        counters[(chat_id, msg["message_id"])] = state


def on_widget_query(q):
    key = (q["chat"]["id"], q["message_id"])
    state = counters.get(key)
    if state is None or q["data"] not in ("like", "reset"):
        # 未知消息(例如机器人重启过)或未知数据:同样要回应
        call("answerWidgetQuery", widget_query_id=q["id"])
        return
    new = {"n": state["n"] + 1 if q["data"] == "like" else 0, "r": state["r"] + 1}
    if call("editMessageWidgetData", chat_id=key[0], message_id=key[1],
            chat_data=dump(new)):
        counters[key] = new  # 编辑成功后才提交新状态
    call("answerWidgetQuery", widget_query_id=q["id"], data=dump(counters[key]))


def main():
    offset = 0
    while True:
        updates = call("getUpdates", offset=offset, timeout=30,
                       allowed_updates=["message", "widget_query"])
        if updates is None:
            time.sleep(3)
            continue
        for u in updates:
            offset = u["update_id"] + 1
            if "widget_query" in u:
                on_widget_query(u["widget_query"])
            elif u.get("message", {}).get("text") == "/start":
                send_counter(u["message"]["chat"]["id"])


main()
// bot_counter.mjs
import { readFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const HTML = await readFile("counter.html", "utf-8");
const counters = new Map(); // "chat_id:message_id" -> {n: 计数, r: 版本号}

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (r.ok) return r.result;
  if ((r.description ?? "").includes("message is not modified")) {
    return true; // 状态没有变化:按成功处理
  }
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function dump(state) {
  return JSON.stringify(state); // 本身就是紧凑格式,相当于 separators=(",", ":")
}

async function sendCounter(chatId) {
  const state = { n: 0, r: 0 };
  const msg = await call("sendWidget", {
    chat_id: chatId, html: HTML, chat_data: dump(state),
    caption: "点 +1 开始计数", allow_queries: true,
  });
  if (msg) counters.set(`${chatId}:${msg.message_id}`, state);
}

async function onWidgetQuery(q) {
  const chatId = q.chat.id, messageId = q.message_id;
  const key = `${chatId}:${messageId}`;
  const state = counters.get(key);
  if (state === undefined || !["like", "reset"].includes(q.data)) {
    // 未知消息(例如机器人重启过)或未知数据:同样要回应
    await call("answerWidgetQuery", { widget_query_id: q.id });
    return;
  }
  const next = { n: q.data === "like" ? state.n + 1 : 0, r: state.r + 1 };
  if (await call("editMessageWidgetData", {
    chat_id: chatId, message_id: messageId, chat_data: dump(next),
  })) {
    counters.set(key, next); // 编辑成功后才提交新状态
  }
  await call("answerWidgetQuery", { widget_query_id: q.id, data: dump(counters.get(key)) });
}

async function main() {
  let offset = 0;
  while (true) {
    const updates = await call("getUpdates", {
      offset, timeout: 30, allowed_updates: ["message", "widget_query"],
    });
    if (updates === null) {
      await sleep(3000);
      continue;
    }
    for (const u of updates) {
      offset = u.update_id + 1;
      if (u.widget_query) {
        await onWidgetQuery(u.widget_query);
      } else if (u.message?.text === "/start") {
        await sendCounter(u.message.chat.id);
      }
    }
  }
}

main();

用户看到的效果:发送 /start 后,出现一个大大的“0”和两个原生按钮。点 +1 先显示“发送中…”,随后变成新的数字。如果机器人停止运行,15 秒后小组件会显示“机器人没有响应”(TIMEOUT)。机器人重启后内存中的字典是空的,于是机器人不带数据回应,小组件提示用户发送 /start;真实项目应把状态按聊天和消息保存在数据库中。

示例 3:用共享小组件做实时投票

同一个投票显示在多个私聊中,共用一份结果。第一次带 is_shared 和 allow_queries 的 sendWidget 创建共享小组件;机器人保存返回消息中的 widget.id,之后每当有用户发送 /start,就用 sendSharedWidget 给他发送同一个投票。票数通过 editSharedWidgetData 写入 public_data,所有显示这个投票的消息都会拿到新的总数。

poll.html(1799 字节,压缩后 1036 字节):

<style>
.o{display:block;width:100%;margin:6px 0;text-align:left}
.me{outline:2px solid var(--tg-theme-button-color)}
.bar{height:4px;margin-top:4px;border-radius:2px;background:var(--tg-theme-button-color)}
.h{color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<strong>下一篇教程用哪种语言?</strong>
<div id="list"></div>
<div class="h" id="msg"></div>
<script>
const W = window.TelegramWidget, $ = (id) => document.getElementById(id);
const OPTS = ['Python', 'JavaScript', 'Go'];
let st = { v: [0, 0, 0], r: -1 }, mine = null;
try { mine = JSON.parse(localStorage.getItem('vote')); } catch (e) {}
function take(text) {
  let s = null;
  try { s = JSON.parse(text); } catch (e) {}
  if (s && Array.isArray(s.v) && s.r >= st.r) { st = s; draw(); }
}
function draw() {
  const total = st.v.reduce((a, b) => a + b, 0);
  $('list').replaceChildren(...OPTS.map((name, i) => {
    const b = document.createElement('button');
    const pct = total ? Math.round(st.v[i] / total * 100) : 0;
    b.className = 'o' + (mine === i ? ' me' : '');
    b.innerHTML = name + ' <span class="h">' + pct + '% (' + st.v[i] + ')</span><div class="bar" style="width:' + pct + '%"></div>';
    b.addEventListener('click', () => vote(i));
    return b;
  }));
}
function vote(i) {
  if (!W) return;
  $('msg').textContent = '发送中…';
  W.request('vote:' + i).then((a) => {
    mine = i;
    try { localStorage.setItem('vote', String(i)); } catch (e) {}
    $('msg').textContent = '投票成功';
    take(a.result);
    draw();
  }, (e) => {
    $('msg').textContent = e.code === 'NOT_ALLOWED' ? '请打开机器人后再投票' : '未发送:' + e.code;
  });
}
if (W) {
  W.onEvent('publicDataChanged', () => take(W.publicData));
  W.watchPublicData();
  take(W.publicData);
}
draw();
</script>

小组件调用了 watchPublicData():如果不调用,已经显示在屏幕上的共享小组件只有在消息重新加载时才会拿到新的公共状态。投票可见期间,客户端按小组件的刷新周期轮询公共状态,机器人用 cache_time 把它设为 10 秒。用户自己的选择保存在 localStorage 中,它属于这台设备上的这条消息。

bot_poll.py:按用户记录投票,编辑合并为每秒一次:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789  # 你自己与机器人的私聊
HTML = open("poll.html", encoding="utf-8").read()
OPTIONS = 3
DB_FILE = "poll.json"
CAPTION = "投票:下一篇教程用哪种语言?"

try:
    with open(DB_FILE) as f:
        db = json.load(f)
except FileNotFoundError:
    db = {"widget_id": None, "votes": {}, "r": 0}  # votes:用户 id -> 选项
dirty, last_edit = False, 0.0


def save():
    with open(DB_FILE, "w") as f:
        json.dump(db, f)


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if r["ok"]:
        return r["result"]
    if "message is not modified" in r.get("description", ""):
        return True
    print(f"{method} failed: {r.get('description')}")
    return None


def public_state():
    v = [0] * OPTIONS
    for option in db["votes"].values():
        v[option] += 1
    return json.dumps({"v": v, "r": db["r"]}, separators=(",", ":"))


def flush():
    """每秒最多写入一次公共状态(共享小组件的限制)。"""
    global dirty, last_edit
    if dirty and time.monotonic() - last_edit >= 1:
        last_edit = time.monotonic()
        if call("editSharedWidgetData", widget_id=db["widget_id"],
                public_data=public_state(), cache_time=10):
            dirty = False


def on_query(q):
    global dirty
    data = q["data"]
    if q.get("widget_id") == db["widget_id"] and data.startswith("vote:") \
            and data[5:].isdigit() and int(data[5:]) < OPTIONS:
        db["votes"][str(q["from"]["id"])] = int(data[5:])  # 每个用户一票
        db["r"] += 1
        save()
        dirty = True
    # 投票者立即从回应中看到新结果,其他人通过编辑获得
    call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())


def main():
    if not db["widget_id"]:
        # 第一次带 is_shared 的发送会创建共享小组件
        msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
                   public_data=public_state(), is_shared=True, allow_queries=True,
                   caption=CAPTION)
        db["widget_id"] = msg["widget"]["id"]
        save()
    offset = 0
    while True:
        updates = call("getUpdates", offset=offset, timeout=1 if dirty else 25,
                       allowed_updates=["message", "widget_query", "shared_widget_query"])
        if updates is None:
            time.sleep(3)
            continue
        for u in updates:
            offset = u["update_id"] + 1
            q = u.get("widget_query") or u.get("shared_widget_query")
            if q:
                on_query(q)
            elif u.get("message", {}).get("text") == "/start":
                call("sendSharedWidget", chat_id=u["message"]["chat"]["id"],
                     widget_id=db["widget_id"], caption=CAPTION)
        flush()


main()
// bot_poll.mjs
import { readFile, writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const ADMIN_CHAT_ID = 123456789; // 你自己与机器人的私聊
const HTML = await readFile("poll.html", "utf-8");
const OPTIONS = 3;
const DB_FILE = "poll.json";
const CAPTION = "投票:下一篇教程用哪种语言?";

let db;
try {
  db = JSON.parse(await readFile(DB_FILE, "utf-8"));
} catch (e) {
  if (e.code !== "ENOENT") throw e;
  db = { widget_id: null, votes: {}, r: 0 }; // votes:用户 id -> 选项
}
let dirty = false, lastEdit = -Infinity;

async function save() {
  await writeFile(DB_FILE, JSON.stringify(db));
}

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (r.ok) return r.result;
  if ((r.description ?? "").includes("message is not modified")) return true;
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function publicState() {
  const v = new Array(OPTIONS).fill(0);
  for (const option of Object.values(db.votes)) v[option] += 1;
  return JSON.stringify({ v, r: db.r });
}

// 每秒最多写入一次公共状态(共享小组件的限制)。
async function flush() {
  const now = performance.now() / 1000; // 单调时钟,单位:秒
  if (dirty && now - lastEdit >= 1) {
    lastEdit = now;
    if (await call("editSharedWidgetData", {
      widget_id: db.widget_id, public_data: publicState(), cache_time: 10,
    })) {
      dirty = false;
    }
  }
}

async function onQuery(q) {
  const data = q.data;
  const digits = data.slice(5);
  if (q.widget_id === db.widget_id && data.startsWith("vote:")
      && /^\d+$/.test(digits) && Number(digits) < OPTIONS) {
    db.votes[String(q.from.id)] = Number(digits); // 每个用户一票
    db.r += 1;
    await save();
    dirty = true;
  }
  // 投票者立即从回应中看到新结果,其他人通过编辑获得
  await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}

async function main() {
  if (!db.widget_id) {
    // 第一次带 is_shared 的发送会创建共享小组件
    const msg = await call("sendWidget", {
      chat_id: ADMIN_CHAT_ID, html: HTML,
      public_data: publicState(), is_shared: true, allow_queries: true,
      caption: CAPTION,
    });
    db.widget_id = msg.widget.id;
    await save();
  }
  let offset = 0;
  while (true) {
    const updates = await call("getUpdates", {
      offset, timeout: dirty ? 1 : 25,
      allowed_updates: ["message", "widget_query", "shared_widget_query"],
    });
    if (updates === null) {
      await sleep(3000);
      continue;
    }
    for (const u of updates) {
      offset = u.update_id + 1;
      const q = u.widget_query || u.shared_widget_query;
      if (q) {
        await onQuery(q);
      } else if (u.message?.text === "/start") {
        await call("sendSharedWidget", {
          chat_id: u.message.chat.id,
          widget_id: db.widget_id,
          caption: CAPTION,
        });
      }
    }
    await flush();
  }
}

main();

用户看到的效果:三个带百分比和进度条的原生按钮。点击后显示“投票成功”,自己选的选项带有描边,票数立即包含自己这一票(来自回应)。其他用户的投票大约 10 秒内出现,无需重新打开聊天。

示例 4:浏览器预览、体积检查与错误处理

小组件本质上是 HTML,把桌面浏览器窗口调到 320–430 px 宽,就能快速看一眼布局。Telegram 之外没有 TelegramWidget,所以要在小组件代码前放一个替身对象。把它放在单独的文件 stub.html 中,以免混进要发送的内容。下面是官方文档中替身的精简版,预设为计数器的数据:

<style>:root{--tg-theme-bg-color:#fff;--tg-theme-text-color:#000;--tg-theme-hint-color:#707579;
--tg-theme-link-color:#3390ec;--tg-theme-button-color:#3390ec;--tg-theme-button-text-color:#fff;
--tg-theme-secondary-bg-color:#f1f1f4}body{max-width:360px}</style>
<script>
window.TelegramWidget = window.TelegramWidget || {
  profile: 1, colorScheme: 'light', themeParams: {}, isActive: true, isPreview: false,
  isForward: false, chatType: 'private', viewer: { id: 1, first_name: 'Test' },
  chatData: '{"n":4,"r":1}', publicData: null, wallet: null,
  HapticFeedback: { impactOccurred() { return this; }, notificationOccurred() { return this; }, selectionChanged() { return this; } },
  onEvent() {}, offEvent() {}, ready() {}, watchPublicData() {}, unwatchPublicData() {},
  openLink: (url) => console.log('openLink', url), openTelegramLink: (url) => console.log('openTelegramLink', url),
  copyText: (text) => console.log('copyText', text),
  request: (data) => { console.log('request', data); return Promise.resolve({ result: '{"n":5,"r":2}' }); },
};
</script>

preview.py 把替身和小组件拼接成 preview.html:

import sys

stub = open("stub.html", encoding="utf-8").read()
widget = open(sys.argv[1], encoding="utf-8").read()
with open("preview.html", "w", encoding="utf-8") as f:
    f.write(stub + widget)
print("请在 320-430 px 宽的浏览器窗口中打开 preview.html")
// preview.mjs
import { readFile, writeFile } from "node:fs/promises";

const stub = await readFile("stub.html", "utf-8");
const widget = await readFile(process.argv[2], "utf-8");
await writeFile("preview.html", stub + widget, "utf-8");
console.log("请在 320-430 px 宽的浏览器窗口中打开 preview.html");

运行 python3 preview.py counter.html,打开 preview.html,在控制台里能看到 request like。可以把 chatData、publicData、viewer 和 isForward 改成你想查看的情况。注意:浏览器会绘制 Telegram 会移除的内容(输入框、vh、滚动),也不执行任何限制。

check_widget.py 在发送前按服务器的方式(Python zlib,level 9)计算体积。在 JavaScript 项目中可以使用 Node.js 版本,但 Node 的 zlib 结果可能相差几个字节,接近 4096 时请以 Python 的数字为准:

import sys
import zlib

raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8")  # UTF-8 无效时抛出 UnicodeDecodeError
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} 字节,zlib level 9 压缩后 {packed} 字节")
if b"\x00" in raw:
    sys.exit("包含 NUL 字符:服务器会返回 INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
    sys.exit("体积过大:服务器会返回 INPUT_MEDIA_WIDGET_TOO_LARGE")
print("OK")
// check_widget.mjs
import { readFile } from "node:fs/promises";
import { deflateSync } from "node:zlib";

function fail(message) {
  console.error(message);
  process.exit(1);
}

const raw = await readFile(process.argv[2]);
new TextDecoder("utf-8", { fatal: true }).decode(raw); // UTF-8 无效时抛出 TypeError
// Node 自带的 zlib 与服务器(Python)的结果可能相差几个字节:
// 请在 4096 之下留出一点余量
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} 字节,zlib level 9 压缩后 ${packed} 字节`);
if (raw.includes(0)) {
  fail("包含 NUL 字符:服务器会返回 INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
  fail("体积过大:服务器会返回 INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");
$ python3 check_widget.py counter.html
1224 字节,zlib level 9 压缩后 731 字节
OK

运行这些示例时可能遇到的 Bot API 错误:

错误原因解决方法
INPUT_MEDIA_WIDGET_TOO_LARGEHTML 超过 32768 字节,或压缩后超过 4096 字节删除注释和无用代码,用 SVG 和 CSS 代替 data: 图片
INPUT_MEDIA_WIDGET_HTML_INVALIDHTML 不是有效的 UTF-8,或包含 NUL 字符以 UTF-8 文本读取文件,作为字符串发送
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data 或 public_data 超过 1024 字节使用短键名和紧凑 JSON(separators=(",", ":"))
message is not modified编辑设置的状态与当前相同按成功处理
query is too old超过 15 秒才调用 answerWidgetQuery先回应,再做耗时操作
invalid cache time specifiedcache_time 小于 5使用 5–3600 秒

小组件中被拒绝的请求,其 code 可能是:NOT_ALLOWED(没有 allow_queries、不是由点击触发、预览,或静态小组件的转发)、BUSY(同一时间只能有一个请求)、RATE_LIMITED(超过每 5 秒 5 次)、TIMEOUT、FAILED 和 INVALID_ANSWER。数据为空或超过 64 字节时,会在发送前直接抛出 TypeError。

发给用户前的检查清单

  1. 压缩后体积小于 4096 字节(check_widget.py)。
  2. 状态为 null 或缺少 TelegramWidget 时,小组件也能显示有用的内容。
  3. 颜色来自 --tg-theme-* 变量,已在浅色和深色聊天主题下检查过。
  4. 消息带有说明文字,通知和旧版客户端显示的就是它。
  5. 机器人在 15 秒内回应每一个 widget_query,且 allowed_updates 中包含 widget_query 和 shared_widget_query。
  6. 在你这一侧对编辑做了限速,并且不把“message is not modified”当作错误。

这里用到的所有属性、事件和限制,都列在 TelegramWidget JavaScript API 参考中;官方文档见 core.telegram.org/bots/widgets。各方法的参数可以在 Bot API 方法参考中查看;还没有机器人的话,先看 创建 Telegram 机器人教程。

常见问题

怎么把 HTML 传给 sendWidget?

把整个文档作为字符串参数 html 传入,并以 JSON 格式发送请求,例如 Python 中的 requests.post(url, json={"chat_id": 123456789, "html": html}),这样 HTML 里的引号和换行都会被正确编码。

为什么点击后小组件显示 TIMEOUT?

机器人没有在 15 秒内调用 answerWidgetQuery。常见原因是机器人没在运行,或者传了不含 widget_query(以及 shared_widget_query)的 allowed_updates,导致根本收不到请求。

editMessageWidgetData 返回 "message is not modified" 怎么办?

按成功处理:小组件已经是这个状态了。新的 chat_data 或 public_data 与当前值相同时就会出现这个错误。触发这次编辑的小组件请求仍然要回应。

怎么用共享小组件做实时投票?

带 is_shared 和 allow_queries 发送一次小组件,保存 widget.id,再用 sendSharedWidget 发到其他聊天;按(widget_id, from.id)统计票数,并用 editSharedWidgetData 每秒最多写入一次结果。小组件中必须调用 watchPublicData()。

怎么在浏览器里预览小组件?

在 Telegram 之外 window.TelegramWidget 是 undefined,所以要在单独的预览文件中,把一个简易替身对象和主题变量放在小组件代码前面。浏览器不会执行小组件规范和各项限制,发给用户之前一定要在 Telegram 里实测。

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

Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。