Telegram Bot API

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

  1. 在 Mini App 中获取原始 initData 字符串,例如打印 Telegram.WebApp.initData(不是 initDataUnsafe)。以 tgWebAppData= 开头的 URL 片段也可以:前缀会被自动去掉。
  2. 粘贴打开该 Mini App 的机器人的 Token。
  3. 点击校验。你会得到有效/无效的结论、auth_date 及其时效(超过 24 小时会警告),以及解析出的全部字段,其中 user 和其他 JSON 值会被解码。

校验原理

工具遵循 Validating data received via the Mini App 中的官方算法:

  1. 把 initData 作为查询字符串解析,并把 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 被重放。

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