Telegram Bot API

Validador de initData de Mini Apps de Telegram

Pega Telegram.WebApp.initData y el token de tu bot para comprobar si el hash de la Mini App es válido: la misma verificación HMAC-SHA256 que debe hacer tu servidor, ejecutada localmente en tu navegador.

El token se queda en tu navegador (localStorage) y solo se envía a api.telegram.org.

Algoritmo: secret_key = HMAC_SHA256("WebAppData", bot_token); hash = hex(HMAC_SHA256(secret_key, data_check_string)), donde data_check_string son todos los campos excepto hash, ordenados por clave y unidos como key=value con \n.

Cómo verificar el hash de una Mini App de Telegram

  1. Obtén la cadena initData original en tu Mini App, por ejemplo mostrando en consola Telegram.WebApp.initData (no initDataUnsafe). También sirve un fragmento de URL que empiece con tgWebAppData=: el prefijo se elimina.
  2. Pega el token del bot que abre la Mini App.
  3. Pulsa Validar. Obtienes un veredicto válido/no válido, auth_date con su antigüedad (con un aviso si tiene más de 24 horas) y todos los campos analizados, con user y los demás valores JSON decodificados.

Cómo funciona la validación

La herramienta sigue el algoritmo oficial de Validating data received via the Mini App:

  1. Analiza initData como query string y aparta hash.
  2. Arma data_check_string: todos los demás campos como key=value (valores decodificados de URL), ordenados alfabéticamente y unidos con un salto de línea \n.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. Los datos son válidos si hex(HMAC_SHA256(key=secret_key, message=data_check_string)) es igual a hash.

La misma verificación en un servidor 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;
}

Revisa también auth_date en el servidor para que no se pueda reutilizar un initData antiguo e interceptado.

Por qué el hash no coincide

Privacidad

Ninguna solicitud sale de tu navegador: el HMAC se calcula con la Web Crypto API y el token se guarda solo en localStorage; nada llega a nuestro servidor. Para ver initData real de un lanzamiento, abre el /es/telegram-mini-app-tester.html dentro de Telegram. El flujo de pruebas completo está en /es/guides/test-telegram-mini-app.html; si necesitas un token nuevo, consulta /es/guides/telegram-bot-token.html.

Preguntas frecuentes

¿Cómo se validan los init data de una Web App de Telegram?

Calcula secret_key = HMAC_SHA256("WebAppData", bot_token), arma el data-check-string con todos los campos excepto hash, ordenados por clave y unidos con \n, y compara hex(HMAC_SHA256(secret_key, data_check_string)) con hash. La herramienta de arriba hace exactamente eso.

¿Por qué el hash de mi initData no es válido?

Normalmente el token es de otro bot, o initData se modificó: se decodificó, se volvió a codificar, se recortó o se reconstruyó a partir de initDataUnsafe. Pega la cadena original de Telegram.WebApp.initData.

¿Puedo confiar en initDataUnsafe?

No en el servidor. initDataUnsafe son solo datos ya analizados en el cliente; envía el initData original a tu backend y valida ahí el hash antes de confiar en el ID del usuario.

¿Qué antigüedad puede tener initData?

Telegram recomienda revisar auth_date para rechazar datos desactualizados, pero el límite lo decides tú. La herramienta muestra la antigüedad y avisa cuando los datos tienen más de 24 horas.

¿Se envía mi token del bot a algún lado?

No. El validador no hace solicitudes de red: el hash se calcula con la Web Crypto API en tu navegador. El token solo se recuerda en localStorage.

Otras utilidades

Buscador de chat IDEscapador de MarkdownV2 y HTMLVerificador de webhookBot API Tester