Telegram Bot API

API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan

· 10 menit baca

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 seperti isForward atau chatType: "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

PropertiTipeKeterangan
profileIntegerProfil widget yang diterapkan aplikasi: 1 di versi ini
colorSchemeStringlight atau dark, skema warna chat (juga --tg-color-scheme)
themeParamsObjectPalet bubble sebagai string #rrggbb, dengan key yang sama seperti themeParams di Mini App
isActiveBooleanWidget sedang terlihat (!document.hidden)
isPreviewBooleanHasil inline yang ditampilkan sebelum dikirim: tanpa ketukan, tanpa request
isForwardBooleanSalinan hasil forward
chatTypeStringprivate, group, supergroup, channel, atau null di forward atau preview
viewerObjectid, first_name, last_name, username, is_premium pengguna yang melihat; hanya jika widget boleh mengirim request, selain itu null
publicDataStringState bersama, maksimal 1024 byte, atau null. Read-only
chatDataStringState chat, maksimal 1024 byte, atau null; selalu null di forward. Read-only
contentSafeAreaInsetObjecttop, right, bottom, left, cornerLeft, cornerRight: area yang tertutup waktu pesan
walletObjectWallet Telegram, atau null (aplikasi tanpa wallet, request tidak diizinkan, preview)
HapticFeedbackObjectUmpan balik haptic, lihat di bawah

Method TelegramWidget

MethodFungsi
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

EventKapan terjadi
themeChangedTema chat berubah; colorScheme, themeParams, dan variabel CSS sudah diperbarui
activated / deactivatedWidget menjadi terlihat / tersembunyi (setelah visibilitychange)
chatDataChangedBot mengubah state chat; chatData sudah berisi nilai baru. Tidak pernah terjadi di forward
publicDataChangedBot mengubah state bersama; untuk widget shared yang tampil di layar hanya selama di-watch. Terjadi setelah chatDataChanged jika keduanya berubah
contentSafeAreaChangedArea 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'
  );
});
codeArti
NOT_ALLOWEDTanpa allow_queries, forward widget statis, bukan dari ketukan saat request background tidak diizinkan, preview, atau aplikasi yang tidak meneruskan request
BUSYRequest atau panggilan wallet lain dari widget ini masih berjalan
RATE_LIMITEDPanggilan background dalam 5 detik sejak yang terakhir, atau lebih dari 5 request per 5 detik per pengguna dan bot
TIMEOUTBot tidak menjawab dalam 15 detik (mati, lambat, atau tidak menerima widget_query / shared_widget_query)
FAILEDPenyebab lain: bot diblokir atau dihapus, pesan sudah tidak ada, jaringan gagal
INVALID_ANSWERJawaban bot melanggar batasan
REJECTED, BAD_REQUESTKhusus 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

VariabelArti
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-colorLatar bubble, teks, teks sekunder, link
--tg-theme-button-color, --tg-theme-button-text-colorTombol 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-colorPermukaan kedua, aksen, subjudul, aksi destruktif, pemisah
--tg-color-schemelight atau dark
--tg-text-font-size, --tg-text-line-height, --tg-text-paddingUkuran 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-opacityGaya tombol aplikasi yang dipakai <button> default
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -rightArea 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

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

BatasanNilaiJika dilampaui
HTML32768 byte; 4096 byte setelah zlib level 9INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data, public_dataMasing-masing 1024 byte UTF-8INPUT_MEDIA_WIDGET_DATA_TOO_LARGE
Data request1–64 byteTypeError di widget
Data jawaban1024 byteWIDGET_RESULT_TOO_LARGE
Waktu menjawab15 detikTIMEOUT; jawaban terlambat: query is too old
Request5 per 5 detik per pengguna dan botRATE_LIMITED
Edit widget shared1 per detik; periode refresh default 30 detik, cache_time 5–3600Flood wait; invalid cache time specified di bawah 5
CPU300 ms JavaScript per detik; 500 ms dalam satu taskDiperlambat; widget dihentikan
Memori8 MBWidget dihentikan
Node DOM2000Widget dihentikan
Timer64 timer aktifRangeError
localStorage, sessionStorage4 KB per area per pesanQuotaExceededError
BubbleLebar 200 px sampai lebar maksimum bubble, tinggi 50–600 pxTerpotong

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.

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

ErrorPenyebab
INPUT_MEDIA_WIDGET_TOO_LARGEHTML lebih dari 32768 byte atau 4096 byte terkompresi
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 tidak valid atau ada karakter NUL di html
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data atau public_data lebih dari 1024 byte
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALIDTeks state tidak valid saat mengirim / saat mengedit
message is not modifiedEdit 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.

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.