Telegram Mini App initData Doğrulayıcı
Telegram.WebApp.initData değerini ve bot token'ınızı yapıştırarak Mini App hash'inin geçerli olup olmadığını kontrol edin — sunucunuzun yapması gereken HMAC-SHA256 kontrolünün aynısı, tarayıcınızda yerel olarak yapılır.
Token tarayıcınızda (localStorage) kalır ve yalnızca api.telegram.org adresine gönderilir.
Algoritma: secret_key = HMAC_SHA256("WebAppData", bot_token); hash = hex(HMAC_SHA256(secret_key, data_check_string)); burada data_check_string, hash dışındaki tüm alanların anahtara göre sıralanıp key=value biçiminde \n ile birleştirilmesidir.
Telegram Mini App hash'i nasıl kontrol edilir
- Mini App'inizde ham initData metnini alın; örneğin
Telegram.WebApp.initDatadeğerini loglayarak (initDataUnsafedeğil).tgWebAppData=ile başlayan bir URL fragment'i de çalışır: ön ek kaldırılır. - Mini App'i açan botun token'ını yapıştırın.
- Doğrula düğmesine basın. Geçerli/geçersiz sonucunu, yaşıyla birlikte
auth_datedeğerini (24 saatten eskiyse uyarıyla) veuserile diğer JSON değerleri çözülmüş halde tüm ayrıştırılmış alanları görürsünüz.
Doğrulama nasıl çalışır
Araç, Validating data received via the Mini App bölümündeki resmi algoritmayı izler:
- initData'yı bir query string olarak ayrıştırın ve
hashdeğerini bir kenara ayırın. data_check_stringoluşturun: diğer tüm alanlarkey=valuebiçiminde (URL'den çözülmüş değerler), alfabetik sıralı ve satır sonu\nile birleştirilmiş.secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).hex(HMAC_SHA256(key=secret_key, message=data_check_string))değerihashile eşitse veri geçerlidir.
Aynı kontrol bir Node.js sunucusunda:
const crypto = require('crypto');
function checkInitData(initData, botToken) {
const params = new URLSearchParams(initData);
const hash = params.get('hash');
params.delete('hash');
const dataCheckString = [...params]
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
.map(([k, v]) => `${k}=${v}`)
.join('\n');
const secret = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
const calc = crypto.createHmac('sha256', secret).update(dataCheckString).digest('hex');
return calc === hash;
}
Ele geçirilmiş eski bir initData'nın yeniden kullanılamaması için sunucuda auth_date değerini de kontrol edin.
Hash neden eşleşmiyor
- Token, Mini App'i başlatan bottan farklı bir bota ait.
- initData doğrulamadan önce çözülmüş veya değiştirilmiş — her zaman ham metni verin.
- Metin
initDataUnsafeverisinden yeniden oluşturulmuş: alan sırası ve kodlama farklıdır, bu yüzden hash eşleşmez.
Gizlilik
Hiçbir istek tarayıcınızdan çıkmaz: HMAC, Web Crypto API ile hesaplanır ve token yalnızca localStorage'da tutulur — hiçbir şey sunucumuza ulaşmaz. Gerçek bir başlatmadan canlı initData görmek için /tr/telegram-mini-app-tester.html aracını Telegram içinde açın. Tüm test süreci /tr/guides/test-telegram-mini-app.html rehberindedir; yeni bir token gerekiyorsa /tr/guides/telegram-bot-token.html rehberine bakın.
Sık sorulan sorular
Telegram Web App init verisi nasıl doğrulanır?
secret_key = HMAC_SHA256("WebAppData", bot_token) hesaplayın, hash dışındaki tüm alanları anahtara göre sıralayıp \n ile birleştirerek data-check-string'i oluşturun ve hex(HMAC_SHA256(secret_key, data_check_string)) değerini hash ile karşılaştırın. Yukarıdaki araç tam olarak bunu yapar.
initData hash'im neden geçersiz?
Genellikle token başka bir bota aittir ya da initData değiştirilmiştir: çözülmüş, yeniden kodlanmış, kırpılmış veya initDataUnsafe verisinden yeniden oluşturulmuş. Ham Telegram.WebApp.initData metnini yapıştırın.
initDataUnsafe'e güvenebilir miyim?
Sunucuda hayır. initDataUnsafe istemcide ayrıştırılmış veriden ibarettir; ham initData değerini backend'inize gönderin ve kullanıcı ID'sine güvenmeden önce hash'i orada doğrulayın.
initData ne kadar eski olabilir?
Telegram eskimiş veriyi reddetmek için auth_date kontrolünü önerir, ancak sınır size kalmıştır. Araç yaşı gösterir ve veri 24 saatten eskiyse uyarır.
Bot token'ım bir yere gönderiliyor mu?
Hayır. Doğrulayıcı hiçbir ağ isteği yapmaz: hash tarayıcınızda Web Crypto API ile hesaplanır. Token yalnızca localStorage'da hatırlanır.
Diğer yardımcı araçlar
Chat ID bulucuMarkdownV2 ve HTML kaçışlayıcıWebhook denetleyiciBot API Tester