Telegram Bot API

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

· 8 phút đọc

Widget Telegram là những khối HTML tương tác nhỏ mà bot gửi kèm tin nhắn bằng phương thức sendWidget, ra mắt trong Bot API 10.4 ngày 9/11/2026. Mỗi widget là một tài liệu HTML tối đa 32 KB, được ứng dụng Telegram chạy ngay trên thiết bị người dùng, không có mạng, và vẽ theo đúng giao diện của chat: thẻ đơn hàng tự cập nhật trạng thái, bộ đếm, cuộc bình chọn có thanh kết quả nhảy theo phiếu, mã khuyến mãi sao chép bằng một chạm.

Widget hiện chạy ở đâu: trên môi trường production, bot chỉ gửi được widget vào chat riêng với người dùng, và tin nhắn được gửi với nội dung được bảo vệ (protected content) nên không chuyển tiếp được. Widget trong group, inline mode và tin chuyển tiếp hiện chỉ chạy trên test server.

Widget Telegram là gì

Code và trạng thái: chat_data và public_data

Widget = code cố định + trạng thái thay đổi được. HTML được đặt lúc gửi và không bao giờ đổi: không có phương thức nào thay thế nó. Thứ thay đổi là trạng thái, và chỉ bot được ghi. Widget đọc trạng thái qua TelegramWidget.chatData, TelegramWidget.publicData và vẽ lại khi có sự kiện chatDataChanged, publicDataChanged.

Tiêu chíTrạng thái chat (chat_data)Trạng thái công khai (public_data)
Gắn vớiMột tin nhắn gốcTin nhắn của widget tĩnh, hoặc widget dùng chung ở mọi nơi nó hiển thị
Ai thấyChỉ trong chat đó (trong group: một trạng thái chung cho mọi thành viên)Ở mọi nơi widget hiển thị
Trong tin chuyển tiếpKhông bao giờBản sao (widget tĩnh) hoặc trạng thái dùng chung trực tiếp (widget dùng chung)
Kích thướcTối đa 1024 byte văn bảnTối đa 1024 byte văn bản
Đổi bằngeditMessageWidgetDataeditMessageWidgetData hoặc editSharedWidgetData
Ví dụVán game đang chơi, trạng thái đơn hàngKết quả bình chọn, giá

Cả hai là văn bản thuần, server không phân tích, thường là JSON. Trong widget, trạng thái chưa có hoặc đã xóa có giá trị null.

Widget sống ở đâu: production và test server

NơiCách đến đóRequest (khi có allow_queries)Production
Chat riêng với botsendWidget, sendSharedWidgetKhi chạm và chạy nềnCó
Group thường hoặc supergroupsendWidgetChỉ khi chạmChỉ test server
Mọi chat trừ channel, gửi qua botInline mode (InputWidgetMessageContent, InputSharedWidgetMessageContent)Chỉ khi chạmChỉ test server
Tin chuyển tiếp, kể cả trong channelNgười dùng chuyển tiếpKhi chạm, chỉ widget dùng chungChỉ test server

Bot không đăng widget vào channel được. Ứng dụng chưa hỗ trợ widget sẽ hiện tin nhắn dưới dạng media không được hỗ trợ kèm caption. Tin nhắn widget không sao chép được bằng copyMessage hay copyMessages, và trong group quyền can_send_other_messages cũng áp dụng cho widget.

Widget Telegram và Mini App khác nhau thế nào

Tiêu chíMini AppWidget
Ở đâuWebView mở từ nút, menu hoặc linkTrong bong bóng tin nhắn, luôn hiện trong chat
CodeTrang web trên server của bạnTối đa 32 KB HTML nằm trong tin nhắn, cố định sau khi gửi
EngineWebView của nền tảngSandbox QuickJS, do ứng dụng Telegram vẽ
MạngToàn bộ webKhông có
Liên lạc với botQua backend của bạn, với initData có chữ kýTelegramWidget.request() → update widget_query
Nhập liệuMọi thứ, kể cả bàn phímChạm và pointer event, không bàn phím

Ở phần trùng nhau, TelegramWidget dùng lại tên của Telegram.WebApp (themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready). Việc gì lớn hơn một widget thì mở bot hoặc Mini App bằng openTelegramLink. Nếu bạn đang làm Mini App, có thể thử Telegram.WebApp API ngay trên trình duyệt bằng Mini App Tester.

Gửi widget đầu tiên bằng sendWidget

  1. Tạo bot và sao chép token (cách tạo bot Telegram, cách lấy token bot Telegram).
  2. Gửi /start cho bot để bot được phép nhắn cho bạn, rồi lấy chat id từ getUpdates.
  3. Gọi sendWidget. Tham số html là một chuỗi, nên hãy gửi request dạng JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "html": "<h3>Mã khuyến mãi của bạn</h3><p>Bấm nút để sao chép.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
    "caption": "Mã khuyến mãi của bạn: PROMO10"
  }'

Tương tự bằng Python với requests hoặc JavaScript với fetch:

import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Mã khuyến mãi của bạn</h3>
<p>Bấm nút để sao chép.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""

r = requests.post(f"{API}/sendWidget", json={
    "chat_id": 123456789,
    "html": html,
    "caption": "Mã khuyến mãi của bạn: PROMO10",
}, timeout=10)
print(r.json())  # result: Message đã gửi, có trường "widget"
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Mã khuyến mãi của bạn</h3>
<p>Bấm nút để sao ché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: "Mã khuyến mãi của bạn: PROMO10",
  }),
  signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: Message đã gửi, có trường "widget"

