Widget Telegram: HTML Interaktif di Dalam Pesan Bot
Widget telegram adalah blok HTML interaktif kecil yang dikirim bot di dalam pesan lewat method sendWidget, fitur baru Bot API 10.4 yang rilis 9 November 2026. Widget berupa satu dokumen HTML maksimal 32 KB yang dijalankan aplikasi Telegram di perangkat pengguna tanpa akses jaringan, dan tampil mengikuti gaya chat: kartu pesanan yang statusnya ikut berubah, penghitung, polling dengan bar yang bergerak saat orang memilih, atau kode promo yang tersalin dengan satu ketukan.
Di mana widget berfungsi saat ini: di lingkungan produksi, bot hanya bisa mengirim widget ke chat pribadi dengan pengguna, dan pesannya dikirim dengan konten terlindungi (protected content) sehingga tidak bisa diteruskan. Widget di grup, mode inline, dan forward untuk sementara hanya berfungsi di server tes.
Apa itu widget Telegram
- Satu dokumen HTML.
<style>dan<script>ditulis inline, gambar hanya berupa URLdata:atau SVG inline. Maksimal 32768 byte UTF-8 dan maksimal 4096 byte setelah kompresi zlib level 9. Potongan HTML tanpa<html>dan<body>juga boleh. - Berjalan di sandbox. JavaScript dijalankan di QuickJS, engine JavaScript kecil, bukan di WebView. Aplikasi memeriksa setiap perubahan yang dibuat widget terhadap profil widget dan hanya menggambar yang lolos, sehingga tampilannya sama di iOS, Android, macOS, Telegram Desktop, dan web.
- Offline.
fetch,XMLHttpRequest,WebSocket, dan API jaringan lain melemparNetworkDisabledError. Script, style, font, dan gambar eksternal tidak pernah dimuat, dan tidak ada library bawaan. - Terasa native. Palet warna chat tersedia sebagai variabel CSS
--tg-theme-*, dan<button>tanpa style digambar sebagai tombol bawaan aplikasi. - Tanpa keyboard. Input, select, dan textarea dihapus. Widget merespons ketukan, pointer event, geser horizontal, dan tekan lama.
Kode dan state: chat_data dan public_data
Widget terdiri dari kode yang tetap plus state yang bisa berubah. HTML ditentukan saat widget dikirim dan tidak pernah berubah: tidak ada method untuk menggantinya. Yang berubah adalah state, dan hanya bot yang bisa menulisnya. Widget membacanya sebagai TelegramWidget.chatData dan TelegramWidget.publicData, lalu menggambar ulang saat event chatDataChanged dan publicDataChanged.
| Aspek | State chat (chat_data) | State bersama (public_data) |
|---|---|---|
| Terikat ke | Satu pesan asli | Pesan widget statis, atau widget shared di mana pun ia tampil |
| Terlihat | Hanya di chat itu (satu untuk semua anggota di grup) | Di mana pun widget tampil |
| Di pesan forward | Tidak pernah | Salinan (widget statis) atau state bersama yang live (widget shared) |
| Ukuran | Maksimal 1024 byte teks | Maksimal 1024 byte teks |
| Diubah dengan | editMessageWidgetData | editMessageWidgetData atau editSharedWidgetData |
| Contoh | Game yang sedang berjalan, status pesanan | Hasil polling, harga |
Keduanya berupa teks biasa yang tidak ditafsirkan server, biasanya JSON. Di dalam widget, state yang kosong atau sudah dihapus bernilai null.
Di mana widget bisa tampil: produksi vs server tes
| Tempat | Cara sampai ke sana | Request (dengan allow_queries) | Produksi |
|---|---|---|---|
| Chat pribadi dengan bot | sendWidget, sendSharedWidget | Saat diketuk dan di background | Ya |
| Grup biasa atau supergroup | sendWidget | Hanya saat diketuk | Hanya server tes |
| Chat apa pun kecuali channel, via bot | Mode inline (InputWidgetMessageContent, InputSharedWidgetMessageContent) | Hanya saat diketuk | Hanya server tes |
| Pesan forward, termasuk di channel | Diteruskan oleh pengguna | Saat diketuk, hanya widget shared | Hanya server tes |
Bot tidak bisa memposting widget di channel. Aplikasi yang belum mendukung widget menampilkan pesan sebagai media yang tidak didukung beserta caption-nya. Pesan widget tidak bisa disalin dengan copyMessage atau copyMessages, dan di grup izin can_send_other_messages juga berlaku untuk widget.
Widget Telegram vs Mini App
| Aspek | Mini App | Widget |
|---|---|---|
| Lokasi | WebView yang dibuka dari tombol, menu, atau link | Di dalam bubble pesan, selalu terlihat di chat |
| Kode | Halaman web di server kamu | HTML maksimal 32 KB di dalam pesan, dikunci saat dikirim |
| Engine | WebView platform | Sandbox QuickJS, digambar oleh aplikasi Telegram |
| Jaringan | Internet | Tidak ada |
| Komunikasi dengan bot | Backend kamu, dengan initData bertanda tangan | TelegramWidget.request() → update widget_query |
| Input | Semuanya, termasuk keyboard | Ketukan dan pointer event, tanpa keyboard |
Di bagian yang mirip, TelegramWidget memakai nama yang sama dengan Telegram.WebApp (themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready). Untuk fitur yang terlalu besar bagi widget, buka bot atau Mini App kamu dengan openTelegramLink. Kalau kamu justru sedang membuat Mini App, coba Mini App Tester.
Kirim widget pertama dengan sendWidget
- Buat bot dan salin tokennya (cara membuat bot Telegram, cara mendapatkan token bot).
- Kirim
/startke bot agar bot bisa mengirim pesan ke kamu, lalu ambil chat id darigetUpdates. - Panggil sendWidget. Parameter
htmlberupa string, jadi kirim request sebagai JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>Kode promo kamu</h3><p>Ketuk tombol untuk menyalinnya.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "Kode promo kamu: PROMO10"
}'
Versi Python dengan requests atau JavaScript dengan fetch:
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Kode promo kamu</h3>
<p>Ketuk tombol untuk menyalinnya.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "Kode promo kamu: PROMO10",
}, timeout=10)
print(r.json()) # result: Message yang terkirim, dengan field "widget"const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Kode promo kamu</h3>
<p>Ketuk tombol untuk menyalinnya.</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: "Kode promo kamu: PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: Message yang terkirim, dengan field "widget"Widget ini sama sekali tanpa CSS, tapi tetap terlihat seperti pesan biasa dengan tombol native. TelegramWidget sudah tersedia tanpa tag script, dan copyText berfungsi karena dipanggil di handler ketukan. Kamu juga bisa menempelkan HTML ini ke form sendWidget di Bot API Tester dan mengirimnya dengan token milikmu.
Parameter sendWidget lainnya: width dan height (anchor ukuran dalam piksel logis), chat_data dan public_data (state awal), allow_queries, is_shared, serta parameter umum seperti caption, reply_markup, reply_parameters, message_thread_id, dan protect_content.
Cara widget berkomunikasi dengan bot
Request bekerja seperti tombol callback di dalam widget:
- Bot mengirim widget dengan
allow_queries: true. - Saat diketuk, widget memanggil
TelegramWidget.request("like")dengan data 1–64 byte. - Bot menerima update
widget_queryberisiid,from,chat,message_id, dandata(dari forward widget shared:shared_widget_query). Jika kamu memakaiallowed_updates, masukkan kedua jenis update ini. - Bot memanggil answerWidgetQuery dalam 15 detik, opsional dengan
datamaksimal 1024 byte yang hanya diterima widget yang bertanya. - Untuk mengubah tampilan bagi semua orang, bot memanggil editMessageWidgetData (atau
editSharedWidgetData); widget menerimachatDataChanged/publicDataChanged.
Jawaban itu sendiri tidak pernah mengubah state. Request dibatasi 5 per 5 detik per pengguna dan bot; query yang tidak dijawab berakhir sebagai TIMEOUT di widget. Kode lengkap yang siap jalan ada di contoh widget Telegram.
Widget statis dan widget shared
Tanpa is_shared, widget bersifat statis: kode dan state tinggal di pesan, dan forward mendapat salinan yang membeku. Dengan is_shared, pengiriman pertama membuat widget shared: satu objek dengan ID (widget.id di pesan yang dikembalikan) yang bisa ditampilkan oleh banyak pesan. Kirim lagi dengan sendSharedWidget, dan ubah state bersamanya untuk semua pesan sekaligus dengan editSharedWidgetData, maksimal sekali per detik. Widget yang sudah tampil di layar baru menerima state bersama yang baru setelah memanggil TelegramWidget.watchPublicData(); aplikasi lalu melakukan polling sesuai periode refresh widget (default 30 detik, 5–3600 lewat cache_time).
Ringkasan batasan widget Telegram
| Apa | Batas |
|---|---|
| HTML | 32768 byte; 4096 byte setelah zlib level 9 |
chat_data, public_data | Masing-masing 1024 byte |
| Data request / data jawaban | 1–64 byte / maksimal 1024 byte |
| Waktu menjawab query | 15 detik |
| Request | 5 per 5 detik per pengguna dan bot |
| Ukuran bubble | Lebar 200 px sampai lebar maksimum bubble, tinggi 50–600 px; sisanya terpotong |
| Edit widget shared | 1 per detik |
| Memori / node DOM | 8 MB / 2000 node |
Tabel lengkap, termasuk kuota CPU, timer, dan storage, ada di referensi API TelegramWidget.
Tips desain
- Selalu kirim caption. Caption inilah yang tampil di daftar chat, notifikasi, pencarian, dan aplikasi yang belum mendukung widget.
- Pakai tema. Bangun warna dari variabel
--tg-theme-*dan uji di tema chat terang maupun gelap;prefers-color-schememengikuti tema chat, bukan sistem. - Gambar state pertama langsung dari
chatData/publicData; tidak ada yang perlu dimuat. - Jaga ukurannya kecil. Hitung ukuran terkompresi seperti cara server menghitung:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - Jangan simpan rahasia. Anggap kode dan state bersama sebagai data publik; di grup, semua anggota melihat state chat.
- Atur layout berdasarkan lebar dengan
%, flex, atau grid.vhtidak didukung dan tidak ada yang bisa di-scroll di dalam widget. - Tampilkan setiap hasil request: "Mengirim…", jawaban bot, dan setiap kode error.
Jangan tertukar dengan widget untuk website
Istilah "widget Telegram" juga dipakai untuk widget website yang lebih lama: Telegram Login Widget, embed postingan, dan tombol share. Itu adalah script yang kamu pasang di situs sendiri. Widget Bot API 10.4 adalah hal yang berbeda: HTML yang dikirim bot ke dalam chat. Dokumentasi resmi widget bot ada di core.telegram.org/bots/widgets. Cara memasang widget untuk situs dibahas di panduan widget Telegram untuk website.
Langkah selanjutnya
- Contoh widget Telegram: kartu pesanan, penghitung dengan request, dan polling live sebagai widget shared, lengkap dengan kode bot Python.
- API JavaScript TelegramWidget: properti, method, event, kode error, variabel CSS, dan batasan.
- Referensi method Bot API: semua parameter
sendWidget,answerWidgetQuery, dan method lain di Bot API 10.4.
Pertanyaan umum
Apa itu widget Telegram?
Blok interaktif kecil yang digambar di dalam pesan bot, diperkenalkan di Bot API 10.4 (9 November 2026). Widget adalah satu dokumen HTML mandiri dengan CSS dan JavaScript inline yang dijalankan aplikasi Telegram di perangkat pengguna, di dalam sandbox tanpa akses jaringan.
Apakah widget Telegram bisa dipakai di grup?
Belum di produksi. Saat ini bot hanya bisa mengirim widget di chat pribadi dengan pengguna, dan widget tidak bisa diteruskan. Grup, mode inline, dan forward baru berfungsi di server tes.
Bagaimana cara mengirim widget dari bot?
Panggil sendWidget dengan chat_id dan html (string 1–32768 byte, maksimal 4096 byte setelah kompresi zlib level 9), ditambah opsional caption, chat_data, public_data, dan allow_queries. Hasilnya adalah Message yang terkirim, lengkap dengan field widget.
Apakah widget Telegram bisa melakukan request HTTP?
Tidak. fetch, XMLHttpRequest, WebSocket, dan API jaringan lain melempar NetworkDisabledError. Satu-satunya jalur keluar adalah TelegramWidget.request(), yang mengirim 1–64 byte ke bot sebagai update widget_query.
Apa beda widget dan Mini App?
Mini App adalah halaman web yang kamu host sendiri, dibuka di WebView dari tombol atau link, dengan akses jaringan penuh. Widget hidup di dalam bubble pesan, berupa HTML maksimal 32 KB yang dikunci saat dikirim, tanpa jaringan, dan hanya bisa berkomunikasi dengan bot lewat request.
Bisakah HTML widget diubah setelah dikirim?
Tidak. Kode dikunci saat dikirim; yang bisa berubah hanya state. Perbarui chat_data atau public_data dengan editMessageWidgetData atau editSharedWidgetData, atau kirim widget baru untuk tampilan baru. Caption bisa diedit dengan editMessageCaption.
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.
API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan
Referensi API JavaScript TelegramWidget: properti, request(), event, kode error, variabel CSS, widget_query dan answerWidgetQuery, plus semua batasannya.
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.