本文详解 Telegram 内联按钮（inline button）调用 Web App 的关键实现要点，指出 callback_data 与 web_app 字段互斥的根本原因，并提供符合 Bot API 规范的 JSON 构建方式及完整可运行示例。
本文详解 telegram 内联按钮（inline button）调用 web app 的关键实现要点，指出 `callback_data` 与 `web_app` 字段互斥的根本原因，并提供符合 bot api 规范的 json 构建方式及完整可运行示例。
在 Telegram Bot 开发中，通过内联按钮（Inline Keyboard Button）启动 Web App 是常见需求，但极易因字段冲突导致功能失效。核心问题在于：web_app 和 callback_data 不可共存于同一个按钮对象中——这是 Telegram Bot API 的硬性约束（官方文档明确说明），一旦同时存在，Telegram 将忽略 web_app 字段，仅处理回调逻辑，从而导致点击后无任何页面跳转。
正确的实现必须严格遵循以下结构：
- 每个按钮对象仅包含 text 和 web_app（含 url），绝对不可混入 callback_data、url 或 switch_inline_query 等其他触发类字段；
- 整个内联键盘需以二维数组形式组织（即 [ [button1], [button2, button3] ]），再经 json_encode() 序列化为合法 JSON；
- Web App URL 必须使用 HTTPS 协议，且域名需提前在 @BotFather 中通过 /setdomain 设置白名单（否则 iOS/Android 客户端将拒绝打开）。
✅ 正确代码示例（PHP）：
// 构建单按钮内联键盘（推荐使用数组而非字符串拼接，避免 JSON 格式错误）
$inline = [
[
[
'text' => tgescape($row['text']), // 注意 HTML 转义防注入
'web_app' => ['url' => $row['val']] // 仅保留 web_app，无 callback_data
]
]
];
$reply_markup = [
'inline_keyboard' => $inline
];
sendMsg($bot['token'], $chatId, "Нажмите для запуска:", [
'reply_markup' => json_encode($reply_markup)
]);
⚠️ 关键注意事项：
- 禁止字符串拼接 JSON：原始代码中 $inline .= '[{"text":"...","web_app":{...},"callback_data":"..."}]' 易引发引号嵌套、特殊字符未转义等问题，极难调试；务必使用 json_encode() 生成结构化 JSON；
- URL 安全要求：Web App 地址必须为有效 HTTPS，且证书可信（自签名证书不被支持）；
- 域名白名单：首次部署前，必须用 BotFather 执行 /setdomain 并输入根域名（如 example.com），子路径（如 example.com/app）自动生效；
- 客户端兼容性：Web App 仅支持 Telegram iOS / Android 官方客户端（v.9.0+），桌面版和 Web 版暂不支持。
总结：内联 Web App 按钮失败的根源几乎总是字段冲突或 JSON 格式错误。牢记「一按钮一用途」原则——需要 Web App 就舍弃 callback_data；需要回调就改用普通按钮 + callback_data + 后端处理。两者不可兼得，但可通过 Web App 自身接口（如 window.Telegram.WebApp.sendData()）与 Bot 后端通信，实现更灵活的交互闭环。