Widget này không có chút CSS nào mà vẫn trông như tin nhắn bình thường với nút native. TelegramWidget có sẵn mà không cần thẻ script, và copyText chạy được vì nó được gọi trong handler của một lần chạm. Bạn cũng có thể dán HTML vào form sendWidget trong Bot API Tester và gửi bằng token của mình.

Các tham số khác của sendWidget: width và height (kích thước neo, tính bằng pixel logic), chat_data và public_data (trạng thái ban đầu), allow_queries, is_shared, cùng các tham số quen thuộc như caption, reply_markup, reply_parameters, message_thread_id và protect_content.

Widget bot Telegram nói chuyện với bot thế nào

Request hoạt động giống một callback button nằm trong widget:

  1. Bot gửi widget với allow_queries: true.
  2. Khi người dùng chạm, widget gọi TelegramWidget.request("like") với 1–64 byte dữ liệu.
  3. Bot nhận update widget_query gồm id, from, chat, message_id và data (từ tin chuyển tiếp của widget dùng chung: shared_widget_query). Nếu bạn truyền allowed_updates, nhớ thêm cả hai loại.
  4. Bot gọi answerWidgetQuery trong vòng 15 giây, có thể kèm data tối đa 1024 byte mà chỉ widget đã hỏi nhận được.
  5. Để đổi thứ mà mọi người cùng thấy, bot gọi editMessageWidgetData (hoặc editSharedWidgetData); widget nhận chatDataChanged / publicDataChanged.

Bản thân câu trả lời không đổi trạng thái. Giới hạn là 5 request mỗi 5 giây cho mỗi cặp người dùng và bot; nếu bot không trả lời, widget nhận lỗi TIMEOUT. Code chạy được đầy đủ có trong bài ví dụ widget Telegram.

Widget tĩnh và widget dùng chung

Không có is_shared, widget là widget tĩnh: code và trạng thái nằm trong tin nhắn, bản chuyển tiếp chỉ là bản sao đứng yên. Có is_shared, lần gửi đầu tiên tạo ra một widget dùng chung: một đối tượng có định danh (widget.id trong tin nhắn trả về) mà bao nhiêu tin nhắn cũng có thể hiển thị. Gửi lại nó bằng sendSharedWidget và đổi trạng thái công khai cho tất cả cùng lúc bằng editSharedWidgetData, tối đa một lần mỗi giây. Widget đang hiện trên màn hình chỉ nhận trạng thái mới sau khi gọi TelegramWidget.watchPublicData(); khi đó ứng dụng hỏi lại theo chu kỳ làm mới của widget (mặc định 30 giây, đặt 5–3600 qua cache_time).

Giới hạn của widget Telegram

MụcGiới hạn
HTML32768 byte; 4096 byte sau khi nén zlib mức 9
chat_data, public_dataMỗi loại 1024 byte
Dữ liệu request / dữ liệu trả lời1–64 byte / tối đa 1024 byte
Thời gian trả lời query15 giây
Request5 mỗi 5 giây cho mỗi người dùng và bot
Kích thước bong bóngRộng từ 200 px đến mức tối đa của bong bóng, cao 50–600 px; phần thừa bị cắt
Sửa widget dùng chung1 lần mỗi giây
Bộ nhớ / số node DOM8 MB / 2000 node

Bảng đầy đủ, gồm quota CPU, timer và storage, có trong tài liệu TelegramWidget API.

Mẹo thiết kế

Đừng nhầm với widget cho website

"Telegram widget" còn dùng để chỉ các widget cho website có từ trước: Telegram Login Widget, nhúng bài đăng và nút chia sẻ. Đó là script bạn đặt trên trang web của mình. Widget của Bot API 10.4 là thứ khác hẳn: HTML do bot gửi vào chat. Cách gắn nút đăng nhập, nhúng bài đăng và nút chia sẻ lên site có trong bài widget Telegram cho website. Tài liệu chính thức về widget nằm tại core.telegram.org/bots/widgets.

Bước tiếp theo

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

Widget Telegram là gì?

Là khối tương tác nhỏ được vẽ ngay trong tin nhắn của bot, có từ Bot API 10.4 (9/11/2026). Mỗi widget là một tài liệu HTML độc lập với CSS và JavaScript inline, được ứng dụng Telegram chạy trên thiết bị người dùng trong sandbox, không có mạng.

Widget Telegram có chạy trong group không?

Trên production thì chưa. Hiện bot chỉ gửi được widget vào chat riêng với người dùng và tin nhắn không chuyển tiếp được. Group, inline mode và chuyển tiếp mới chạy trên test server.

Bot gửi widget bằng cách nào?

Gọi sendWidget với chat_id và html (chuỗi 1–32768 byte, tối đa 4096 byte sau khi nén zlib mức 9), kèm tùy chọn caption, chat_data, public_data và allow_queries. Phương thức trả về Message đã gửi có trường widget.

Widget có gọi HTTP request được không?

Không. fetch, XMLHttpRequest, WebSocket và mọi API mạng khác đều ném NetworkDisabledError. Cách duy nhất để liên lạc ra ngoài là TelegramWidget.request(), gửi 1–64 byte tới bot dưới dạng update widget_query.

Widget khác Mini App ở điểm nào?

Mini App là trang web bạn tự host, mở trong WebView từ nút hoặc link, có đầy đủ mạng. Widget nằm trong bong bóng tin nhắn, tối đa 32 KB HTML cố định từ lúc gửi, không có mạng và chỉ nói chuyện với bot qua request.

Có sửa được HTML của widget sau khi gửi không?

Không. Code cố định sau khi gửi, chỉ trạng thái thay đổi. Cập nhật chat_data hoặc public_data bằng editMessageWidgetData hay editSharedWidgetData, hoặc gửi widget mới nếu cần giao diện khác. Caption thì sửa được bằng editMessageCaption.

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.

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

Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.