Telegram WebApp无法接收startapp参数，如何传递令牌换Bearer Token？

核心问题说明 #

你遇到的问题并非参数传递格式错误，而是WebApp端没有通过Telegram官方提供的方式获取参数——Telegram不会直接将startapp参数暴露在页面URL中，而是封装在WebApp的初始化数据里。

正确步骤 #

1. 确保链接格式合规

传递令牌的正确链接格式为：

t.me/<你的机器人用户名>/<WebApp短名称>?startapp=<你的唯一用户令牌>

注意：

• <WebApp短名称>必须和你在BotFather中创建WebApp时填写的Short name完全一致
• 如果令牌包含特殊字符（如&、=），需先用encodeURIComponent()编码后再传入

2. WebApp端正确获取令牌

在你的网站代码中，必须通过Telegram提供的window.Telegram.WebApp对象读取初始化数据，从中提取令牌：

// 先初始化WebApp
window.Telegram.WebApp.ready();

// 解析初始化数据中的参数
const initDataParams = new URLSearchParams(window.Telegram.WebApp.initData);
const uniqueToken = initDataParams.get('start_param');

// 兑换Bearer Token的逻辑
if (uniqueToken) {
  // 调用后端接口兑换令牌
  fetch('/api/exchange-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userToken: uniqueToken })
  })
  .then(res => res.json())
  .then(data => {
    // 将Bearer Token存入Cookie
    document.cookie = `BearerToken=${data.bearerToken}; path=/; secure; SameSite=Strict`;
    // 执行后续授权逻辑
  });
}

3. 常见错误排查

• 直接读取页面URL参数：Telegram WebApp加载时会隐藏原始URL参数，无法通过window.location.search获取startapp
• WebApp短名称错误：链接中的路径必须和BotFather配置的短名称完全匹配，大小写敏感
• 未初始化WebApp：必须调用window.Telegram.WebApp.ready()后才能正确读取初始化数据
• 未验证签名（生产环境必做）：后端需要用机器人的Token验证initData的签名，防止参数被篡改

内容的提问来源于stack exchange，提问作者Daniel Protopopov