Telegram Mini App initData 校验工具
粘贴 Telegram.WebApp.initData 和你的 Bot Token,即可检查 Mini App 的 hash 是否有效——这正是你的服务器必须执行的 HMAC-SHA256 校验,只不过在浏览器本地完成。
Token 只保存在你的浏览器中(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 的 hash
- 在 Mini App 中获取原始 initData 字符串,例如打印
Telegram.WebApp.initData(不是initDataUnsafe)。以tgWebAppData=开头的 URL 片段也可以:前缀会被自动去掉。 - 粘贴打开该 Mini App 的机器人的 Token。
- 点击校验。你会得到有效/无效的结论、
auth_date及其时效(超过 24 小时会警告),以及解析出的全部字段,其中user和其他 JSON 值会被解码。
校验原理
工具遵循 Validating data received via the Mini App 中的官方算法:
- 把 initData 作为查询字符串解析,并把
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 被重放。
hash 为什么不匹配
- Token 来自另一个机器人,而不是启动该 Mini App 的机器人。
- initData 在校验前被解码或修改过——请始终传入原始字符串。
- 字符串是从
initDataUnsafe重新拼出来的:字段顺序和编码都不同,hash 不会匹配。
隐私
没有任何请求离开你的浏览器:HMAC 用 Web Crypto API 计算,Token 只保存在 localStorage 中,不会到达我们的服务器。要查看真实启动时的 initData,请在 Telegram 中打开 /zh/telegram-mini-app-tester.html。完整的测试流程见 /zh/guides/test-telegram-mini-app.html;如果需要新的 Token,请参见 /zh/guides/telegram-bot-token.html。
常见问题
如何校验 Telegram Web App 的 init data?
计算 secret_key = HMAC_SHA256("WebAppData", bot_token),用除 hash 以外的所有字段按键名排序、以 \n 连接,构造 data-check-string,然后把 hex(HMAC_SHA256(secret_key, data_check_string)) 与 hash 比较。上方工具做的正是这件事。
为什么我的 initData hash 无效?
通常是 Token 属于另一个机器人,或者 initData 被改动过:被解码、重新编码、截断,或者是从 initDataUnsafe 重新拼出来的。请粘贴原始的 Telegram.WebApp.initData 字符串。
可以信任 initDataUnsafe 吗?
在服务器端不行。initDataUnsafe 只是客户端解析出的数据;请把原始 initData 发送到后端,在那里校验 hash 之后再信任用户 ID。
initData 多旧算过期?
Telegram 建议检查 auth_date 以拒绝过期数据,但具体期限由你决定。工具会显示数据的时效,超过 24 小时时给出警告。
我的 Bot Token 会被发送到别处吗?
不会。校验工具不发出任何网络请求:hash 在浏览器中用 Web Crypto API 计算。Token 只会被记在 localStorage 中。
其他工具
Chat ID 查询工具MarkdownV2 与 HTML 转义工具Webhook 检查工具Bot API Tester