Telegram Bot API

Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python

· 12 phút đọc

Các ví dụ widget Telegram dưới đây đầy đủ và chạy được ngay: mỗi ví dụ gồm HTML của widget (nhỏ hơn nhiều so với giới hạn 4 KB sau nén), code bot Python dùng requests và long polling, cùng mô tả người dùng sẽ thấy gì. Bắt đầu với thẻ đơn hàng tĩnh, thêm request bằng bộ đếm, rồi dựng bình chọn trực tiếp dạng widget dùng chung. Nếu bạn mới làm quen, hãy đọc widget Telegram là gì trước.

Trước khi bắt đầu: trên production, widget hiện chỉ chạy trong chat riêng với bot và được gửi với nội dung được bảo vệ nên không chuyển tiếp được. Group, inline mode và chuyển tiếp chỉ chạy trên test server. Mọi ví dụ bên dưới đều chạy trong chat riêng.

Bạn cần: Python 3 với requests (pip install requests), token bot (cách lấy token) và chat id của bạn. Lưu từng widget thành file cạnh script bot. Trước khi viết code, bạn có thể dán bất kỳ widget nào vào form sendWidget trong Bot API Tester để xem nó trong chat.

Ví dụ 1: thẻ đơn hàng tĩnh (không có request)

Thẻ tóm tắt đơn hàng có dòng trạng thái được bot cập nhật theo tiến trình. Widget không hỏi bot gì cả nên được gửi không có allow_queries. Trạng thái nằm trong chat_data; widget vẽ nó lúc khởi động và mỗi khi có sự kiện chatDataChanged. Tin nhắn còn có caption và inline keyboard bên dưới widget.

order.html (933 byte, 558 byte sau nén):

<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>Đơn hàng #1042</h3>
<div class="row"><span>2 × Margherita</span><span>$19.00</span></div>
<div class="row"><span>1 × Nước chanh</span><span>$4.50</span></div>
<div class="row"><strong>Tổng</strong><strong>$23.50</strong></div>
<div class="st"><span id="st">Đã nhận đơn</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 ? 'lúc ' + s.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>

bot_order.py: gửi thẻ, rồi đổi trạng thái ba lần:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789  # chat riêng của bạn với bot
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  # widget đã hiển thị đúng trạng thái này
        raise RuntimeError(f"{method}: {r['description']}")
    return r["result"]


msg = call(
    "sendWidget",
    chat_id=CHAT_ID,
    html=HTML,
    chat_data=json.dumps({"status": "Đã nhận đơn"}),
    caption="Đơn hàng #1042: $23.50",
    reply_markup={"inline_keyboard": [[
        {"text": "Theo dõi đơn hàng", "url": "https://example.com/orders/1042"},
    ]]},
)

for status in ["Đang nấu", "Đang giao", "Đã giao"]:
    time.sleep(60)  # bot thật: khi hệ thống đơn hàng báo có thay đổi
    call(
        "editMessageWidgetData",
        chat_id=CHAT_ID,
        message_id=msg["message_id"],
        chat_data=json.dumps({"status": status, "at": time.strftime("%H:%M")}),
    )
// 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; // chat riêng của bạn với bot
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; // widget đã hiển thị đúng trạng thái này
    }
    throw new Error(`${method}: ${r.description}`);
  }
  return r.result;
}

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

const msg = await call("sendWidget", {
  chat_id: CHAT_ID,
  html: HTML,
  chat_data: JSON.stringify({ status: "Đã nhận đơn" }),
  caption: "Đơn hàng #1042: $23.50",
  reply_markup: { inline_keyboard: [[
    { text: "Theo dõi đơn hàng", url: "https://example.com/orders/1042" },
  ]] },
});

for (const status of ["Đang nấu", "Đang giao", "Đã giao"]) {
  await sleep(60_000); // bot thật: khi hệ thống đơn hàng báo có thay đổi
  await call("editMessageWidgetData", {
    chat_id: CHAT_ID,
    message_id: msg.message_id,
    chat_data: JSON.stringify({ status, at: hhmm() }),
  });
}

Người dùng thấy gì: một thẻ theo màu của chat với danh sách món, tổng tiền và "Đã nhận đơn", caption "Đơn hàng #1042: $23.50" và nút "Theo dõi đơn hàng" bên dưới. Mỗi phút dòng trạng thái lặng lẽ đổi sang "Đang nấu" kèm chữ xám "lúc 19:40", và cứ thế tiếp: sửa widget không tạo dấu "đã sửa" và không gửi thông báo. Mốc giờ giúp trạng thái được hiểu là một ảnh chụp tại thời điểm đó, không phải thanh tiến trình để ngồi chờ.

