初始化数据

Mini App 启动时，客户端会通过 Telegram.WebApp.initData 传递一个经过签名的初始化数据字符串。该字符串包含了用户、聊天和启动参数等信息。

Telegram.WebApp.initDataUnsafe 提供了解析后的 WebAppInitData 对象，方便在客户端直接访问。

安全提示

initDataUnsafe 中的数据未经服务端验证，仅供客户端展示使用。涉及业务逻辑的数据必须在服务端使用 initData 原始字符串进行签名验证。

WebAppInitData

初始化数据对象，通过 Telegram.WebApp.initDataUnsafe 访问。

字段	类型	描述
query_id	String	用于 answerWebAppQuery 的唯一查询 ID
user	WebAppUser	当前用户信息
receiver	WebAppUser	对话中的另一方用户信息（仅私聊可用）
chat	WebAppChat	当前聊天信息（仅群组/频道可用）
chat_type	String	聊天类型："sender"、"private"、"group"、"supergroup"、"channel"
chat_instance	String	聊天实例的唯一标识
start_param	String	通过链接传递的启动参数
can_send_after	Integer	允许调用 sendData 的最早时间（Unix 时间戳）
auth_date	Integer	认证时间（Unix 时间戳）
hash	String	数据签名哈希值，用于验证
signature	String	数据签名，用于第三方验证。Bot API 8.0+

WebAppUser

用户信息对象。

字段	类型	描述
id	Integer	用户 ID
is_bot	Boolean	是否为 Bot
first_name	String	名字
last_name	String	姓氏（可选）
username	String	用户名（可选）
language_code	String	用户语言代码（如 "zh-hans"、"en"）
is_premium	Boolean	是否为 Premium 用户（可选）
added_to_attachment_menu	Boolean	是否已添加到附件菜单（可选）
allows_write_to_pm	Boolean	是否允许 Bot 发送私信（可选）
photo_url	String	用户头像 URL（可选）

WebAppChat

聊天信息对象。

字段	类型	描述
id	Integer	聊天 ID
type	String	聊天类型："group"、"supergroup"、"channel"
title	String	聊天标题
username	String	聊天用户名（可选）
photo_url	String	聊天头像 URL（可选）

使用示例

const tg = Telegram.WebApp;
const initData = tg.initDataUnsafe;

// 获取用户信息
if (initData.user) {
  console.log('用户 ID:', initData.user.id);
  console.log('用户名:', initData.user.first_name);
  console.log('语言:', initData.user.language_code);
  console.log('Premium:', initData.user.is_premium);
}

// 获取聊天信息
if (initData.chat) {
  console.log('聊天 ID:', initData.chat.id);
  console.log('聊天标题:', initData.chat.title);
}

// 获取启动参数
if (initData.start_param) {
  console.log('启动参数:', initData.start_param);
  handleStartParam(initData.start_param);
}

// 发送原始数据到服务端验证
fetch('/api/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ initData: tg.initData })
});

initData 查询字符串格式

Telegram.WebApp.initData 是一个 URL 编码的查询字符串，包含以下参数：

query_id=AAHd...&user=%7B%22id%22%3A123...%7D&auth_date=1234567890&hash=abc123...

解析后包含以下键值对：

键	值
query_id	查询 ID 字符串
user	JSON 编码的用户对象
receiver	JSON 编码的接收者对象
chat	JSON 编码的聊天对象
chat_type	聊天类型字符串
chat_instance	聊天实例 ID
start_param	启动参数
can_send_after	允许发送的时间戳
auth_date	认证时间戳
hash	HMAC-SHA256 签名
signature	Ed25519 签名

详细的验证方法请参阅数据验证。