Telegram Web App API 是 Telegram 为开发者提供的一套接口，允许你在 Telegram 聊天窗口中直接嵌入和运行基于网页的交互式应用，无需用户离开聊天界面。许多用户在使用 Telegram 机器人或频道时，会遇到点击链接后无法正常加载 Web App、调用 API 后数据不返回、或不知道如何在自己的机器人中集成 Web App 等问题。这些问题通常源于对 API 配置、前端参数传递或后端验证机制不熟悉。下面将详细讲解如何从准备到成功调用 Telegram Web App API 的完整流程。
准备工作：注册机器人并获取 Token
在调用任何 Telegram API 之前，你需要先拥有一个机器人，并获取其 API Token。
具体操作说明：
1. 打开 Telegram 应用，搜索 @BotFather并开始对话。
2. 发送指令 /newbot，按照提示依次输入你想要的机器人名称和用户名（用户名必须以 bot结尾，例如 MyWebAppBot）。
3. 创建成功后，BotFather会返回一串类似 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz的字符串，这就是你的 API Token，请务必妥善保存。
4. 为了后续能调用 Web App API，你还需要在 BotFather 中启用 Web App 功能：发送 /mybots，选择你的机器人，点击 Bot Settings→ Web Apps→ Turn on。
注意事项/小提示：
- Token 是机器人的唯一凭证，不要泄露给任何人。
- 机器人用户名一旦设定，无法修改，请谨慎命名。
- 在 BotFather 中启用 Web App 后，你的机器人才能响应 Web App 相关的请求。
备用方案：
- 如果忘记 Token，可以在 BotFather 中通过
/mybots→ 选择机器人 → API Token重新获取。 - 如果无法访问 BotFather，请检查网络连接或重新安装 Telegram 客户端。
创建并部署你的 Web App 页面
Web App 本质上是一个标准的网页，你需要编写 HTML/CSS/JavaScript 代码，并将其部署到公网可访问的服务器上（例如 GitHub Pages、Vercel 或自己的服务器）。
具体操作说明：
1. 创建一个新的文件夹，在内部新建 index.html文件，编写你的 Web 应用页面。例如，一个简单的打卡按钮页面。
2. 在页面中引入 Telegram Web App 的 JavaScript SDK：在 标签中添加 。
3. 在 JavaScript 代码中，你可以通过全局对象 window.Telegram.WebApp来调用 API，例如获取用户信息、关闭 Web App、发送数据给机器人等。示例代码：
`javascript
let tg = window.Telegram.WebApp;
tg.ready(); // 通知 Telegram 页面加载完成
let user = tg.initDataUnsafe.user; // 获取用户信息
console.log(user);
`
4. 将整个文件夹部署到静态托管平台。以 GitHub Pages 为例：将代码推送到 GitHub 仓库，然后在仓库设置中启用 Pages功能，选择 main分支和 /根目录。
5. 部署成功后，你会获得一个形如 https://你的用户名.github.io/你的仓库名/的公开 URL。
注意事项/小提示：
- 必须使用 HTTPS 协议，Telegram 不支持 HTTP 的 Web App 链接。
tg.ready()必须在页面加载完成后调用，否则可能导致 API 不可用。- 部署后，请确保 URL 可以直接在浏览器中正常打开，否则 Telegram 内也无法加载。
备用方案：
- 如果没有 GitHub 账户，可以使用 Vercel 或 Netlify 免费部署，流程类似。
- 如果不想使用第三方平台，可以购买一台云服务器，使用 Nginx 部署静态文件。
在机器人中绑定 Web App 链接
部署好页面后，你需要将 Web App 的链接与机器人的某个命令或按钮关联起来，这样用户点击后才能打开。
具体操作说明：
1. 打开 Telegram，找到你的机器人，发送 /setdomain给 BotFather，然后选择你的机器人，输入你部署的 Web App 域名（例如 你的用户名.github.io）。这一步是为了将域名加入白名单，否则 Web App 无法在 Telegram 内正常打开。
2. 在机器人代码中（使用 Python、Node.js 等语言），创建一个内联键盘按钮，按钮类型为 web_app，并指向你的 Web App URL。例如，使用 Python 的 python-telegram-bot库：
`python
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
button = InlineKeyboardButton(text="打开应用", web_app=WebAppInfo(url="你的完整URL"))
keyboard = InlineKeyboardMarkup([[button]])
`
3. 将上述按钮附加到某个命令（例如 /start）的回复中。当用户点击按钮时，Telegram 会直接弹出 Web App 页面。
注意事项/小提示：
/setdomain设置的域名必须与部署的域名完全一致，包括子域名。- 如果使用路径（如
https://域名/子路径/），也需要在域名中体现，但通常只设置根域名即可。 - 按钮文字尽量简短明确，例如“打开应用”或“开始使用”。
备用方案：
- 如果不写代码，可以使用一些机器人管理平台（如 Manybot）的可视化界面来添加 Web App 按钮。
- 如果
/setdomain操作失败，检查域名是否已备案或是否被墙。
调用 Web App API 发送数据给机器人
Web App 的核心功能之一是将用户在前端的操作结果（如填写表单、点击按钮）实时发送回机器人。这需要通过 window.Telegram.WebApp.sendData()方法实现。
具体操作说明：
1. 在 Web App 的前端页面中，编写一个事件处理函数，当用户完成操作后调用 sendData。例如，用户点击“提交”按钮后：
`javascript
document.getElementById('submitBtn').addEventListener('click', function() {
let data = JSON.stringify({ action: 'check_in', time: new Date().toISOString() });
window.Telegram.WebApp.sendData(data);
window.Telegram.WebApp.close(); // 可选：发送后自动关闭 Web App
});
`
2. 在机器人后端代码中，你需要监听来自 Web App 的数据。以 python-telegram-bot为例，在 MessageHandler中处理 filters.StatusUpdate.WEB_APP_DATA：
`python
async def web_app_data(update, context):
data = update.effective_message.web_app_data.data
user_id = update.effective_user.id
print(f"收到来自 {user_id} 的数据: {data}")
# 处理数据，例如存储到数据库
await update.message.reply_text("数据已接收！")
`
3. 将上述处理器添加到你的 Application中，例如 application.add_handler(MessageHandler(filters.StatusUpdate.WEB_APP_DATA, web_app_data))。
注意事项/小提示：
sendData只能发送字符串数据，建议使用 JSON 格式进行序列化。- 数据大小限制为 4096 字节，超过会发送失败。
- 机器人接收到的
web_app_data.data是原始字符串，需要手动解析。
备用方案：
- 如果不想关闭 Web App，可以省略
close()方法，让用户手动关闭。 - 如果数据发送失败，检查前端是否调用了
tg.ready()，以及域名是否在白名单中。
验证 Web App 调用结果
完成以上步骤后，你需要测试整个流程是否正常工作。
具体操作说明：
1. 在 Telegram 中与你的机器人对话，发送 /start命令，点击“打开应用”按钮。
2. 在弹出的 Web App 页面中，执行预设的操作（例如点击提交按钮）。观察页面是否正常关闭，或者是否有提示信息。
3. 返回与机器人的聊天窗口，查看机器人是否回复了“数据已接收！”或你设定的其他确认消息。
4. 在机器人后端日志中，检查是否打印出了用户发送的数据内容。
5. 如果一切正常，说明 Web App API 调用成功。如果未收到数据，请检查浏览器控制台是否有错误（在 Telegram 内无法直接查看，建议先在普通浏览器中调试）。
注意事项/小提示：
- 首次测试时，建议先在普通浏览器中打开 Web App URL，模拟 Telegram 环境（注意此时
window.Telegram.WebApp可能未定义，需要添加兼容性判断）。 - 如果 Web App 无法在 Telegram 内打开，检查
/setdomain是否设置正确，以及 URL 是否以https://开头。
备用方案：
- 如果机器人没有回复，检查后端代码中是否有语法错误或网络问题。
- 如果数据内容为空，检查前端
sendData是否在tg.ready()之后调用。
常见问题补充
问：Web App 在 Telegram 内打开后白屏怎么办？
答：首先检查 URL 是否可公网访问且为 HTTPS。其次，在浏览器中打开该 URL，查看控制台是否有 JavaScript 错误。常见原因包括：未引入 telegram-web-app.js、tg.ready()未调用、或域名未在白名单中。
问：如何获取用户的 Telegram ID？
答：在前端通过 window.Telegram.WebApp.initDataUnsafe.user.id获取。注意该数据是由 Telegram 客户端签名提供的，但 initDataUnsafe未经验证，仅供前端展示；如果需要安全验证，应使用 initData并在后端通过 HMAC 验证。
问：sendData发送后，机器人收不到数据？
答：检查机器人后端是否正确添加了 filters.StatusUpdate.WEB_APP_DATA处理器。同时确认前端调用 sendData时，Web App 页面没有被其他操作打断（如页面跳转）。另外，确保发送的数据不超过 4096 字节。
问：Web App 能否与机器人进行双向通信？
答：可以。除了通过 sendData向机器人发送消息，机器人也可以通过 answerWebAppQueryAPI 向 Web App 发送回复，但需要配合 query_id（来自 WebAppQuery类型）。这通常用于更复杂的交互场景。
总结：
通过注册机器人、部署 Web App 页面、绑定链接并正确调用
sendData和WEB_APP_DATA过滤器，即可实现 Telegram 内网页应用与机器人的双向数据交互。