Ví dụ 2: bộ đếm dùng request widget_query

Bộ đếm có nút +1 và Đặt lại. Mỗi lần chạm gọi TelegramWidget.request(); bot tăng số đếm, ghi vào chat_data bằng editMessageWidgetData và trả lời đúng giá trị đó qua answerWidgetQuery để widget hiện ngay. Số revision r giúp widget bỏ qua trạng thái cũ đến sau trạng thái mới.

counter.html (1250 byte, 731 byte sau nén):

<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">Đặt lại</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 = 'Đang gửi…';
  W.request(data).then((a) => {
    $('m').textContent = show(a.result) ? '' : 'Gửi /start để nhận bộ đếm mới';
  }, (e) => {
    $('m').textContent = e.code === 'TIMEOUT' ? 'Bot không phản hồi' : 'Chưa gửi được: ' + e.code;
  });
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
  W.onEvent('chatDataChanged', () => show(W.chatData));
  show(W.chatData);
}
</script>

Điểm chính trong code widget:

bot_counter.py: long polling với allowed_updates có 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": số đếm, "r": revision}


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  # không có gì thay đổi: coi như thành công
    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="Bấm +1 để đếm", 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"):
        # tin nhắn lạ (vd. bot vừa khởi động lại) hoặc data lạ: vẫn phải trả lời
        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  # chỉ ghi nhận sau khi sửa thành công
    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: số đếm, r: revision}

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; // không có gì thay đổi: coi như thành công
  }
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function dump(state) {
  return JSON.stringify(state); // vốn đã gọn, giống 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: "Bấm +1 để đếm", 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)) {
    // tin nhắn lạ (vd. bot vừa khởi động lại) hoặc data lạ: vẫn phải trả lời
    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); // chỉ ghi nhận sau khi sửa thành công
  }
  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();

Người dùng thấy gì: sau /start là số "0" lớn với hai nút native. Chạm +1 sẽ hiện "Đang gửi…", rồi số mới. Nếu bot tắt, sau 15 giây widget báo "Bot không phản hồi" (TIMEOUT). Sau khi bot khởi động lại, dictionary trong bộ nhớ rỗng nên bot trả lời không kèm data và widget nhắc người dùng gửi /start; bot thật nên lưu trạng thái trong database, theo khóa chat và message.

Ví dụ 3: bình chọn trực tiếp bằng widget dùng chung

Một cuộc bình chọn hiện trong nhiều chat riêng nhưng chỉ có một bộ kết quả. Lần sendWidget đầu tiên với is_shared và allow_queries tạo widget dùng chung; bot lưu widget.id từ tin nhắn trả về và về sau gửi cùng cuộc bình chọn cho mọi người dùng gửi /start bằng sendSharedWidget. Phiếu được ghi vào public_data qua editSharedWidgetData, nên mọi tin nhắn hiển thị cuộc bình chọn đều nhận tổng mới.

poll.html (1841 byte, 1039 byte sau nén):

<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>Bài hướng dẫn tới nên dùng ngôn ngữ nào?</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 = 'Đang gửi…';
  W.request('vote:' + i).then((a) => {
    mine = i;
    try { localStorage.setItem('vote', String(i)); } catch (e) {}
    $('msg').textContent = 'Đã ghi nhận phiếu';
    take(a.result);
    draw();
  }, (e) => {
    $('msg').textContent = e.code === 'NOT_ALLOWED' ? 'Mở bot để bình chọn' : 'Chưa gửi được: ' + e.code;
  });
}
if (W) {
  W.onEvent('publicDataChanged', () => take(W.publicData));
  W.watchPublicData();
  take(W.publicData);
}
draw();
</script>

Widget gọi watchPublicData(): thiếu lệnh này, widget dùng chung đang hiện trên màn hình chỉ nhận trạng thái mới khi tin nhắn được tải lại. Trong lúc cuộc bình chọn hiển thị, ứng dụng hỏi trạng thái công khai theo chu kỳ làm mới của widget, ở đây bot đặt 10 giây bằng cache_time. Lựa chọn của người dùng được lưu trong localStorage, thuộc về đúng tin nhắn này trên thiết bị này.

