Telegram Bot API

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

· 10 phút đọc

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ư isForward hay chatType: "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ínhKiểuMô tả
profileIntegerWidget profile mà ứng dụng áp dụng: 1 ở phiên bản này
colorSchemeStringlight hoặc dark, theo chat (cũng có trong --tg-color-scheme)
themeParamsObjectBảng màu của bong bóng dạng chuỗi #rrggbb, cùng khóa với themeParams của Mini App
isActiveBooleanWidget đang hiển thị (!document.hidden)
isPreviewBooleanKết quả inline hiện trước khi gửi: không chạm, không request
isForwardBooleanBản chuyển tiếp
chatTypeStringprivate, group, supergroup, channel, hoặc null trong bản chuyển tiếp hay preview
viewerObjectid, 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
publicDataStringTrạng thái công khai, tối đa 1024 byte, hoặc null. Chỉ đọc
chatDataStringTrạ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
contentSafeAreaInsetObjecttop, right, bottom, left, cornerLeft, cornerRight: vùng bị giờ gửi tin nhắn che
walletObjectVí của Telegram, hoặc null (ứng dụng không có ví, không được gửi request, bản preview)
HapticFeedbackObjectRung phản hồi, xem bên dưới

Phương thức của TelegramWidget

Phương thứcChứ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ệnKhi nào
themeChangedTheme của chat đổi; colorScheme, themeParams và biến CSS đã được cập nhật
activated / deactivatedWidget hiện ra / bị ẩn (sau visibilitychange)
chatDataChangedBot đổi trạng thái chat; chatData đã là giá trị mới. Không bao giờ có trong bản chuyển tiếp
publicDataChangedBot đổ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
contentSafeAreaChangedVù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_ALLOWEDKhô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
BUSYMột request hoặc lệnh gọi ví khác của widget đang chạy
RATE_LIMITEDLệ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
TIMEOUTBot 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)
FAILEDMọ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_ANSWERCâu trả lời của bot vượt giới hạn
REJECTED, BAD_REQUESTChỉ 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-colorNền bong bóng, chữ, chữ phụ, link
--tg-theme-button-color, --tg-theme-button-text-colorNú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-colorNền phụ, màu nhấn, phụ đề, hành động nguy hiểm, đường phân cách
--tg-color-schemelight hoặc dark
--tg-text-font-size, --tg-text-line-height, --tg-text-paddingCỡ 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-opacityKiể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 / -rightDả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ỏ

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ạnGiá trịKhi vượt quá
HTML32768 byte; 4096 byte sau khi nén zlib mức 9INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data, public_dataMỗi loại 1024 byte UTF-8INPUT_MEDIA_WIDGET_DATA_TOO_LARGE
Dữ liệu request1–64 byteTypeError trong widget
Dữ liệu trả lời1024 byteWIDGET_RESULT_TOO_LARGE
Thời gian trả lời15 giâyTIMEOUT; trả lời muộn: query is too old
Request5 mỗi 5 giây cho mỗi người dùng và botRATE_LIMITED
Sửa widget dùng chung1 lần mỗi giây; chu kỳ làm mới mặc định 30 giây, cache_time 5–3600Flood wait; invalid cache time specified nếu dưới 5
CPU300 ms JavaScript mỗi giây; 500 ms cho một taskBị hãm tốc; widget bị dừng
Bộ nhớ8 MBWidget bị dừng
Node DOM2000Widget bị dừng
Timer64 timer đang chạyRangeError
localStorage, sessionStorage4 KB mỗi vùng cho mỗi tin nhắnQuotaExceededError
Bong bóngRộng từ 200 px đến mức tối đa của bong bóng, cao 50–600 pxBị 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.

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ỗiNguyên nhân
INPUT_MEDIA_WIDGET_TOO_LARGEHTML quá 32768 byte hoặc quá 4096 byte sau nén
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 không hợp lệ hoặc có ký tự NUL trong html
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data hoặc public_data quá 1024 byte
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALIDVăn bản trạng thái không hợp lệ khi gửi / khi sửa
message is not modifiedLầ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.

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.