Widget Telegram: HTML tương tác ngay trong tin nhắn của bot
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ì
- Một tài liệu HTML duy nhất.
<style>và<script>viết inline, ảnh chỉ dùngdata:URL hoặc SVG inline. Tối đa 32768 byte UTF-8 và 4096 byte sau khi nén zlib mức 9. Chỉ cần một đoạn HTML, không bắt buộc<html>và<body>. - Chạy trong sandbox. JavaScript chạy bằng QuickJS, một engine JavaScript nhỏ, không phải WebView. Ứng dụng kiểm tra mọi thay đổi của widget theo widget profile và chỉ vẽ phần hợp lệ, nên widget hiển thị giống nhau trên iOS, Android, macOS, Telegram Desktop và bản web.
- Không có mạng.
fetch,XMLHttpRequest,WebSocketvà các API mạng khác némNetworkDisabledError. Script, style, font và ảnh bên ngoài không bao giờ được tải, cũng không có thư viện nào đi kèm. - Giao diện native. Bảng màu của chat có sẵn dưới dạng biến CSS
--tg-theme-*, và một<button>không style sẽ được vẽ như nút của chính ứng dụng. - Không có bàn phím. Input, select và textarea bị loại bỏ. Widget phản hồi chạm, pointer event, kéo ngang và nhấn giữ.
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ới | Một tin nhắn gốc | Tin nhắn của widget tĩnh, hoặc widget dùng chung ở mọi nơi nó hiển thị |
| Ai thấy | Chỉ 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ếp | Khô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ước | Tối đa 1024 byte văn bản | Tối đa 1024 byte văn bản |
| Đổi bằng | editMessageWidgetData | editMessageWidgetData hoặc editSharedWidgetData |
| Ví dụ | Ván game đang chơi, trạng thái đơn hàng | Kế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ơi | Cách đến đó | Request (khi có allow_queries) | Production |
|---|---|---|---|
| Chat riêng với bot | sendWidget, sendSharedWidget | Khi chạm và chạy nền | Có |
| Group thường hoặc supergroup | sendWidget | Chỉ khi chạm | Chỉ test server |
| Mọi chat trừ channel, gửi qua bot | Inline mode (InputWidgetMessageContent, InputSharedWidgetMessageContent) | Chỉ khi chạm | Chỉ test server |
| Tin chuyển tiếp, kể cả trong channel | Người dùng chuyển tiếp | Khi chạm, chỉ widget dùng chung | Chỉ 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 App | Widget |
|---|---|---|
| Ở đâu | WebView mở từ nút, menu hoặc link | Trong bong bóng tin nhắn, luôn hiện trong chat |
| Code | Trang web trên server của bạn | Tối đa 32 KB HTML nằm trong tin nhắn, cố định sau khi gửi |
| Engine | WebView của nền tảng | Sandbox QuickJS, do ứng dụng Telegram vẽ |
| Mạng | Toàn bộ web | Không có |
| Liên lạc với bot | Qua backend của bạn, với initData có chữ ký | TelegramWidget.request() → update widget_query |
| Nhập liệu | Mọi thứ, kể cả bàn phím | Chạ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
- Tạo bot và sao chép token (cách tạo bot Telegram, cách lấy token bot Telegram).
- Gửi
/startcho bot để bot được phép nhắn cho bạn, rồi lấy chat id từgetUpdates. - Gọi sendWidget. Tham số
htmllà 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:
- Bot gửi widget với
allow_queries: true. - Khi người dùng chạm, widget gọi
TelegramWidget.request("like")với 1–64 byte dữ liệu. - Bot nhận update
widget_querygồmid,from,chat,message_idvàdata(từ tin chuyển tiếp của widget dùng chung:shared_widget_query). Nếu bạn truyềnallowed_updates, nhớ thêm cả hai loại. - Bot gọi answerWidgetQuery trong vòng 15 giây, có thể kèm
datatối đa 1024 byte mà chỉ widget đã hỏi nhận được. - Để đổi thứ mà mọi người cùng thấy, bot gọi editMessageWidgetData (hoặc
editSharedWidgetData); widget nhậnchatDataChanged/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ục | Giới hạn |
|---|---|
| HTML | 32768 byte; 4096 byte sau khi nén zlib mức 9 |
chat_data, public_data | Mỗi loại 1024 byte |
| Dữ liệu request / dữ liệu trả lời | 1–64 byte / tối đa 1024 byte |
| Thời gian trả lời query | 15 giây |
| Request | 5 mỗi 5 giây cho mỗi người dùng và bot |
| Kích thước bong bóng | Rộ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 chung | 1 lần mỗi giây |
| Bộ nhớ / số node DOM | 8 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ế
- Luôn gửi caption. Đó là thứ hiện trong danh sách chat, thông báo, tìm kiếm và trên ứng dụng chưa hỗ trợ widget.
- Dùng màu theme. Dựng màu trên biến
--tg-theme-*và thử cả theme sáng lẫn tối;prefers-color-schemetheo theme của chat chứ không theo hệ thống. - Vẽ trạng thái đầu tiên ngay từ
chatData/publicData; không có gì phải tải. - Giữ kích thước nhỏ. Đo kích thước nén giống server:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - Không để bí mật. Coi code và trạng thái công khai là public; trong group mọi thành viên đều thấy trạng thái chat.
- Bố cục theo chiều rộng bằng
%, flex hoặc grid.vhkhông được hỗ trợ và bên trong widget không có cuộn. - Hiển thị mọi kết quả của request: "Đang gửi…", câu trả lời và từng mã lỗi.
Đừ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
- Ví dụ widget Telegram: thẻ đơn hàng, bộ đếm có request và bình chọn trực tiếp dùng chung, kèm code bot Python.
- TelegramWidget JavaScript API: thuộc tính, phương thức, sự kiện, mã lỗi, biến CSS và giới hạn.
- Danh sách phương thức Bot API: tham số của
sendWidget,answerWidgetQueryvà các phương thức mới khác.
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.
Bài viết liên quan
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ử.