API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan
API widget Telegram adalah objek window.TelegramWidget yang diberikan aplikasi Telegram ke setiap widget Bot API 10.4, ditambah sisi Bot API: update widget_query dan method answerWidgetQuery. Referensi ini memuat semua properti, method, event, dan kode error TelegramWidget, variabel CSS, aturan gestur, serta batasannya, berdasarkan dokumentasi resmi widget Telegram.
Ketersediaan: di lingkungan produksi, widget saat ini hanya berfungsi di chat pribadi dengan bot dan tidak bisa diteruskan (dikirim dengan konten terlindungi). Grup, mode inline, dan forward hanya berfungsi di server tes, jadi properti sepertiisForwardatauchatType: "group"baru relevan di sana.
Baru mengenal widget? Mulai dari apa itu widget Telegram dan contoh widget Telegram.
Bagaimana objek TelegramWidget tersedia
Widget tidak butuh tag script. Di dalam Telegram, window.TelegramWidget sudah ada sebelum script pertama widget berjalan. Di luar Telegram (browser biasa) nilainya undefined. Method yang ditambahkan dalam sebuah profil dideteksi dengan typeof:
const W = window.TelegramWidget; // undefined di browser biasa
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// gambar dari state; null berarti "belum ada state"
}
if (W) W.onEvent('chatDataChanged', render);
render();
Properti TelegramWidget
| Properti | Tipe | Keterangan |
|---|---|---|
profile | Integer | Profil widget yang diterapkan aplikasi: 1 di versi ini |
colorScheme | String | light atau dark, skema warna chat (juga --tg-color-scheme) |
themeParams | Object | Palet bubble sebagai string #rrggbb, dengan key yang sama seperti themeParams di Mini App |
isActive | Boolean | Widget sedang terlihat (!document.hidden) |
isPreview | Boolean | Hasil inline yang ditampilkan sebelum dikirim: tanpa ketukan, tanpa request |
isForward | Boolean | Salinan hasil forward |
chatType | String | private, group, supergroup, channel, atau null di forward atau preview |
viewer | Object | id, first_name, last_name, username, is_premium pengguna yang melihat; hanya jika widget boleh mengirim request, selain itu null |
publicData | String | State bersama, maksimal 1024 byte, atau null. Read-only |
chatData | String | State chat, maksimal 1024 byte, atau null; selalu null di forward. Read-only |
contentSafeAreaInset | Object | top, right, bottom, left, cornerLeft, cornerRight: area yang tertutup waktu pesan |
wallet | Object | Wallet Telegram, atau null (aplikasi tanpa wallet, request tidak diizinkan, preview) |
HapticFeedback | Object | Umpan balik haptic, lihat di bawah |
Method TelegramWidget
| Method | Fungsi |
|---|---|
request(data[, options]) | Mengirim 1–64 byte ke bot. Mengembalikan Promise berisi { result } (jawaban bot atau null) atau gagal dengan WidgetRequestError. Hanya di handler ketukan, atau di background jika diizinkan. options bisa berupa { wallet: true } |
watchPublicData() / unwatchPublicData() | Mulai / hentikan polling live state bersama widget shared selama tampil di layar. Tidak berpengaruh pada widget statis atau preview |
copyText(text) | Menyalin 1–256 karakter saat diketuk; aplikasi menampilkan toast berisi teks itu |
openLink(url) | Membuka URL https: (≤ 256 karakter, bukan host t.me) setelah pengguna mengonfirmasi |
openTelegramLink(url) | Membuka link https://t.me/… di dalam Telegram, seperti link yang diketuk di pesan |
setResizeAnchor(edge) | top (default) atau bottom: tepi bubble yang tetap di tempat saat tinggi berubah |
ready() | Opsional: memberi tahu aplikasi bahwa state pertama sudah digambar |
onEvent(type, handler) / offEvent(type, handler) | Menambah / menghapus handler event (maksimal 16 per jenis event) |
isProfileAtLeast(n) | Mengembalikan profile >= n |
Semua method bersifat sinkron kecuali isProfileAtLeast, request, dan method wallet. HapticFeedback punya impactOccurred(style) (light, medium, heavy, rigid, soft), notificationOccurred(type) (error, success, warning), dan selectionChanged(). Tidak ada sendMessage, dan widget tidak diberi tahu widget_id-nya.
Event
| Event | Kapan terjadi |
|---|---|
themeChanged | Tema chat berubah; colorScheme, themeParams, dan variabel CSS sudah diperbarui |
activated / deactivated | Widget menjadi terlihat / tersembunyi (setelah visibilitychange) |
chatDataChanged | Bot mengubah state chat; chatData sudah berisi nilai baru. Tidak pernah terjadi di forward |
publicDataChanged | Bot mengubah state bersama; untuk widget shared yang tampil di layar hanya selama di-watch. Terjadi setelah chatDataChanged jika keduanya berubah |
contentSafeAreaChanged | Area yang tertutup waktu pesan berubah (caption ditambah, dihapus, atau dipindah, tanda "diedit") |
Handler dipanggil dengan this terikat ke TelegramWidget dan tanpa argumen, jadi baca nilai baru langsung dari objek.
Kode WidgetRequestError
button.addEventListener('click', () => {
status.textContent = 'Mengirim…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? 'Selesai'; },
(error) => { status.textContent = 'Error: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | Arti |
|---|---|
NOT_ALLOWED | Tanpa allow_queries, forward widget statis, bukan dari ketukan saat request background tidak diizinkan, preview, atau aplikasi yang tidak meneruskan request |
BUSY | Request atau panggilan wallet lain dari widget ini masih berjalan |
RATE_LIMITED | Panggilan background dalam 5 detik sejak yang terakhir, atau lebih dari 5 request per 5 detik per pengguna dan bot |
TIMEOUT | Bot tidak menjawab dalam 15 detik (mati, lambat, atau tidak menerima widget_query / shared_widget_query) |
FAILED | Penyebab lain: bot diblokir atau dihapus, pesan sudah tidak ada, jaringan gagal |
INVALID_ANSWER | Jawaban bot melanggar batasan |
REJECTED, BAD_REQUEST | Khusus panggilan wallet: pengguna menolak, atau wallet menolak transaksi atau payload |
Data kosong atau lebih dari 64 byte melempar TypeError sebelum apa pun dikirim.
Sisi bot: widget_query dan answerWidgetQuery
Request dari pesan asli masuk sebagai widget_query di Update; request dari forward widget shared masuk sebagai shared_widget_query. Jika kamu mengisi allowed_updates di getUpdates atau setWebhook, sertakan keduanya (lihat juga panduan webhook telegram bot).
{
"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 dari pesan yang dikirim via bot berisi inline_message_id dan chat_type sebagai ganti chat dan message_id; widget_id ada untuk widget shared. shared_widget_query hanya berisi id, from, type, data, dan widget_id. Jawab setiap query dengan answerWidgetQuery (widget_query_id, opsional data maksimal 1024 byte); ubah state secara terpisah dengan editMessageWidgetData atau editSharedWidgetData. from dan widget_id diisi Telegram dan tidak bisa dipalsukan, tapi perlakukan data sebagai input yang tidak tepercaya.
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}"}'
Variabel CSS
| Variabel | Arti |
|---|---|
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color | Latar bubble, teks, teks sekunder, link |
--tg-theme-button-color, --tg-theme-button-text-color | Tombol utama aplikasi |
--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 | Permukaan kedua, aksen, subjudul, aksi destruktif, pemisah |
--tg-color-scheme | light atau dark |
--tg-text-font-size, --tg-text-line-height, --tg-text-padding | Ukuran teks pesan (sekitar 15px), tinggi baris (sekitar 1.35), inset teks bubble (sekitar 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 | Gaya tombol aplikasi yang dipakai <button> default |
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -right | Area tempat waktu pesan digambar (sama dengan env(safe-area-inset-*)) |
Aplikasi memasang variabel ini di elemen root dengan !important; kamu hanya bisa mendefinisikan ulang di elemen milikmu sendiri. prefers-color-scheme, light-dark(), dan color-scheme mengikuti tema chat, bukan sistem.
Gestur dan touch-action
Ketukan dan ketukan ganda selalu milik widget; geser vertikal selalu menggulir chat (widget menerima pointercancel). Tekan lama dan geser horizontal diklaim per elemen lewat CSS touch-action: auto menyerahkannya ke chat (menu pesan, swipe-to-reply), pan-y memberikan geser horizontal ke widget, none memberikan tekan lama (contextmenu) dan geser horizontal ke widget. Patokan praktis: touch-action: none untuk tombol tekan lama, kontrol game, atau canvas, pan-y untuk slider atau carousel horizontal, dan auto untuk sisanya. Gunakan pointer event; touch event tidak dikirim. Jauhkan kontrol dari 20 px pertama di sisi awal, karena area itu tidak pernah bisa diklaim.
Yang dihapus oleh profil widget
- Kontrol form (
input,select,textarea);<button>adalah satu-satunya kontrol. Tidak ada event keyboard maupun fokus. - Semua API jaringan (
fetch,XMLHttpRequest,WebSocket, dan lainnya melemparNetworkDisabledError), script, style, font, dan gambar eksternal,location, danhistory. vhdan unit relatif tinggi lainnya,overflow: auto / scroll(menjadihidden),position: sticky,@font-face,:has(), CSS nesting.alert,confirm,prompt,navigator.clipboard(pakaicopyText),iframe,video,audio, WebGL.
Fitur yang dihapus tidak pernah merusak widget: elemen, deklarasi, atau event tersebut dibuang dan sisanya tetap berjalan. CSS.supports() dan @supports menjawab sesuai profil.
Batasan widget Telegram
| Batasan | Nilai | Jika dilampaui |
|---|---|---|
| HTML | 32768 byte; 4096 byte setelah zlib level 9 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | Masing-masing 1024 byte UTF-8 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| Data request | 1–64 byte | TypeError di widget |
| Data jawaban | 1024 byte | WIDGET_RESULT_TOO_LARGE |
| Waktu menjawab | 15 detik | TIMEOUT; jawaban terlambat: query is too old |
| Request | 5 per 5 detik per pengguna dan bot | RATE_LIMITED |
| Edit widget shared | 1 per detik; periode refresh default 30 detik, cache_time 5–3600 | Flood wait; invalid cache time specified di bawah 5 |
| CPU | 300 ms JavaScript per detik; 500 ms dalam satu task | Diperlambat; widget dihentikan |
| Memori | 8 MB | Widget dihentikan |
| Node DOM | 2000 | Widget dihentikan |
| Timer | 64 timer aktif | RangeError |
localStorage, sessionStorage | 4 KB per area per pesan | QuotaExceededError |
| Bubble | Lebar 200 px sampai lebar maksimum bubble, tinggi 50–600 px | Terpotong |
Widget yang dihentikan mempertahankan frame terakhirnya dengan badge "Widget stopped" dan dibangun ulang saat tampil lagi; setelah dua kali crash berturut-turut, widget tetap berhenti sampai aplikasi di-restart.
Storage, link, haptic, dan copyText
- Web Storage melekat pada pesan ini di perangkat ini. Data tetap ada setelah aplikasi di-restart, tidak pernah dikirim ke bot, dan tidak disinkronkan antarperangkat. Bungkus
setItemdengantry/catch. - Link:
openLink,openTelegramLink,copyText, danrequestbutuh ketukan sungguhan: panggil secara sinkron di handlerclick, bukan setelahawaitatau di timer. Satu ketukan membuka satu panggilan seperti itu. URL tidak valid melemparTypeError;<a href="https://…">yang diketuk juga berfungsi. - Haptic hanya diputar saat widget terlihat, maksimal 5 berturut-turut dan 10 per detik; bebas batas selama sentuhan dan 5 detik sesudahnya. Aplikasi desktop dan web tidak memutar apa pun.
- copyText menyalin 1–256 karakter dan selalu menampilkan toast berisi teks yang disalin.
Ringkasan pembayaran dengan wallet TON
Widget bisa meminta pengguna membayar lewat wallet bawaan Telegram, dengan format TON Connect. Tampilkan tombol bayar hanya jika TelegramWidget.wallet bukan null. Saat diketuk, widget mengirim request(data, { wallet: true }); query yang diterima bot lalu punya type {"type": "data", "wallet_card": …}, dan bot menjawab dengan transaksi baru. Di handler jawaban, widget memanggil wallet.sendTransaction(), yang tidak butuh ketukan kedua dalam 10 detik:
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));
Setelah itu bot menerima query bertipe sent_transaction berisi hash pesan dan wajib memverifikasi transaksi di blockchain. Setelah TIMEOUT, pembayaran mungkin saja sudah masuk, jadi tanyakan status pesanan ke bot alih-alih membayar lagi.
Error Bot API untuk widget
| Error | Penyebab |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML lebih dari 32768 byte atau 4096 byte terkompresi |
INPUT_MEDIA_WIDGET_HTML_INVALID | UTF-8 tidak valid atau ada karakter NUL di html |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data atau public_data lebih dari 1024 byte |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | Teks state tidak valid saat mengirim / saat mengedit |
message is not modified | Edit yang tidak mengubah apa pun; anggap sebagai sukses |
Coba method-method ini dengan token milikmu di Bot API Tester, dan lihat parameter sendWidget. Daftar lengkap method Bot API 10.4 ada di referensi method; jika belum punya token, baca cara mendapatkan token bot Telegram.
Pertanyaan umum
Apakah perlu memasang script untuk memakai TelegramWidget?
Tidak. Di dalam Telegram, window.TelegramWidget sudah ada sebelum script pertama widget berjalan, lengkap dengan state, tema, dan konteks. Di luar Telegram nilainya undefined, jadi periksa dulu saat membuka widget di browser.
Apa arti WidgetRequestError NOT_ALLOWED?
Pesan ini tidak boleh mengirim request: widget dikirim tanpa allow_queries, merupakan forward widget statis atau preview, atau request() dipanggil di luar ketukan saat request background tidak diizinkan.
Seberapa cepat bot harus menjawab widget_query?
Dalam 15 detik, dengan answerWidgetQuery. Setelah itu promise di widget gagal dengan TIMEOUT, dan jawaban yang terlambat ditolak dengan query is too old. Jawab setiap query, bahkan saat terjadi kegagalan.
Bisakah widget mengubah chatData atau publicData sendiri?
Tidak. Keduanya read-only di widget. Hanya bot yang menulis state, lewat sendWidget, editMessageWidgetData, atau editSharedWidgetData; widget hanya bisa meminta ke bot dengan TelegramWidget.request().
Apakah ada method TelegramWidget.sendMessage?
Tidak ada. sendMessage tidak tersedia di widget: tidak ada yang pernah dikirim ke chat atas nama pengguna. Widget hanya bisa mengirim request ke botnya, menyalin teks, membuka link, dan memainkan haptic.
Panduan terkait
Cara Membuat Bot Telegram: dari BotFather sampai Pesan Pertama
Cara membuat bot telegram langkah demi langkah: daftar di @BotFather, simpan token, cek dengan getMe, lalu kirim pesan pertama lewat curl dan Python.
Kirim Pesan Bot Telegram dengan Telegram Bot API (sendMessage)
Kirim pesan bot telegram lewat Bot API: contoh sendMessage dengan curl, Python, dan JavaScript, format HTML/MarkdownV2, tombol inline, dan solusi error.
Telegram Bot Token: Cara Mendapatkan, Mengecek, dan Mencabut Token
Cara mendapatkan token bot telegram dari @BotFather, melihat token bot lama, mengecek dengan getMe, dan me-revoke token yang bocor. Lengkap dengan contoh.
Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error
Panduan webhook telegram bot: syarat HTTPS dan port, setWebhook dengan secret_token, cek getWebhookInfo, deleteWebhook, serta solusi error 409 dan n8n.
Chat ID Telegram Dimana? Cara Mendapatkan Chat ID User, Grup, dan Channel
Chat id telegram dimana? Cara mendapatkan chat id user, grup, supergroup, dan channel lewat getUpdates, plus solusi saat result kosong atau error 409.
Server Test Telegram: Cara Test Bot di Lingkungan Test Telegram
Cara memakai server test Telegram untuk bot: login ke lingkungan test, buat bot test, panggil Bot API lewat /test/, lalu aktifkan TEST di tester kami.
Widget Telegram untuk Website: Login dengan Telegram, Embed Post, Komentar, dan Tombol Share
Pasang widget telegram untuk website: login dengan Telegram (OIDC), Login Widget lama dengan cek hash, embed post, komentar channel, dan tombol share.
Contoh Widget Telegram: Kode HTML dan Bot Python Lengkap
Contoh widget telegram lengkap dengan kode: kartu pesanan statis, counter dengan request widget_query, polling live sebagai widget shared, preview lokal.
Widget Telegram: HTML Interaktif di Dalam Pesan Bot
Widget telegram (Bot API 10.4): apa itu, cara kerja sendWidget, chat_data dan public_data, di mana bisa dipakai saat ini, dan bedanya dengan Mini App.