bot_poll.py: phiếu lưu theo người dùng, gộp các lần sửa thành tối đa một lần mỗi giây:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789  # chat riêng của chính bạn với bot
HTML = open("poll.html", encoding="utf-8").read()
OPTIONS = 3
DB_FILE = "poll.json"

try:
    with open(DB_FILE) as f:
        db = json.load(f)
except FileNotFoundError:
    db = {"widget_id": None, "votes": {}, "r": 0}  # votes: user id -> lựa chọn
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():
    """Ghi trạng thái dùng chung tối đa một lần mỗi giây (giới hạn của widget dùng chung)."""
    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:])  # mỗi người một phiếu
        db["r"] += 1
        save()
        dirty = True
    # người bình chọn thấy số mới ngay; những người khác nhận qua lần sửa
    call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())


def main():
    if not db["widget_id"]:
        # lần gửi đầu tiên với is_shared tạo ra widget dùng chung
        msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
                   public_data=public_state(), is_shared=True, allow_queries=True,
                   caption="Bình chọn: ngôn ngữ cho bài hướng dẫn tới?")
        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="Bình chọn: ngôn ngữ cho bài hướng dẫn tới?")
        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; // chat riêng của chính bạn với bot
const HTML = await readFile("poll.html", "utf-8");
const OPTIONS = 3;
const DB_FILE = "poll.json";

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: user id -> lựa chọn
}
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 });
}

// Ghi trạng thái dùng chung tối đa một lần mỗi giây (giới hạn của widget dùng chung).
async function flush() {
  const now = performance.now() / 1000; // giây theo đồng hồ đơn điệu
  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); // mỗi người một phiếu
    db.r += 1;
    await save();
    dirty = true;
  }
  // người bình chọn thấy số mới ngay; những người khác nhận qua lần sửa
  await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}

async function main() {
  if (!db.widget_id) {
    // lần gửi đầu tiên với is_shared tạo ra widget dùng chung
    const msg = await call("sendWidget", {
      chat_id: ADMIN_CHAT_ID, html: HTML,
      public_data: publicState(), is_shared: true, allow_queries: true,
      caption: "Bình chọn: ngôn ngữ cho bài hướng dẫn tới?",
    });
    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: "Bình chọn: ngôn ngữ cho bài hướng dẫn tới?",
        });
      }
    }
    await flush();
  }
}

main();

Người dùng thấy gì: ba nút native kèm phần trăm và thanh kết quả. Sau khi chạm là "Đã ghi nhận phiếu", lựa chọn của người dùng được viền nổi bật và số phiếu đã tính luôn phiếu của họ (lấy từ câu trả lời). Phiếu của người khác hiện ra trong khoảng 10 giây mà không cần mở lại chat.

Ví dụ 4: xem thử trên trình duyệt, đo kích thước và xử lý lỗi

Widget là HTML, nên một cửa sổ trình duyệt rộng 320–430 px đủ để xem nhanh. Ngoài Telegram không có TelegramWidget, nên hãy đặt một đối tượng giả lập phía trên code widget. Để nó trong file riêng, stub.html, để không bao giờ lẫn vào thứ bạn gửi đi. Đây là bản rút gọn của stub trong tài liệu chính thức, đặt sẵn cho bộ đếm:

<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 ghép stub với widget thành 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("Mở preview.html trong cửa sổ trình duyệt rộng 320-430 px")
// 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("Mở preview.html trong cửa sổ trình duyệt rộng 320-430 px");

Chạy python3 preview.py counter.html, mở preview.html và xem console có dòng request like. Đổi chatData, publicData, viewer và isForward theo trường hợp muốn xem. Lưu ý trình duyệt vẫn vẽ những thứ Telegram loại bỏ (input, vh, cuộn) và không áp dụng giới hạn nào.

check_widget.py đo kích thước đúng như server (zlib của Python, mức 9) trước khi gửi. Bản Node.js tiện dùng trong dự án JavaScript, nhưng zlib của Node có thể lệch vài byte, nên khi gần mức 4096 hãy tin con số của Python:

import sys
import zlib

raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8")  # ném UnicodeDecodeError nếu UTF-8 không hợp lệ
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bytes, {packed} bytes after zlib level 9")
if b"\x00" in raw:
    sys.exit("NUL character: the server answers INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
    sys.exit("too large: the server answers 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); // ném TypeError nếu UTF-8 không hợp lệ
// zlib đi kèm Node có thể lệch vài byte so với server (Python):
// nên chừa một khoảng nhỏ dưới 4096
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bytes, ${packed} bytes after zlib level 9`);
if (raw.includes(0)) {
  fail("NUL character: the server answers INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
  fail("too large: the server answers INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");
$ python3 check_widget.py counter.html
1250 bytes, 731 bytes after zlib level 9
OK

Các lỗi Bot API có thể gặp khi chạy những ví dụ này:

LỗiNguyên nhânCách sửa
INPUT_MEDIA_WIDGET_TOO_LARGEHTML quá 32768 byte hoặc quá 4096 byte sau nénBỏ comment và code thừa, ưu tiên SVG và CSS thay cho ảnh data:
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 không hợp lệ hoặc có ký tự NUL trong HTMLĐọc file dưới dạng văn bản UTF-8 và gửi như một chuỗi
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data hoặc public_data quá 1024 byteKhóa ngắn, JSON gọn (separators=(",", ":"))
message is not modifiedLần sửa đặt đúng trạng thái đang cóCoi là thành công
query is too oldGọi answerWidgetQuery sau 15 giâyTrả lời trước, việc chậm làm sau
invalid cache time specifiedcache_time nhỏ hơn 5Dùng 5–3600 giây

Còn trong widget, code của request bị từ chối có thể là: NOT_ALLOWED (không có allow_queries, không có lần chạm, đang ở chế độ preview hoặc là bản chuyển tiếp của widget tĩnh), BUSY (mỗi lúc chỉ một request), RATE_LIMITED (quá 5 request mỗi 5 giây), TIMEOUT, FAILED và INVALID_ANSWER. Dữ liệu rỗng hoặc dài hơn 64 byte sẽ ném TypeError trước khi gửi.

Checklist trước khi gửi widget cho người dùng

  1. Kích thước sau nén dưới 4096 byte (check_widget.py).
  2. Widget vẫn vẽ được nội dung hữu ích khi trạng thái là null và khi không có TelegramWidget.
  3. Màu lấy từ biến --tg-theme-*; đã thử cả theme sáng và tối.
  4. Tin nhắn có caption, vì thông báo và ứng dụng cũ hiển thị caption.
  5. Bot trả lời mọi widget_query trong 15 giây, và allowed_updates có widget_query lẫn shared_widget_query.
  6. Tần suất sửa được giới hạn ở phía bạn, và "message is not modified" không bị coi là lỗi.

Mọi thuộc tính, sự kiện và giới hạn dùng ở đây đều có trong tài liệu TelegramWidget JavaScript API; tài liệu chính thức nằm tại core.telegram.org/bots/widgets. Chưa có bot? Xem cách tạo bot Telegram.

Câu hỏi thường gặp

Gửi HTML cho phương thức sendWidget thế nào?

Truyền nguyên tài liệu vào tham số chuỗi html. Hãy gửi request dạng JSON, ví dụ requests.post(url, json={"chat_id": 123456789, "html": html}) trong Python, để dấu nháy và xuống dòng trong HTML được mã hóa đúng.

Vì sao widget báo TIMEOUT sau khi chạm?

Bot không gọi answerWidgetQuery trong vòng 15 giây. Thường là bot không chạy, hoặc bot truyền allowed_updates mà thiếu widget_query (và shared_widget_query) nên không bao giờ nhận được query.

Xử lý lỗi "message is not modified" từ editMessageWidgetData ra sao?

Coi như thành công: widget đã có đúng trạng thái đó. Lỗi xảy ra khi chat_data hoặc public_data mới giống hệt giá trị hiện tại. Vẫn phải trả lời widget query đã gây ra lần sửa này.

Làm bình chọn trực tiếp bằng widget dùng chung thế nào?

Gửi widget một lần với is_shared và allow_queries, lưu widget.id, gửi sang chat khác bằng sendSharedWidget, đếm phiếu theo cặp (widget_id, from.id) và ghi tổng bằng editSharedWidgetData tối đa một lần mỗi giây. Widget phải gọi watchPublicData().

Xem thử widget trên trình duyệt bằng cách nào?

Ngoài Telegram, window.TelegramWidget là undefined, nên hãy đặt một đối tượng giả lập nhỏ và các biến theme phía trên code widget trong một file preview riêng. Trình duyệt không áp dụng widget profile hay giới hạn, nên hãy thử trong Telegram trước khi gửi cho người dùng.

Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên

Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.

API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript

Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.

Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ

Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.

Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n

Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.

Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic

Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.

Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram

Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.

Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ

Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.

TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn

Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.

Widget Telegram: HTML tương tác ngay trong tin nhắn của bot

Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.