许多开发者在使用 Telegram 机器人时，希望嵌入一个可以直接在 Telegram 客户端内打开的网页应用（Web App），但不知道如何通过 Telegram Web App API 进行配置和调用。常见的问题包括：不知道如何创建 Web App 链接、如何在机器人中发送 Web App 按钮、如何接收用户数据以及如何处理 API 返回的初始化信息。本文将手把手带你完成从准备到验证的全流程。

准备工作：注册机器人并获取 Token

在调用 Telegram Web App API 之前，你需要拥有一个 Telegram 机器人，并获取其 API Token。

具体操作说明：

1. 打开 Telegram，搜索 BotFather（官方机器人创建工具）。

2. 向 BotFather 发送 /newbot命令，按照提示设置机器人名称和用户名（用户名需以 bot结尾）。

3. 创建成功后，BotFather 会返回一个 API Token，格式类似 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。请妥善保存此 Token。

4. 如果你已有机器人，直接使用现有 Token 即可。

注意事项/小提示：

  • Token 是机器人的唯一凭证，不要泄露给他人。
  • 机器人用户名一旦设定，无法修改，请谨慎命名。
  • 建议将 Token 保存在环境变量或配置文件中，避免硬编码。

备用方案：

  • 如果找不到 BotFather，请确认你的 Telegram 客户端已更新至最新版本。
  • 若忘记 Token，可向 BotFather 发送 /mybots，选择对应机器人，然后点击 API Token重新获取。

创建 Web App 的前端页面

你需要一个可以被 Telegram 客户端内嵌加载的网页，该页面需要通过 Telegram Web App API 与机器人交互。

具体操作说明：

1. 准备一个 HTML 文件，例如 index.html，并在其中引入 Telegram Web App 的 SDK：在 标签内添加 。

2. 在页面加载完成后，通过 window.Telegram.WebApp对象获取用户信息。例如，使用 Telegram.WebApp.initData获取初始化数据，或使用 Telegram.WebApp.sendData()向机器人发送数据。

3. 将你的网页部署到公网可访问的服务器上（例如使用 GitHub Pages、Vercel、Netlify 或自己的云服务器），并记录下完整的 HTTPS 链接（例如 https://yourdomain.com/index.html）。

4. 确保你的网页支持 HTTPS 协议，因为 Telegram 强制要求 Web App 使用 HTTPS。

注意事项/小提示：

  • 开发阶段可使用本地服务器测试，但最终上线必须使用 HTTPS。
  • 不要直接在页面中硬编码敏感信息，所有用户数据应通过 initData安全获取。
  • 建议在页面中添加 Telegram.WebApp.ready()方法，通知 Telegram 页面已准备就绪。

备用方案：

  • 如果没有公网服务器，可以使用 ngrok将本地服务临时映射到公网，方便测试。
  • 若不想编写前端代码，也可以使用现成的 Web App 模板（如 GitHub 上的 Telegram-Web-App-Boilerplate）。

在机器人中配置 Web App 按钮

你需要让机器人能够发送一个带有 Web App 按钮的消息，用户点击后即可打开你的网页。

具体操作说明：

1. 使用机器人 API 发送消息时，在 InlineKeyboardMarkup或 ReplyKeyboardMarkup中添加一个 WebAppInfo类型的按钮。

2. 例如，使用 Python 的 python-telegram-bot库，代码如下：

`python

from telegram import InlineKeyboardButton, InlineKeyboardMarkup

button = InlineKeyboardButton(text="打开应用", web_app={"url": "https://yourdomain.com/index.html"})

keyboard = InlineKeyboardMarkup([[button]])

await update.message.reply_text("点击下方按钮打开 Web App", reply_markup=keyboard)

`

3. 如果你使用其他编程语言（如 Node.js、PHP），请参考对应 Telegram Bot API 文档，核心是设置 web_app字段并传入你的网页 URL。

4. 发送消息后，用户会在 Telegram 聊天界面看到一个按钮，点击后将在 Telegram 内置浏览器中打开你的网页。

注意事项/小提示：

  • Web App 的 URL 必须为 HTTPS，且域名不能是 IP 地址（除非是 localhost 测试）。
  • 按钮文本应简洁明了，例如“打开应用”、“开始游戏”等。
  • 如果使用 ReplyKeyboardMarkup，按钮会显示在输入框上方，但建议使用 InlineKeyboardButton以获得更好体验。

备用方案：

  • 如果不想写代码，可以使用 @BotFather的 /setmenubutton命令，为机器人设置一个默认的 Web App 菜单按钮。
  • 也可以使用第三方机器人管理平台（如 ManyBot）来快速配置按钮。

接收并验证 Web App 初始化数据

当用户打开 Web App 时，Telegram 会将用户信息以 initData的形式传递给网页，你需要验证这些数据的真实性。

具体操作说明：

