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 під час запуску, відкрийте /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