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
- Obtenha a string bruta de initData no seu Mini App, por exemplo registrando
Telegram.WebApp.initDatano log (nãoinitDataUnsafe). Um fragmento de URL que começa comtgWebAppData=também serve: o prefixo é removido. - Cole o token do bot que abre o Mini App.
- Clique em Validar. Você recebe o veredito válido/inválido, o
auth_datecom a idade (com aviso se tiver mais de 24 horas) e todos os campos extraídos, comusere outros valores JSON decodificados.
Como funciona a validação
A ferramenta segue o algoritmo oficial de Validating data received via the Mini App:
- Interprete o initData como query string e separe o
hash. - Monte a
data_check_string: todos os outros campos no formatokey=value(valores decodificados da URL), em ordem alfabética, unidos por uma quebra de linha\n. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).- Os dados são válidos se
hex(HMAC_SHA256(key=secret_key, message=data_check_string))for igual ahash.
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
- O token é de um bot diferente daquele que abriu o Mini App.
- O initData foi decodificado ou modificado antes da validação — passe sempre a string bruta.
- A string foi remontada a partir de
initDataUnsafe: a ordem dos campos e a codificação mudam, então o hash não vai conferir.
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