Telegram Bot API

Валидатор initData для Telegram Mini App

Вставьте Telegram.WebApp.initData и токен бота, чтобы проверить хеш 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.

Как проверить хеш Telegram Mini App

  1. Получите исходную строку initData в своём Mini App, например выведите в консоль Telegram.WebApp.initData (не initDataUnsafe). Подойдёт и фрагмент URL, начинающийся с tgWebAppData=: префикс отбрасывается.
  2. Вставьте токен бота, который открывает Mini App.
  3. Нажмите Проверить. Вы увидите вердикт «валидно / невалидно», auth_date с возрастом (предупреждение, если старше 24 часов) и все поля, где user и другие JSON-значения уже разобраны.

Как работает проверка

Инструмент следует официальному алгоритму из раздела Validating data received via the Mini App:

  1. initData разбирается как query string, hash откладывается.
  2. Собирается data_check_string: все остальные поля в виде key=value (значения URL-декодированы), отсортированные по алфавиту и соединённые переводом строки \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 нельзя было использовать повторно.

Почему хеш не совпадает

Конфиденциальность

Ни один запрос не покидает браузер: HMAC считается через Web Crypto API, токен хранится только в localStorage — на наш сервер ничего не попадает. Чтобы увидеть реальную initData при запуске, откройте /ru/telegram-mini-app-tester.html внутри Telegram. Весь процесс тестирования описан в гайде /ru/guides/test-telegram-mini-app.html, а как получить новый токен — в /ru/guides/telegram-bot-token.html.

Частые вопросы

Как проверить initData Telegram Web App?

Вычислите secret_key = HMAC_SHA256("WebAppData", bot_token), соберите data-check-string из всех полей, кроме hash, отсортированных по ключу и соединённых через \n, и сравните hex(HMAC_SHA256(secret_key, data_check_string)) с hash. Инструмент выше делает именно это.

Почему хеш initData не совпадает?

Чаще всего токен от другого бота или initData изменили: декодировали, перекодировали, обрезали или собрали заново из initDataUnsafe. Вставляйте исходную строку Telegram.WebApp.initData.

Можно ли доверять initDataUnsafe?

Не на сервере. initDataUnsafe — просто разобранные данные на клиенте; отправляйте на бэкенд исходную initData и проверяйте хеш там, прежде чем доверять ID пользователя.

Насколько старой может быть initData?

Telegram рекомендует проверять auth_date, чтобы отклонять устаревшие данные, а порог вы выбираете сами. Инструмент показывает возраст и предупреждает, если данным больше 24 часов.

Отправляется ли куда-то мой токен?

Нет. Валидатор не делает сетевых запросов: хеш считается через Web Crypto API в вашем браузере. Токен лишь запоминается в localStorage.

Другие утилиты

Поиск chat IDЭкранирование MarkdownV2 и HTMLПроверка вебхукаBot API Tester