Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a
Telegram Mini App testine normal bir tarayıcıda, taklit edilmiş (mock) bir Telegram.WebApp ile başlayın; ardından yerel derlemenizi HTTPS üzerinden yayınlayın, adresi @BotFather'a kaydedin ve uygulamayı DevTools bağlıyken Telegram içinde açın. Son adım sunucuda: kullanıcıya güvenmeden önce initData'yı doğrulayın. Aşağıda localhost'tan üretim kontrol listesine kadar tüm süreci bulacaksınız.
1. Adım: arayüzü normal tarayıcıda test edin
Telegram dışında Telegram.WebApp'in arkasında bir istemci yoktur: başlatma verisi, tema ya da yerel butonlar gelmez. Yine de kodunuz bu durumu tolere ediyorsa arayüzün büyük kısmını masaüstü tarayıcıda geliştirebilirsiniz:
const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);
if (insideTelegram) {
tg.ready(); // yükleme ekranını mümkün olduğunca erken gizleyin
tg.expand();
} else {
console.info("Telegram dışında: mock veriler kullanılıyor");
}
Sayfayı tema değişkenleri ve bir yedek değerle biçimlendirin, ör. var(--tg-theme-bg-color, #fff); böylece iki ortamda da okunaklı kalır.
Kod yazmadan her API çağrısının ne yaptığını görmek için Mini App Tester'ı açın. Normal tarayıcıda mock modda çalışır ve Telegram.WebApp'i taklit eder: MainButton ve BackButton'a basın, popup açın, CloudStorage'a yazın, temayı değiştirin ve günlükte 45'ten fazla olayı izleyin. Ancak mock veriler yalnızca bir yer tutucudur: initData'sı Telegram tarafından imzalanmadığı için sunucu tarafındaki doğrulamadan (doğru olarak) geçemez.
2. Adım: Telegram Mini App'i localhost'tan HTTPS ile çalıştırın
Telegram Mini App'leri yalnızca HTTPS adreslerinden açar (istisna test ortamıdır); zaten telefonunuz http://localhost adresine ulaşamaz. Telegram Mini App'i localhost'ta test etmenin standart yolu, geliştirme sunucunuza herkese açık bir HTTPS adresi veren bir tüneldir:
# geliştirme sunucusunu başlatın, ör. 5173 portunda Vite
npm run dev
# ikinci bir terminalde tünellerden birini kullanın
ngrok http 5173
cloudflared tunnel --url http://localhost:5173
Her araç herkese açık bir https:// adresi yazdırır. Sık karşılaşılan iki takılma:
- Vite tünel host'unu reddediyor. Güncel Vite sürümleri geliştirme sunucusunda bilinmeyen host'ları engeller; tünel alan adını
vite.config.jsiçindekiserver.allowedHosts'a ekleyin. - Adres değişiyor. Birçok tünel her yeniden başlatmada yeni, rastgele bir URL verir. Bu olduğunda adresi @BotFather'da güncelleyin veya 3. adımdaki
setChatMenuButtonçağrısını tekrarlayın.
3. Adım: Mini App'i @BotFather'a kaydedin
Bir Mini App her zaman bir bota bağlıdır. Henüz botunuz yoksa Telegram bot yapma rehberini izleyin. Sonra kullanıcıların adresinizi nasıl açacağını seçin:
- Doğrudan link: @BotFather'a
/newappgönderin, botu seçin ve adımları izleyin. Uygulamahttps://t.me/<bot_username>/<app_name>adresinde açılır. - Menü butonu: @BotFather'da
/setmenubuttonveya Bot Settings → Menu Button'u kullanın ya dasetChatMenuButtonmetodunu çağırın. - Klavye butonları: reply klavyede veya inline klavyede bir
web_appbutonu (yalnızca özel sohbetlerde).
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button": {"type": "web_app", "text": "Uygulamayı aç",
"web_app": {"url": "https://your-tunnel.example.com"}}}'
chat_id verilmezse bu çağrı tüm kullanıcılar için varsayılan menü butonunu ayarlar. Tünel adresiniz her değiştiğinde curl'ü yeniden yazmak yerine çağrıyı Bot API Tester'da setChatMenuButton ile tekrarlayın.
4. Adım: Telegram test ortamını kullanın
Telegram'ın ayrı bir test ortamı vardır; burada Mini App linkleri TLS'siz düz HTTP kullanabilir, bu da yerel ağda test için kullanışlıdır. Kendi hesabını ve kendi botunu gerektirir:
- iOS: Ayarlar simgesine 10 kez dokunun → Accounts → Login to another account → Test.
- Telegram Desktop: ☰ Settings → Shift+Alt+sağ tık "Add Account" → Test Server.
- macOS: Debug Menu'yü açmak için Ayarlar simgesine 10 kez tıklayın, ardından ⌘+tık "Add Account".
Test hesabında @BotFather ile bir bot oluşturun ve API çağrılarını https://api.telegram.org/bot<token>/test/METHOD_NAME adresine gönderin. Flood limitleri orada yükseltilmez, hatta daha sıkı olabilir; yük testi için uygun bir yer değildir. Bot API Tester'daki TEST anahtarı dahil tam kurulum Telegram test sunucusu rehberinde.
5. Adım: Mini App'te Telegram içinde hata ayıklayın
Chrome'da hiç görünmeyen birçok hata yalnızca gerçek WebView'da ortaya çıkar. Telegram'ın resmi Debug Mode for Mini Apps talimatlarının özeti:
| Platform | Nasıl incelenir |
|---|---|
| iOS | Ayarlar simgesine 10 kez dokunup Allow Web View Inspection'ı açın; USB ile bağlayın ve Mac'teki Safari'de Develop → cihazınız'ı açın. |
| Android | USB hata ayıklamayı açın; Telegram Ayarlar'ında en alta inin, sürüm numarasına iki kez basılı tutun, Enable WebView Debug'ı seçin; Chrome'da chrome://inspect/#devices adresini açın. |
| Telegram Desktop (Windows, Linux) | Beta sürümü kurun; Settings → Advanced → Experimental settings → Enable webview inspection; sağ tık → Inspect. |
| Telegram for macOS | Beta sürümü kurun; Ayarlar simgesine 5 kez tıklayıp Debug Mini Apps'i açın; sağ tık → Inspect Element. |
İstemcileri hızlıca karşılaştırmak için https://telegram-bot-api.info/telegram-mini-app-tester.html adresini bir test botunun Mini App URL'si olarak ayarlayın. Telegram içinde Mini App Tester gerçek API'yi kullanır ve version, platform, colorScheme, themeParams, güvenli alanları (safe area) ve ilgili istemcinin tetiklediği her olayı gösterir. Kendi kodunuzda herkesin en yeni uygulamayı kullandığını varsaymayın; yeni özellikleri Telegram.WebApp.isVersionAtLeast("8.0") ile kontrol edin.
6. Adım: initData'yı sunucuda doğrulayın
Telegram.WebApp.initDataUnsafe yalnızca görüntüleme içindir. Ham Telegram.WebApp.initData metnini backend'inize gönderin ve doğrulayın:
- Query string'i ayrıştırın ve
hash'i çıkarın. - Kalan alanları alfabetik sıralayın ve
\nile ayrılmışkey=valuesatırları olarak birleştirin: budata_check_string'dir. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token)değerini hesaplayın.hex(HMAC_SHA256(key=secret_key, message=data_check_string))değerihash'e eşitse veri gerçektir.auth_date'i kontrol ederek eski verileri reddedin.
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") };
}
İstemcide metni değiştirmeden gönderin, ör. fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }), ve uygulamayı başlatan botun token'ıyla doğrulayın. Token'ınızı bilmemesi gereken üçüncü bir taraf ise resmi dokümantasyonda anlatıldığı gibi signature alanını Telegram'ın Ed25519 açık anahtarıyla doğrulayabilir.
Bot API 10.2: Mini App origin koruması
Bot API 10.2, Mini App metotlarının asıl Mini App alan adı dışındaki origin'lerden çağrılmasını yasakladı; koruma 20 Temmuz 2026'da tüm Mini App'ler için etkinleştirildi. Test sırasında bu, uygulama kayıtlı tünel adresinden staging alan adı veya giriş sayfası gibi başka bir host'a yönlendirdiğinde can yakar: orada Telegram.WebApp çağrıları çalışmaz. Telegram ile konuşan kodu kayıtlı alan adında tutun ve tünel host'u her değiştiğinde adresi yeniden kaydedin. Korumayı @BotFather'daki Mini App ayarlarından kapatabilirsiniz, ancak bu durumda Mini App'te güvenilmeyen sitelere link olmamasını sağlamak size kalır.
Telegram Mini App test kontrol listesi
- Arayüz mock modda ve hem açık hem koyu temada çalışıyor.
Telegram.WebApp.ready(), temel arayüz çizilir çizilmez çağrılıyor.- @BotFather'daki veya
setChatMenuButtonile verilen adres, güncel tünel ya da üretim alan adınızla eşleşiyor. - iOS, Android ve masaüstünde DevTools ile test edildi; yeni özellikler
isVersionAtLeast()ile kontrol ediliyor. - Tam ekran düzenler
safeAreaInsetvecontentSafeAreaInset'e uyuyor. - Backend
initData'yı (hash veauth_date) doğruluyor veinitDataUnsafe'e asla güvenmiyor. - Tüm
Telegram.WebAppçağrıları kayıtlı origin üzerinde çalışıyor. - Üretim geçici bir tünelde değil, geçerli sertifikalı kendi alan adınızda çalışıyor.
Doğrulama kodunuz bot token'ına dayanır, bu yüzden onu gizli tutun: bot token alma ve koruma rehberine bakın. Aynı backend bot güncellemelerini de alıyorsa Telegram bot webhook kurulumu ile devam edin. Tam bir web uygulaması yerine sohbet mesajının içinde küçük bir etkileşimli blok yeterliyse Bot API 10.4 ile gelen Telegram widget'larına göz atın.
Sık sorulan sorular
Telegram Mini App localhost'ta nasıl test edilir?
Telegram Mini App'leri yalnızca HTTPS adreslerinden açar. Geliştirme sunucunuzu bir HTTPS tüneliyle (ör. ngrok veya Cloudflare Tunnel) dışarı açın ve bu adresi @BotFather'da ya da setChatMenuButton ile kaydedin. Test ortamında düz HTTP linklerine izin verilir.
Telegram Mini App Telegram olmadan test edilebilir mi?
Kısmen. Normal tarayıcıda Telegram istemcisi yoktur; bu yüzden Mini App Tester'ın mock modu gibi bir Telegram.WebApp taklidi gerekir. Gerçek initData, yerel popup'lar ve titreşim (haptics) yalnızca Telegram içinde çalışır.
Telegram Mini App için DevTools nasıl açılır?
iOS'ta Ayarlar simgesine 10 kez dokunup Allow Web View Inspection'ı açın ve Safari'nin Develop menüsünü kullanın. Android'de Telegram hata ayıklama ayarlarından WebView Debug'ı açıp chrome://inspect/#devices adresine gidin. Masaüstü ve macOS'ta beta sürümlerin webview inceleme seçeneklerini kullanın.
initData doğrulaması neden başarısız oluyor?
Sık nedenler: ham initData metni yerine initDataUnsafe'i doğrulamak, başka bir botun token'ını kullanmak, değerleri URL-decode etmemek, hash'i data-check string'de bırakmak, HMAC anahtarı ile mesajı karıştırmak veya Telegram'ın hiç imzalamadığı mock verilerle test etmek.
Telegram.WebApp metotları başka bir alan adında neden çalışmıyor?
Bot API 10.2'den beri Mini App metotları, Mini App alan adından farklı bir origin'den çağrıldığında engellenir; koruma 20 Temmuz 2026'da tüm Mini App'ler için açıldı. Uygulamayı kayıtlı alan adında tutun veya @BotFather'dan bu korumayı kapatın.
Telegram Mini App için ayrı bir test sunucusu var mı?
Evet. Test ortamı üretimden tamamen ayrıdır: orada yeni bir hesap ve yeni bir bot gerekir, Bot API çağrıları https://api.telegram.org/bot<token>/test/METHOD_NAME adresine gider ve Mini App linkleri TLS'siz HTTP kullanabilir.
İlgili rehberler
Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma
Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.
Telegram botu nasıl deploy edilir: VPS, Docker ve serverless hosting
Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.
Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası
Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.
Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür
Telegram Bot API hataları: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nedenleri, çözümleri ve hata yönetimi kodu.
Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu
Telegram Bot API limitleri: saniyede 30 mesaj, sohbet başına 1 mesaj/sn, grupta dakikada 20, 429 retry_after yönetimi, dosya boyutu ve mesaj uzunluğu.
Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link
Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.
Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye
Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.
n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme
n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.
Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript
Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.
Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?
Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.
Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme
Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.
Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım
Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.
Telegram inline bot: inline modu açma ve inline sorguları yanıtlama
Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.
Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler
Telegram botunuzda Stars ile ödeme alın: XTR ile sendInvoice, pre_checkout_query, successful_payment, iade ve abonelikler; Python ve JS kodu.
Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?
Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.
Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu
Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.
TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar
Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.
Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu
Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.
Telegram widget: bot mesajının içinde çalışan etkileşimli HTML
Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?