如何配置 Telegram 登录与 Mini App

Stream 站点部署完成后，若要在网站中 使用 Telegram 账号登录，或在 Telegram 内 打开 Mini App，还需要在 BotFather 中为机器人完成两项配置：

本教程分两部分：先配置 Domain，再配置 Mini App。请使用你 已部署完成的网站域名（下文以 https://tgff.ccwu.cc 为例，请替换为你自己的地址）。

!!! info "前置条件" - 已完成 Stream 站点部署 - 已拥有可用的 Bot 和 Bot Token（若尚未创建，请先阅读 如何申请 Telegram Bot 并获取 Token） - 网站域名已可正常访问（建议已启用 HTTPS）

开始之前，请先准备好

第一部分：配置 Domain（开通 Telegram 登录）

第一步：进入 Bot 管理并打开 Bot Settings

1. 在 Telegram 中打开 @BotFather
2. 发送 /mybots
3. 在列表中选择你要配置的机器人（示例：@tmk_wj_bot）
4. 点击 「Bot Settings」

第二步：进入 Domain 设置

在 Settings for @你的机器人 页面，点击 「Domain」。

第三步：开始绑定域名

若尚未配置过 Domain，BotFather 会提示 Web login is currently unavailable，点击 「Set domain」 继续。

第四步：发送网站 URL

BotFather 会提示：

Link your website with your bot to use the Telegram Login Widget.

请在输入框发送你的 网站完整 URL（必须带 https://），例如：

https://tgff.ccwu.cc

!!! warning "请填写完整 URL" - 必须包含 https:// 协议头 - 域名需与 Stream 站点 实际访问地址一致 - 不要使用带路径的地址（如 /admin），填写站点根域名即可

第五步：确认 Domain 配置成功

发送 URL 后，BotFather 返回 「Success! Domain updated.」 表示绑定成功。

此时你的网站已授权使用该 Bot 进行 Telegram 登录。点击 「« Back to Bot」 返回机器人管理页，继续第二部分 Mini App 配置。

第六步：返回 Bot Settings（准备配置 Mini App）

点击 「« Back to Bot」 后，会回到机器人管理菜单。再次点击 「Bot Settings」，进入下一步 Mini App 配置。

!!! tip "如何移除 Domain？" 若需更换域名，重新进入 Domain 设置，发送新 URL 即可覆盖。发送 /empty 可清除已绑定的 Domain。

第二部分：配置 Mini App

第七步：进入 Configure Mini App

在 Bot Settings 页面，点击 「Configure Mini App」。

第八步：启用 Mini App

若 BotFather 提示 Mini App is currently disabled，点击 「Enable Mini App」 开启。

第九步：发送 Mini App URL

BotFather 会提示：

Send me the Mini App URL that will be opened by tapping the 'Open App' button.

发送你的网站地址（通常与 Domain 相同），例如：

https://tgff.ccwu.cc

!!! info "Domain 与 Mini App URL 的关系" 两者通常填写 同一个站点根 URL。Domain 用于登录授权，Mini App URL 用于 Telegram 内打开网页。

第十步：确认 Mini App 配置成功

BotFather 返回 「Success! Mini App settings updated.」 表示配置完成。

第十一步：在 Telegram 中验证

打开你的 机器人资料页，应出现 「打开应用」 按钮。点击后会在 Telegram 内打开你配置的网站，即 Mini App 入口。

!!! note "服务条款提示" 资料页底部可能出现 Telegram 开发者服务条款说明，属于正常提示。

配置完成后

将 Bot Token 与上述配置一并填入 TG-FF Stream 建站配置中，即可完整使用登录与 Mini App 能力。

常见问题

只配置 Domain，不配置 Mini App 可以吗？

可以。若只需要 网站 Telegram 登录，配置 Domain 即可。若希望用户在 Telegram 内通过「打开应用」访问站点，还需完成 Mini App 配置。

域名填错了怎么办？

重新进入 BotFather → /mybots → 选择 Bot → Bot Settings → Domain，发送正确的 URL 覆盖即可。

必须使用 HTTPS 吗？

是的。Telegram Login Widget 和 Mini App 都要求使用 HTTPS 站点地址。

一个 Bot 可以绑定多个域名吗？

BotFather 的 Domain 通常 一次只能绑定一个域名。若你有多个站点，建议为每个站点创建独立 Bot，或更换 Domain 后重新绑定。

配置后登录仍然失败？

请逐项检查：

1. Domain 中的 URL 是否与浏览器访问地址 完全一致（含 https://）
2. Stream 站点是否已成功部署并可访问
3. TG-FF 中填写的 Bot Token 是否与当前 Bot 一致
4. 是否使用了正确的 Bot（Domain 绑定在哪个 Bot 上，登录就用哪个 Bot 的 Token）

如何关闭 Mini App？

进入 Configure Mini App，向 BotFather 发送 /empty 即可禁用。

流程回顾

flowchart TB
    subgraph domain [第一部分：Domain 登录]
        A[/mybots 选择 Bot] --> B[Bot Settings]
        B --> C[Domain → Set domain]
        C --> D[发送 https 网站 URL]
        D --> E[Domain updated 成功]
    end
    subgraph mini [第二部分：Mini App]
        F[Bot Settings] --> G[Configure Mini App]
        G --> H[Enable Mini App]
        H --> I[发送 Mini App URL]
        I --> J[资料页出现打开应用]
    end
    E --> F

按以上步骤完成配置后，你的 Stream 站点即可支持 Telegram 登录 与 Mini App 访问。若尚未创建 Bot，请先阅读 Bot 申请教程；若尚未部署站点，请从 Stream 建站介绍 开始。遇到问题可加入 TG-FF 用户交流群 交流。