Cara Tes Telegram Mini App: Dari Mock di Browser sampai Telegram Asli
Untuk tes Telegram Mini App, mulailah di browser biasa dengan Telegram.WebApp versi mock, lalu sajikan build lokal lewat HTTPS, daftarkan URL-nya di @BotFather, dan buka di dalam Telegram dengan DevTools terpasang. Langkah terakhir ada di server: validasi initData sebelum memercayai data pengguna. Berikut alur lengkapnya, dari localhost sampai checklist produksi.
Langkah 1: tes UI di browser biasa
Di luar Telegram, tidak ada klien di balik Telegram.WebApp: tidak ada data peluncuran, tema, maupun tombol native. Sebagian besar antarmuka tetap bisa dibangun di browser desktop, asalkan kode kamu tahan terhadap kondisi itu:
const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);
if (insideTelegram) {
tg.ready(); // sembunyikan placeholder loading secepat mungkin
tg.expand();
} else {
console.info("Di luar Telegram: memakai data mock");
}
Pakai variabel tema dengan nilai cadangan, misalnya var(--tg-theme-bg-color, #fff), agar halaman tetap terbaca di kedua lingkungan.
Untuk melihat efek setiap panggilan API tanpa menulis kode, buka Mini App Tester. Di browser biasa, tool ini berjalan dalam mode mock dan mengemulasi Telegram.WebApp: tekan MainButton dan BackButton, buka popup, tulis ke CloudStorage, ganti tema, dan pantau 45+ event di log. Tapi data mock hanya pengganti: initData-nya tidak ditandatangani Telegram dan (memang seharusnya) gagal divalidasi di server.
Langkah 2: jalankan Telegram Mini App dari localhost lewat HTTPS
Telegram hanya membuka Mini App dari URL HTTPS (pengecualiannya test environment), dan ponsel kamu juga tidak bisa menjangkau http://localhost. Cara standar untuk tes Telegram Mini App di localhost adalah tunnel yang memberi dev server alamat HTTPS publik:
# jalankan dev server, misalnya Vite di port 5173
npm run dev
# di terminal kedua, pakai salah satu tunnel
ngrok http 5173
cloudflared tunnel --url http://localhost:5173
Setiap tool akan menampilkan URL https:// publik. Dua kendala yang sering muncul:
- Vite menolak host tunnel. Versi Vite terbaru memblokir host yang tidak dikenal di dev server; tambahkan domain tunnel ke
server.allowedHostsdivite.config.js. - Alamatnya berubah. Banyak tunnel memberi URL acak baru setiap restart. Kalau begitu, perbarui URL di @BotFather atau ulangi panggilan
setChatMenuButtondari Langkah 3.
Langkah 3: daftarkan Mini App di @BotFather
Mini App selalu terikat pada sebuah bot. Kalau belum punya, ikuti panduan cara membuat bot Telegram. Lalu tentukan cara pengguna membuka URL kamu:
- Direct link: kirim
/newappke @BotFather, pilih bot, dan ikuti instruksinya. Aplikasi lalu terbuka dihttps://t.me/<bot_username>/<app_name>. - Tombol menu: di @BotFather pakai
/setmenubuttonatau Bot Settings → Menu Button, atau panggil metodesetChatMenuButton. - Tombol keyboard: tombol
web_appdi reply keyboard atau inline keyboard (hanya di chat pribadi).
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button": {"type": "web_app", "text": "Buka aplikasi",
"web_app": {"url": "https://your-tunnel.example.com"}}}'
Tanpa chat_id, panggilan ini mengatur tombol menu default untuk semua pengguna. Setiap kali URL tunnel berubah, ulangi panggilannya di setChatMenuButton di Bot API Tester daripada mengetik ulang curl.
Langkah 4: pakai test environment Telegram
Telegram punya test environment terpisah, tempat link Mini App boleh memakai HTTP biasa tanpa TLS. Ini praktis untuk tes di jaringan lokal. Test environment butuh akun dan bot tersendiri:
- iOS: ketuk ikon Settings 10 kali → Accounts → Login to another account → Test.
- Telegram Desktop: ☰ Settings → Shift+Alt+klik kanan "Add Account" → Test Server.
- macOS: klik ikon Settings 10 kali untuk membuka Debug Menu, lalu ⌘+klik "Add Account".
Buat bot dengan @BotFather di akun tes, lalu kirim request API ke https://api.telegram.org/bot<token>/test/METHOD_NAME. Flood limit di sana tidak dinaikkan dan bisa lebih ketat, jadi jangan dipakai untuk load test. Setup lengkap, termasuk switch TEST di Bot API Tester kami, ada di panduan cara memakai server tes Telegram.
Langkah 5: debug Mini App di dalam Telegram
Banyak bug yang tidak pernah muncul di Chrome baru terlihat di WebView asli. Ringkasan instruksi resmi Debug Mode for Mini Apps:
| Platform | Cara inspeksi |
|---|---|
| iOS | Ketuk ikon Settings 10 kali dan aktifkan Allow Web View Inspection; sambungkan lewat USB dan buka Develop → perangkat kamu di Safari pada Mac. |
| Android | Aktifkan USB debugging; di Settings Telegram gulir ke paling bawah, tekan lama nomor versi dua kali, pilih Enable WebView Debug; buka chrome://inspect/#devices di Chrome. |
| Telegram Desktop (Windows, Linux) | Pasang versi beta; Settings → Advanced → Experimental settings → Enable webview inspection; klik kanan → Inspect. |
| Telegram for macOS | Pasang versi beta; klik ikon Settings 5 kali dan aktifkan Debug Mini Apps; klik kanan → Inspect Element. |
Untuk membandingkan klien dengan cepat, pasang https://telegram-bot-api.info/telegram-mini-app-tester.html sebagai URL Mini App di bot tes. Di dalam Telegram, Mini App Tester memakai API asli dan menampilkan version, platform, colorScheme, themeParams, safe area, serta setiap event yang dipicu klien tersebut. Di kode kamu sendiri, batasi fitur baru dengan Telegram.WebApp.isVersionAtLeast("8.0"), jangan berasumsi semua orang memakai aplikasi versi terbaru.
Langkah 6: validasi initData di server
Telegram.WebApp.initDataUnsafe hanya untuk tampilan. Kirim string mentah Telegram.WebApp.initData ke backend dan verifikasi:
- Parse query string dan buang
hash. - Urutkan field yang tersisa secara alfabetis dan gabungkan sebagai baris
key=valueyang dipisahkan\n: inilahdata_check_string. - Hitung
secret_key = HMAC_SHA256(key="WebAppData", message=bot_token). - Data asli jika
hex(HMAC_SHA256(key=secret_key, message=data_check_string))sama denganhash. - Tolak data kedaluwarsa dengan mengecek
auth_date.
import crypto from "node:crypto";
export function validateInitData(initData, botToken, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get("hash") ?? "";
params.delete("hash");
const dataCheckString = [...params.keys()].sort()
.map((key) => `${key}=${params.get(key)}`)
.join("\n");
const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const valid = hash.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
const age = Date.now() / 1000 - Number(params.get("auth_date"));
if (!valid || !(age <= maxAgeSec)) return null;
return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}
Di klien, kirim string itu apa adanya, misalnya fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }), dan validasi dengan token bot yang meluncurkan aplikasi. Pihak ketiga yang tidak boleh tahu token kamu bisa memverifikasi field signature dengan public key Ed25519 milik Telegram, seperti dijelaskan di dokumentasi resmi.
Bot API 10.2: proteksi origin Mini App
Bot API 10.2 melarang pemanggilan metode Mini App dari origin selain domain asli Mini App, dan proteksi ini diaktifkan untuk semua Mini App pada 20 Juli 2026. Saat testing, masalah ini muncul ketika aplikasi melakukan redirect dari URL tunnel yang terdaftar ke host lain, misalnya domain staging atau halaman login: panggilan Telegram.WebApp berhenti berfungsi di sana. Simpan kode yang berkomunikasi dengan Telegram di domain terdaftar, dan daftarkan ulang URL setiap kali host tunnel berubah. Proteksi bisa dimatikan di Mini App @BotFather, tapi setelah itu kamu sendiri yang harus memastikan Mini App tidak berisi link ke situs yang tidak tepercaya.
Checklist testing Telegram Mini App
- UI berfungsi di mode mock serta di tema terang dan gelap.
Telegram.WebApp.ready()dipanggil begitu UI utama selesai dirender.- URL di @BotFather atau
setChatMenuButtoncocok dengan tunnel atau domain produksi saat ini. - Sudah dites di iOS, Android, dan desktop dengan DevTools; fitur baru dibatasi dengan
isVersionAtLeast(). - Layout fullscreen memperhatikan
safeAreaInsetdancontentSafeAreaInset. - Backend memvalidasi
initData(hash danauth_date) dan tidak pernah memercayaiinitDataUnsafe. - Semua panggilan
Telegram.WebAppberjalan di origin yang terdaftar. - Produksi berjalan di domain sendiri dengan sertifikat valid, bukan di tunnel sementara.
Kode validasi bergantung pada token bot, jadi rahasiakan token tersebut: baca cara mendapatkan dan melindungi token bot. Jika backend yang sama juga menerima update bot, lanjutkan ke cara setting webhook bot Telegram. Kalau yang kamu butuhkan hanya blok interaktif kecil di dalam pesan chat, bukan aplikasi web penuh, lihat widget Telegram yang hadir di Bot API 10.4.
Pertanyaan umum
Bagaimana cara tes Telegram Mini App di localhost?
Telegram hanya membuka Mini App dari URL HTTPS, jadi buka dev server lewat tunnel HTTPS (misalnya ngrok atau Cloudflare Tunnel) lalu daftarkan URL itu di @BotFather atau dengan setChatMenuButton. Di test environment, link HTTP biasa diperbolehkan.
Apakah Telegram Mini App bisa dites tanpa Telegram?
Sebagian. Browser biasa tidak punya klien Telegram, jadi kamu butuh mock Telegram.WebApp, misalnya mode mock di Mini App Tester. initData asli, popup native, dan haptik hanya berfungsi di dalam Telegram.
Bagaimana cara membuka DevTools untuk Telegram Mini App?
Di iOS, aktifkan Allow Web View Inspection (ketuk Settings 10 kali) lalu pakai menu Develop di Safari. Di Android, aktifkan WebView Debug di pengaturan debug Telegram dan buka chrome://inspect/#devices. Di desktop dan macOS, pakai opsi inspeksi webview di versi beta.
Kenapa validasi initData saya gagal?
Penyebab umum: memvalidasi initDataUnsafe, bukan string mentah initData; memakai token bot lain; tidak men-decode nilai URL; hash masih ikut di data-check string; key dan message HMAC tertukar; atau tes dengan data mock yang tidak pernah ditandatangani Telegram.
Kenapa metode Telegram.WebApp berhenti berfungsi di domain lain?
Sejak Bot API 10.2, metode Mini App diblokir jika dipanggil dari origin yang berbeda dengan domain Mini App; proteksi ini aktif untuk semua Mini App sejak 20 Juli 2026. Jalankan aplikasi di domain yang terdaftar atau matikan proteksi di @BotFather.
Apakah ada server tes khusus untuk Telegram Mini App?
Ada. Test environment terpisah dari produksi: kamu perlu akun dan bot baru di sana, request Bot API dikirim ke https://api.telegram.org/bot<token>/test/METHOD_NAME, dan link Mini App boleh memakai HTTP tanpa TLS.
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.
Cara Deploy Bot Telegram: Hosting di VPS, Docker, dan Serverless
Cara deploy bot Telegram: polling vs webhook, service systemd di VPS, Docker, Cloudflare Workers dengan secret_token, plus checklist sebelum bot online.
Telegram Bot API 10.0–10.5: Pengaturan Bot, Widget, Rich Message, Ephemeral Message, Guest Mode, dan Lainnya
Fitur baru Telegram Bot API 10.0–10.5: setMySettings dan BotFullInfo, widget HTML, rich message, ephemeral message, guest mode, lengkap dengan contoh JSON.
Error Telegram Bot API: Arti Setiap Error dan Cara Mengatasinya
Daftar error Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Penyebab, solusi, dan kode penanganan.
Limit Telegram Bot API: Rate Limit, Error 429, Ukuran File, dan Panjang Pesan
Limit Telegram Bot API: 30 pesan/detik, 1 pesan/detik per chat, 20/menit di grup, cara menangani 429 retry_after, batas ukuran file dan panjang pesan.
Perintah Bot Telegram: setMyCommands, Scope Perintah, dan Deep Link /start
Cara membuat perintah bot Telegram: /setcommands di @BotFather, setMyCommands dengan scope dan bahasa, parameter deep link /start, dan /cmd@bot di grup.
Keyboard Bot Telegram: Inline Keyboard, Tombol Callback, dan Reply Keyboard
Cara membuat tombol bot Telegram: inline keyboard dengan callback_data, answerCallbackQuery, edit pesan setelah tombol ditekan, reply keyboard, ForceReply.
Integrasi n8n Telegram: Hubungkan Bot, Jalankan Workflow, dan Kirim Pesan
Cara menghubungkan n8n ke Telegram: token bot sebagai Access Token, webhook Telegram Trigger via HTTPS publik, kirim pesan via chat id, dan solusi error.
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.
Bot Inline Telegram: Cara Mengaktifkan Mode Inline dan Menjawab Inline Query
Cara membuat bot inline Telegram: aktifkan mode inline lewat @BotFather atau setMySettings, tangani update inline_query, lalu balas via answerInlineQuery.
Pembayaran Telegram Stars untuk Bot: Invoice, Pre-Checkout, Refund, dan Langganan
Cara menerima pembayaran Telegram Stars di bot: sendInvoice dengan XTR, pre_checkout_query, successful_payment, refund, langganan, plus kode Python/JS.
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.
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.