1. 在前端页面中，使用 Telegram.WebApp.initData获取原始数据字符串，该字符串包含用户 ID、用户名、哈希值等信息。

2. 将 initData发送到你的后端服务器进行验证。验证方法：使用机器人 Token 对 initData中的 query_id和 auth_date等字段进行 HMAC-SHA256 签名，并与 hash字段对比。

3. 例如，在 Python 后端中，验证逻辑如下：

`python

import hashlib, hmac

secret_key = hashlib.sha256(bot_token.encode()).digest()

check_string = "\n".join(sorted([f"{k}={v}" for k, v in data.items() if k != "hash"]))

computed_hash = hmac.new(secret_key, check_string.encode(), hashlib.sha256).hexdigest()

if computed_hash == data["hash"]:

print("验证成功")

`

4. 验证通过后，即可信任用户数据，并据此提供个性化服务或记录用户操作。

注意事项/小提示：

  • 永远不要在前端直接验证 initData，必须在后端进行签名校验。
  • initData中的数据可能包含 auth_date，建议检查该时间戳是否在合理范围内（例如 24 小时内），防止重放攻击。
  • 如果不需要用户身份验证，也可以直接使用 Telegram.WebApp.initDataUnsafe获取未验证的数据（仅用于非敏感场景）。

备用方案：

  • 如果后端语言不是 Python，可以参考 Telegram 官方文档中的 HMAC 验证示例，支持 Java、PHP、Node.js 等。
  • 可以使用现成的库如 telegram-web-app-validator来简化验证流程。

使用 Web App 向机器人发送数据

用户可以在 Web App 中完成操作后，通过 API 将数据发送回机器人，实现双向交互。

具体操作说明：

1. 在前端页面中，调用 Telegram.WebApp.sendData(data)方法，其中 data是一个字符串（通常为 JSON 格式）。

2. 例如，用户点击“提交”按钮时执行：

`javascript

Telegram.WebApp.sendData(JSON.stringify({action: "submit", value: "hello"}));

`

3. 机器人端会收到一个 Message对象，其 text字段即为 data字符串。你需要监听消息事件并解析该数据。

4. 例如，在 Python 机器人中：

`python

async def handle_message(update, context):

user_data = update.message.text

# 解析 JSON 并处理

`

5. 注意：sendData只能发送一次，且发送后 Web App 会自动关闭。如果需要多次交互，请使用 Telegram.WebApp.CloudStorage或自定义后端 API。

注意事项/小提示：

  • sendData发送的数据大小限制为 4096 字节，超出会失败。
  • 发送数据后，用户会回到聊天界面，机器人可以回复确认消息。
  • 如果需要在 Web App 中保持打开状态并多次交互，建议使用机器人 Webhook 或长轮询结合自定义 API。

备用方案：

  • 如果不希望关闭 Web App，可以使用 Telegram.WebApp.MainButton来触发 sendData，或者使用 Telegram.WebApp.BackButton控制导航。
  • 对于复杂应用，可以自己搭建后端接口，Web App 通过 AJAX 与后端通信，后端再通过 Bot API 向用户发送消息。

常见问题补充

问：Web App 在 Telegram 中打不开，显示“无法加载”怎么办？

答：首先检查你的网页 URL 是否为 HTTPS，且证书有效。然后确认域名没有被 Telegram 屏蔽。如果使用本地测试，请确保 ngrok 隧道正常运行。最后，在浏览器中直接打开该 URL 测试是否正常。

问：如何让 Web App 适配不同屏幕尺寸？

答：使用 Telegram.WebApp.expand()方法可以让 Web App 全屏显示。同时，利用 CSS 媒体查询和视口单位（如 vh、vw）来响应式布局。建议监听 Telegram.WebApp.onEvent('viewportChanged')事件动态调整页面。

问：initData中的 hash验证总是失败？

答：请检查你的签名算法是否与官方一致。注意字段排序必须按照字典序，且 hash字段本身不参与签名。另外，确认 bot_token使用的是原始 Token，而不是经过 URL 编码的版本。

问：Web App 能否获取用户的手机号或位置？

答：可以。Telegram Web App API 提供了 Telegram.WebApp.requestContact()和 Telegram.WebApp.requestLocation()方法，但需要用户主动授权。授权后数据会通过 initData或事件回调传递。

问：如何测试 Web App 在不同 Telegram 客户端（iOS/Android/Desktop）上的表现？

答：建议在多个设备上实际测试。注意 Desktop 版可能不支持某些触控手势。可以使用 Telegram.WebApp.platform属性判断当前平台，并做相应适配。

总结：接入 Telegram Web App API 的核心流程包括创建机器人、部署前端页面、配置按钮、验证初始化数据以及实现双向数据传递，每一步都需要严格遵循官方规范，尤其是 HTTPS 要求和签名验证机制。