Telegram Bot API

Widget Telegram: HTML Interaktif di Dalam Pesan Bot

· 8 menit baca

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

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.

AspekState chat (chat_data)State bersama (public_data)
Terikat keSatu pesan asliPesan widget statis, atau widget shared di mana pun ia tampil
TerlihatHanya di chat itu (satu untuk semua anggota di grup)Di mana pun widget tampil
Di pesan forwardTidak pernahSalinan (widget statis) atau state bersama yang live (widget shared)
UkuranMaksimal 1024 byte teksMaksimal 1024 byte teks
Diubah denganeditMessageWidgetDataeditMessageWidgetData atau editSharedWidgetData
ContohGame yang sedang berjalan, status pesananHasil 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

TempatCara sampai ke sanaRequest (dengan allow_queries)Produksi
Chat pribadi dengan botsendWidget, sendSharedWidgetSaat diketuk dan di backgroundYa
Grup biasa atau supergroupsendWidgetHanya saat diketukHanya server tes
Chat apa pun kecuali channel, via botMode inline (InputWidgetMessageContent, InputSharedWidgetMessageContent)Hanya saat diketukHanya server tes
Pesan forward, termasuk di channelDiteruskan oleh penggunaSaat diketuk, hanya widget sharedHanya 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

AspekMini AppWidget
LokasiWebView yang dibuka dari tombol, menu, atau linkDi dalam bubble pesan, selalu terlihat di chat
KodeHalaman web di server kamuHTML maksimal 32 KB di dalam pesan, dikunci saat dikirim
EngineWebView platformSandbox QuickJS, digambar oleh aplikasi Telegram
JaringanInternetTidak ada
Komunikasi dengan botBackend kamu, dengan initData bertanda tanganTelegramWidget.request() → update widget_query
InputSemuanya, termasuk keyboardKetukan 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

  1. Buat bot dan salin tokennya (cara membuat bot Telegram, cara mendapatkan token bot).
  2. Kirim /start ke bot agar bot bisa mengirim pesan ke kamu, lalu ambil chat id dari getUpdates.
  3. Panggil sendWidget. Parameter html berupa 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:

  1. Bot mengirim widget dengan allow_queries: true.
  2. Saat diketuk, widget memanggil TelegramWidget.request("like") dengan data 1–64 byte.
  3. Bot menerima update widget_query berisi id, from, chat, message_id, dan data (dari forward widget shared: shared_widget_query). Jika kamu memakai allowed_updates, masukkan kedua jenis update ini.
  4. Bot memanggil answerWidgetQuery dalam 15 detik, opsional dengan data maksimal 1024 byte yang hanya diterima widget yang bertanya.
  5. Untuk mengubah tampilan bagi semua orang, bot memanggil editMessageWidgetData (atau editSharedWidgetData); widget menerima chatDataChanged / 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

ApaBatas
HTML32768 byte; 4096 byte setelah zlib level 9
chat_data, public_dataMasing-masing 1024 byte
Data request / data jawaban1–64 byte / maksimal 1024 byte
Waktu menjawab query15 detik
Request5 per 5 detik per pengguna dan bot
Ukuran bubbleLebar 200 px sampai lebar maksimum bubble, tinggi 50–600 px; sisanya terpotong
Edit widget shared1 per detik
Memori / node DOM8 MB / 2000 node

Tabel lengkap, termasuk kuota CPU, timer, dan storage, ada di referensi API TelegramWidget.

Tips desain

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

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.

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.