Telegram Bot API

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

  1. Mini App'inizde ham initData metnini alın; örneğin Telegram.WebApp.initData değerini loglayarak (initDataUnsafe değil). tgWebAppData= ile başlayan bir URL fragment'i de çalışır: ön ek kaldırılır.
  2. Mini App'i açan botun token'ını yapıştırın.
  3. Doğrula düğmesine basın. Geçerli/geçersiz sonucunu, yaşıyla birlikte auth_date değerini (24 saatten eskiyse uyarıyla) ve user ile 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:

  1. initData'yı bir query string olarak ayrıştırın ve hash değerini bir kenara ayırın.
  2. data_check_string oluşturun: diğer tüm alanlar key=value biçiminde (URL'den çözülmüş değerler), alfabetik sıralı ve satır sonu \n ile birleştirilmiş.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. hex(HMAC_SHA256(key=secret_key, message=data_check_string)) değeri hash ile 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

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