Валідатор 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
- Отримайте вихідний рядок initData у своєму Mini App, наприклад виведіть у консоль
Telegram.WebApp.initData(неinitDataUnsafe). Підійде й фрагмент URL, що починається зtgWebAppData=: префікс відкидається. - Вставте токен бота, який відкриває Mini App.
- Натисніть Перевірити. Ви побачите вердикт «валідно / невалідно»,
auth_dateз віком (попередження, якщо понад 24 години) і всі поля, деuserта інші JSON-значення вже розібрано.
Як працює перевірка
Інструмент дотримується офіційного алгоритму з розділу Validating data received via the Mini App:
- initData розбирається як query string,
hashвідкладається. - Складається
data_check_string: усі інші поля у виглядіkey=value(значення URL-декодовано), відсортовані за абеткою та з’єднані символом нового рядка\n. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).- Дані валідні, якщо
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 не можна було використати повторно.
Чому геш не збігається
- Токен від іншого бота, а не від того, що запустив Mini App.
- initData декодували або змінили до перевірки — завжди передавайте вихідний рядок.
- Рядок зібрали заново з
initDataUnsafe: порядок полів і кодування відрізняються, тож геш не збіжиться.
Конфіденційність
Жоден запит не залишає браузер: HMAC обчислюється через Web Crypto API, токен зберігається лише в localStorage — на наш сервер нічого не потрапляє. Щоб побачити реальну initData під час запуску, відкрийте /uk/telegram-mini-app-tester.html у Telegram. Увесь процес тестування описано в гайді /uk/guides/test-telegram-mini-app.html, а як отримати новий токен — у /uk/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