Telegram Bot API

اعتبارسنجی initData در Telegram Mini App

Telegram.WebApp.initData و توکن ربات خود را وارد کنید تا ببینید hash مربوط به Mini App معتبر است یا نه — همان بررسی HMAC-SHA256 که سرور شما باید انجام دهد، به‌صورت محلی در مرورگر.

توکن در مرورگر شما (localStorage) می‌ماند و فقط به api.telegram.org ارسال می‌شود.

الگوریتم: secret_key = HMAC_SHA256("WebAppData", bot_token); hash = hex(HMAC_SHA256(secret_key, data_check_string))، که در آن data_check_string همه فیلدها به‌جز hash است که بر اساس کلید مرتب شده و به شکل key=value با \n به هم وصل شده‌اند.

چطور hash را در Telegram Mini App بررسی کنیم

  1. رشته خام initData را در Mini App خود بگیرید، مثلاً با لاگ کردن Telegram.WebApp.initData (نه initDataUnsafe). بخشی از URL که با tgWebAppData= شروع می‌شود هم کار می‌کند: پیشوند حذف می‌شود.
  2. توکن رباتی را که Mini App را باز می‌کند وارد کنید.
  3. اعتبارسنجی را بزنید. نتیجه معتبر/نامعتبر، auth_date همراه با سن آن (با هشدار اگر قدیمی‌تر از 24 ساعت باشد) و همه فیلدهای تجزیه‌شده را می‌گیرید؛ user و دیگر مقادیر JSON هم decode می‌شوند.

اعتبارسنجی چطور کار می‌کند

ابزار از الگوریتم رسمی Validating data received via the Mini App پیروی می‌کند:

  1. initData را به‌عنوان query string تجزیه کنید و hash را کنار بگذارید.
  2. data_check_string را بسازید: همه فیلدهای دیگر به شکل key=value (مقادیر URL-decode شده)، به ترتیب الفبایی، که با شکست خط \n به هم وصل شده‌اند.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. داده معتبر است اگر hex(HMAC_SHA256(key=secret_key, message=data_check_string)) با hash برابر باشد.

همین بررسی روی سرور Node.js:

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;
}

روی سرور auth_date را هم بررسی کنید تا initData قدیمی و شنودشده قابل استفاده مجدد نباشد.

چرا hash مطابقت ندارد

حریم خصوصی

هیچ درخواستی از مرورگر شما خارج نمی‌شود: HMAC با Web Crypto API محاسبه می‌شود و توکن فقط در localStorage نگه داشته می‌شود — هیچ چیز به سرور ما نمی‌رسد. برای دیدن initData زنده از یک اجرای واقعی، /fa/telegram-mini-app-tester.html را داخل تلگرام باز کنید. روند کامل تست در /fa/guides/test-telegram-mini-app.html آمده است؛ اگر توکن جدید لازم دارید، /fa/guides/telegram-bot-token.html را ببینید.

پرسش‌های متداول

چطور init data در Telegram Web App را اعتبارسنجی کنم؟

secret_key = HMAC_SHA256("WebAppData", bot_token) را محاسبه کنید، data-check-string را از همه فیلدها به‌جز hash که بر اساس کلید مرتب و با \n به هم وصل شده‌اند بسازید و hex(HMAC_SHA256(secret_key, data_check_string)) را با hash مقایسه کنید. ابزار بالا دقیقاً همین کار را انجام می‌دهد.

چرا hash مربوط به initData من نامعتبر است؟

معمولاً توکن متعلق به ربات دیگری است، یا initData تغییر کرده است: decode شده، دوباره encode شده، کوتاه شده یا از روی initDataUnsafe بازسازی شده است. رشته خام Telegram.WebApp.initData را وارد کنید.

آیا می‌توانم به initDataUnsafe اعتماد کنم؟

روی سرور خیر. initDataUnsafe فقط داده تجزیه‌شده در کلاینت است؛ initData خام را به بک‌اند بفرستید و قبل از اعتماد به آیدی کاربر، hash را آنجا اعتبارسنجی کنید.

initData حداکثر چقدر می‌تواند قدیمی باشد؟

تلگرام توصیه می‌کند برای رد کردن داده‌های منسوخ auth_date را بررسی کنید، اما تعیین حد با شماست. ابزار سن داده را نشان می‌دهد و اگر بیش از 24 ساعت گذشته باشد هشدار می‌دهد.

آیا توکن ربات من جایی ارسال می‌شود؟

خیر. اعتبارسنج هیچ درخواست شبکه‌ای نمی‌فرستد: hash با Web Crypto API در مرورگر شما محاسبه می‌شود. توکن فقط در localStorage به خاطر سپرده می‌شود.

ابزارهای دیگر

یافتن چت آیدیاسکیپ MarkdownV2 و HTMLبررسی وب هوکBot API Tester