TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn
Telegram widget API gồm đối tượng window.TelegramWidget mà mọi widget của Bot API 10.4 nhận từ ứng dụng Telegram, cùng phần phía Bot API: update widget_query và phương thức answerWidgetQuery. Bài tra cứu này liệt kê mọi thuộc tính, phương thức, sự kiện và mã lỗi của TelegramWidget, các biến CSS, quy tắc cử chỉ và giới hạn, dựa trên tài liệu widget chính thức của Telegram.
Phạm vi hiện tại: trên production, widget chỉ chạy trong chat riêng với bot và không chuyển tiếp được (được gửi với nội dung được bảo vệ). Group, inline mode và chuyển tiếp chỉ chạy trên test server, nên các thuộc tính nhưisForwardhaychatType: "group"trước mắt chỉ có ý nghĩa ở đó.
Mới làm quen với widget? Hãy bắt đầu từ widget Telegram là gì và các ví dụ widget.
Đối tượng TelegramWidget xuất hiện thế nào
Widget không cần thẻ script. Trong Telegram, window.TelegramWidget có sẵn trước khi script đầu tiên của widget chạy. Ngoài Telegram (trình duyệt thường) nó là undefined. Các phương thức được thêm trong một profile được kiểm tra bằng typeof:
const W = window.TelegramWidget; // undefined trong trình duyệt thường
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// vẽ từ state; null nghĩa là "chưa có trạng thái"
}
if (W) W.onEvent('chatDataChanged', render);
render();
Thuộc tính của TelegramWidget
| Thuộc tính | Kiểu | Mô tả |
|---|---|---|
profile | Integer | Widget profile mà ứng dụng áp dụng: 1 ở phiên bản này |
colorScheme | String | light hoặc dark, theo chat (cũng có trong --tg-color-scheme) |
themeParams | Object | Bảng màu của bong bóng dạng chuỗi #rrggbb, cùng khóa với themeParams của Mini App |
isActive | Boolean | Widget đang hiển thị (!document.hidden) |
isPreview | Boolean | Kết quả inline hiện trước khi gửi: không chạm, không request |
isForward | Boolean | Bản chuyển tiếp |
chatType | String | private, group, supergroup, channel, hoặc null trong bản chuyển tiếp hay preview |
viewer | Object | id, first_name, last_name, username, is_premium của người đang xem; chỉ có ở nơi widget được gửi request, còn lại là null |
publicData | String | Trạng thái công khai, tối đa 1024 byte, hoặc null. Chỉ đọc |
chatData | String | Trạng thái chat, tối đa 1024 byte, hoặc null; luôn là null trong bản chuyển tiếp. Chỉ đọc |
contentSafeAreaInset | Object | top, right, bottom, left, cornerLeft, cornerRight: vùng bị giờ gửi tin nhắn che |
wallet | Object | Ví của Telegram, hoặc null (ứng dụng không có ví, không được gửi request, bản preview) |
HapticFeedback | Object | Rung phản hồi, xem bên dưới |
Phương thức của TelegramWidget
| Phương thức | Chức năng |
|---|---|
request(data[, options]) | Gửi 1–64 byte tới bot. Trả về Promise của { result } (câu trả lời của bot hoặc null) hoặc reject với WidgetRequestError. Chỉ trong handler của lần chạm, hoặc chạy nền ở nơi được phép. options có thể là { wallet: true } |
watchPublicData() / unwatchPublicData() | Bắt đầu / dừng hỏi trực tiếp trạng thái công khai của widget dùng chung khi đang hiện trên màn hình. Không có tác dụng với widget tĩnh hoặc preview |
copyText(text) | Sao chép 1–256 ký tự khi chạm; ứng dụng hiện toast kèm văn bản |
openLink(url) | Mở URL https: (≤ 256 ký tự, không phải host t.me) sau khi người dùng xác nhận |
openTelegramLink(url) | Mở link https://t.me/… trong Telegram, như chạm vào link trong tin nhắn |
setResizeAnchor(edge) | top (mặc định) hoặc bottom: cạnh nào của bong bóng đứng yên khi chiều cao đổi |
ready() | Tùy chọn: báo cho ứng dụng biết trạng thái đầu tiên đã vẽ xong |
onEvent(type, handler) / offEvent(type, handler) | Thêm / gỡ handler sự kiện (tối đa 16 cho mỗi loại sự kiện) |
isProfileAtLeast(n) | Trả về profile >= n |
Mọi phương thức đều đồng bộ, trừ isProfileAtLeast, request và các phương thức ví. HapticFeedback có impactOccurred(style) (light, medium, heavy, rigid, soft), notificationOccurred(type) (error, success, warning) và selectionChanged(). Không có sendMessage, và widget không được biết widget_id của mình.
Sự kiện
| Sự kiện | Khi nào |
|---|---|
themeChanged | Theme của chat đổi; colorScheme, themeParams và biến CSS đã được cập nhật |
activated / deactivated | Widget hiện ra / bị ẩn (sau visibilitychange) |
chatDataChanged | Bot đổi trạng thái chat; chatData đã là giá trị mới. Không bao giờ có trong bản chuyển tiếp |
publicDataChanged | Bot đổi trạng thái công khai; với widget dùng chung đang hiện thì chỉ khi nó đang watch. Phát sau chatDataChanged nếu cả hai cùng đổi |
contentSafeAreaChanged | Vùng bị giờ gửi che đã đổi (thêm, bỏ hoặc dời caption, dấu "đã sửa") |
Handler được gọi với this trỏ tới TelegramWidget và không có tham số, nên hãy đọc giá trị mới từ đối tượng.
Mã lỗi WidgetRequestError
button.addEventListener('click', () => {
status.textContent = 'Đang gửi…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? 'Xong'; },
(error) => { status.textContent = 'Lỗi: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | Ý nghĩa |
|---|---|
NOT_ALLOWED | Không có allow_queries, bản chuyển tiếp của widget tĩnh, không có lần chạm ở nơi không cho chạy nền, bản preview, hoặc ứng dụng không chuyển request |
BUSY | Một request hoặc lệnh gọi ví khác của widget đang chạy |
RATE_LIMITED | Lệnh gọi nền trong vòng 5 giây kể từ lần trước, hoặc quá 5 request mỗi 5 giây cho mỗi người dùng và bot |
TIMEOUT | Bot không trả lời trong 15 giây (bot tắt, chậm, hoặc không nhận widget_query / shared_widget_query) |
FAILED | Mọi lỗi khác: bot bị chặn hoặc bị xóa, tin nhắn không còn, lỗi mạng |
INVALID_ANSWER | Câu trả lời của bot vượt giới hạn |
REJECTED, BAD_REQUEST | Chỉ với lệnh gọi ví: người dùng từ chối, hoặc ví từ chối giao dịch hay payload |
Dữ liệu rỗng hoặc quá 64 byte ném TypeError trước khi gửi.
Phía bot: widget_query và answerWidgetQuery
Request từ tin nhắn gốc đến dưới dạng widget_query trong Update; request từ bản chuyển tiếp của widget dùng chung là shared_widget_query. Nếu bạn truyền allowed_updates cho getUpdates hoặc setWebhook, hãy thêm cả hai.
{
"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 từ tin nhắn gửi qua bot có inline_message_id và chat_type thay cho chat và message_id; với widget dùng chung có thêm widget_id. shared_widget_query chỉ có id, from, type, data và widget_id. Trả lời mọi query bằng answerWidgetQuery (widget_query_id, data tùy chọn tối đa 1024 byte); đổi trạng thái riêng bằng editMessageWidgetData hoặc editSharedWidgetData. from và widget_id do Telegram điền nên không giả mạo được, nhưng hãy coi data là đầu vào không tin cậy.
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}"}'
Biến CSS
| Biến | Ý nghĩa |
|---|---|
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color | Nền bong bóng, chữ, chữ phụ, link |
--tg-theme-button-color, --tg-theme-button-text-color | Nút chính của ứng dụng |
--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 | Nền phụ, màu nhấn, phụ đề, hành động nguy hiểm, đường phân cách |
--tg-color-scheme | light hoặc dark |
--tg-text-font-size, --tg-text-line-height, --tg-text-padding | Cỡ chữ tin nhắn (khoảng 15px), giãn dòng (khoảng 1.35), lề chữ trong bong bóng (khoảng 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 | Kiểu nút của ứng dụng, dùng cho <button> mặc định |
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -right | Dải hiển thị giờ gửi tin nhắn (giống env(safe-area-inset-*)) |
Ứng dụng đặt các biến này trên phần tử gốc với !important; bạn chỉ định nghĩa lại được trên phần tử của mình. prefers-color-scheme, light-dark() và color-scheme theo theme của chat, không theo hệ thống.
Cử chỉ và touch-action
Chạm và chạm đúp luôn thuộc về widget; kéo dọc luôn cuộn chat (widget nhận pointercancel). Nhấn giữ và kéo ngang được giành theo từng phần tử bằng CSS touch-action: auto nhường cho chat (menu tin nhắn, vuốt để trả lời), pan-y giao kéo ngang cho widget, none giao cả nhấn giữ (contextmenu) lẫn kéo ngang. Quy tắc nhanh: touch-action: none cho nút nhấn giữ, điều khiển game hoặc canvas, pan-y cho slider ngang hoặc carousel, auto cho mọi chỗ khác. Dùng pointer event; touch event không được gửi tới widget. Đặt điều khiển tránh 20 px ở mép đầu, vùng này không bao giờ giành được cử chỉ.
Những gì widget profile loại bỏ
- Control của form (
input,select,textarea);<button>là control duy nhất. Không có sự kiện bàn phím hay focus. - Mọi API mạng (
fetch,XMLHttpRequest,WebSocketvà các API khác némNetworkDisabledError), script, style, font và ảnh bên ngoài,locationvàhistory. vhvà các đơn vị theo chiều cao khác,overflow: auto / scroll(thànhhidden),position: sticky,@font-face,:has(), CSS nesting.alert,confirm,prompt,navigator.clipboard(dùngcopyText),iframe,video,audio, WebGL.
Tính năng bị loại không làm hỏng widget: phần tử, khai báo hoặc sự kiện đó bị bỏ qua, phần còn lại vẫn chạy. CSS.supports() và @supports trả lời theo profile.
Giới hạn của widget Telegram
| Giới hạn | Giá trị | Khi vượt quá |
|---|---|---|
| HTML | 32768 byte; 4096 byte sau khi nén zlib mức 9 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | Mỗi loại 1024 byte UTF-8 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| Dữ liệu request | 1–64 byte | TypeError trong widget |
| Dữ liệu trả lời | 1024 byte | WIDGET_RESULT_TOO_LARGE |
| Thời gian trả lời | 15 giây | TIMEOUT; trả lời muộn: query is too old |
| Request | 5 mỗi 5 giây cho mỗi người dùng và bot | RATE_LIMITED |
| Sửa widget dùng chung | 1 lần mỗi giây; chu kỳ làm mới mặc định 30 giây, cache_time 5–3600 | Flood wait; invalid cache time specified nếu dưới 5 |
| CPU | 300 ms JavaScript mỗi giây; 500 ms cho một task | Bị hãm tốc; widget bị dừng |
| Bộ nhớ | 8 MB | Widget bị dừng |
| Node DOM | 2000 | Widget bị dừng |
| Timer | 64 timer đang chạy | RangeError |
localStorage, sessionStorage | 4 KB mỗi vùng cho mỗi tin nhắn | QuotaExceededError |
| Bong bóng | Rộng từ 200 px đến mức tối đa của bong bóng, cao 50–600 px | Bị cắt |
Widget bị dừng giữ lại khung hình cuối với nhãn "Widget stopped" và được dựng lại khi hiện ra lần nữa; nếu crash hai lần liên tiếp, nó dừng hẳn cho tới khi ứng dụng khởi động lại.
Storage, link, rung phản hồi và copyText
- Web Storage thuộc về tin nhắn này trên thiết bị này. Nó còn sau khi khởi động lại ứng dụng, không bao giờ gửi về bot và không đồng bộ giữa các thiết bị. Bọc
setItemtrongtry/catch. - Link:
openLink,openTelegramLink,copyTextvàrequestcần một lần chạm thật: gọi đồng bộ trong handlerclick, không phải sauawaithay timer. Một lần chạm mở khóa một lệnh gọi như vậy. URL không hợp lệ némTypeError; chạm vào<a href="https://…">cũng hoạt động. - Rung phản hồi chỉ phát khi widget đang hiển thị, tối đa 5 lần liên tiếp và 10 lần mỗi giây; không bị tính giới hạn trong lúc chạm và 5 giây sau đó. Ứng dụng desktop và web không phát rung.
- copyText sao chép 1–256 ký tự và luôn hiện toast kèm văn bản đã sao chép.
Thanh toán qua ví TON (tóm tắt)
Widget có thể yêu cầu người dùng thanh toán qua ví tích hợp của Telegram, dùng định dạng TON Connect. Chỉ vẽ nút thanh toán khi TelegramWidget.wallet khác null. Khi chạm, widget gửi request(data, { wallet: true }); query của bot khi đó có type là {"type": "data", "wallet_card": …}, và bot trả lời bằng một giao dịch mới. Trong handler của câu trả lời, widget gọi wallet.sendTransaction(), không cần chạm lần hai nếu trong vòng 10 giây:
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));
Sau đó bot nhận query loại sent_transaction kèm hash của message và phải tự xác minh giao dịch trên chain. Sau TIMEOUT khoản thanh toán có thể đã thành công, nên hãy hỏi bot về trạng thái đơn hàng thay vì thanh toán lại.
Lỗi Bot API liên quan đến widget
| Lỗi | Nguyên nhân |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML quá 32768 byte hoặc quá 4096 byte sau nén |
INPUT_MEDIA_WIDGET_HTML_INVALID | UTF-8 không hợp lệ hoặc có ký tự NUL trong html |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data hoặc public_data quá 1024 byte |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | Văn bản trạng thái không hợp lệ khi gửi / khi sửa |
message is not modified | Lần sửa không thay đổi gì; coi là thành công |
Thử các phương thức bằng token của bạn trong Bot API Tester, và xem tham số của sendWidget. Chưa có token? Xem cách lấy token bot Telegram; toàn bộ phương thức Bot API có trong danh sách phương thức.
Câu hỏi thường gặp
Có cần nhúng script để dùng TelegramWidget không?
Không. Trong Telegram, window.TelegramWidget đã có sẵn trước khi script đầu tiên của widget chạy, kèm trạng thái, theme và ngữ cảnh. Ngoài Telegram nó là undefined, nên hãy kiểm tra khi mở widget trên trình duyệt.
WidgetRequestError NOT_ALLOWED nghĩa là gì?
Tin nhắn không được phép gửi request: widget được gửi không có allow_queries, là bản chuyển tiếp của widget tĩnh hoặc bản preview, hoặc request() được gọi ngoài lần chạm ở nơi không cho request chạy nền.
Bot phải trả lời widget_query trong bao lâu?
Trong 15 giây, bằng answerWidgetQuery. Quá thời hạn, promise của widget bị reject với TIMEOUT và câu trả lời muộn bị từ chối với query is too old. Hãy trả lời mọi query, kể cả khi xử lý bị lỗi.
Widget có tự đổi chatData hoặc publicData được không?
Không. Cả hai đều chỉ đọc trong widget. Chỉ bot ghi trạng thái, bằng sendWidget, editMessageWidgetData hoặc editSharedWidgetData; widget chỉ có thể hỏi bot qua TelegramWidget.request().
Có phương thức TelegramWidget.sendMessage không?
Không. Widget không có sendMessage: không có gì được gửi vào chat thay mặt người dùng. Widget chỉ gửi request tới bot của nó, sao chép văn bản, mở link và phát rung phản hồi.
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ẻ.
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ử.
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.