Telegram Bot API

Validador de initData de Mini App do Telegram

Cole o Telegram.WebApp.initData e o token do seu bot para conferir se o hash do Mini App é válido — a mesma verificação HMAC-SHA256 que o seu servidor precisa fazer, executada localmente no navegador.

O token fica no seu navegador (localStorage) e é enviado apenas para api.telegram.org.

Algoritmo: secret_key = HMAC_SHA256("WebAppData", bot_token); hash = hex(HMAC_SHA256(secret_key, data_check_string)), onde data_check_string são todos os campos exceto hash, ordenados por chave e unidos como key=value com \n.

Como verificar o hash de um Mini App do Telegram

  1. Obtenha a string bruta de initData no seu Mini App, por exemplo registrando Telegram.WebApp.initData no log (não initDataUnsafe). Um fragmento de URL que começa com tgWebAppData= também serve: o prefixo é removido.
  2. Cole o token do bot que abre o Mini App.
  3. Clique em Validar. Você recebe o veredito válido/inválido, o auth_date com a idade (com aviso se tiver mais de 24 horas) e todos os campos extraídos, com user e outros valores JSON decodificados.

Como funciona a validação

A ferramenta segue o algoritmo oficial de Validating data received via the Mini App:

  1. Interprete o initData como query string e separe o hash.
  2. Monte a data_check_string: todos os outros campos no formato key=value (valores decodificados da URL), em ordem alfabética, unidos por uma quebra de linha \n.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. Os dados são válidos se hex(HMAC_SHA256(key=secret_key, message=data_check_string)) for igual a hash.

A mesma verificação em um 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;
}

Verifique também o auth_date no servidor, para que um initData antigo e interceptado não possa ser reutilizado.

Por que o hash não confere

Privacidade

Nenhuma requisição sai do seu navegador: o HMAC é calculado com a Web Crypto API, e o token fica apenas no localStorage — nada chega ao nosso servidor. Para ver initData real de uma abertura de verdade, abra o /pt/telegram-mini-app-tester.html dentro do Telegram. O fluxo completo de testes está em /pt/guides/test-telegram-mini-app.html; se precisar de um novo token, veja /pt/guides/telegram-bot-token.html.

Perguntas frequentes

Como validar os init data de um Web App do Telegram?

Calcule secret_key = HMAC_SHA256("WebAppData", bot_token), monte a data-check-string com todos os campos exceto hash, ordenados por chave e unidos com \n, e compare hex(HMAC_SHA256(secret_key, data_check_string)) com hash. A ferramenta acima faz exatamente isso.

Por que o hash do meu initData é inválido?

Normalmente o token é de outro bot, ou o initData foi alterado: decodificado, recodificado, cortado ou remontado a partir de initDataUnsafe. Cole a string bruta de Telegram.WebApp.initData.

Posso confiar no initDataUnsafe?

Não no servidor. initDataUnsafe são apenas dados já interpretados no cliente; envie o initData bruto ao seu backend e valide o hash lá antes de confiar no ID do usuário.

Quão antigo o initData pode ser?

O Telegram recomenda verificar o auth_date para rejeitar dados desatualizados, mas o limite fica a seu critério. A ferramenta mostra a idade e avisa quando os dados têm mais de 24 horas.

O token do meu bot é enviado para algum lugar?

Não. O validador não faz requisições de rede: o hash é calculado com a Web Crypto API no seu navegador. O token é apenas lembrado no localStorage.

Outros utilitários

Localizador de chat IDEscape de MarkdownV2 e HTMLVerificador de webhookBot API Tester