# Telegram 配置指南

在**通道管理**中添加 Telegram Bot 实例，保存 Bot Token 和可选的 Webhook 校验设置。本指南说明如何登录 Telegram、通过 BotFather 获取 Token、在 MOI 中创建实例并测试连接。

## 配置前准备

- 准备一个可登录的 Telegram 账号，用于创建和管理 Bot。
- 确认当前 MOI 工作区提供 **通道管理 > Telegram** 入口，并且你可以新增实例。
- 确认浏览器可以访问 Telegram，MOI 服务可以访问 Telegram Bot API。浏览器登录成功不能代替 MOI 服务端的网络检查。

## 一、登录 Telegram

打开 [Telegram 网页版](https://web.telegram.org/k/)。如果手机已经登录 Telegram，可以在手机中打开 **Settings > Devices > Add Device（设置 > 设备 > 添加设备）**，扫描网页版当前显示的二维码并确认登录。

也可以点击 **LOG IN BY PHONE NUMBER**，按页面提示使用手机号登录；点击 **使用简体中文继续** 可以切换界面语言。

```{figure} /assets/images/agents/guide-5-hd/telegram-web-login.png
:alt: Telegram 网页版登录页，提供二维码、手机号和 Passkey 登录入口，以及简体中文切换按钮。
:class: agent-guide-image
:figclass: agent-guide-shot

使用当前网页中的二维码登录；截图仅用于展示登录入口。
```

## 二、创建 Bot 并获取 Bot Token

1. 打开官方 [BotFather 页面](https://t.me/BotFather)，确认用户名为 **@BotFather**，并带有认证标识。

```{figure} /assets/images/agents/guide-5-hd/telegram-botfather-entry.png
:alt: Telegram 官方 BotFather 页面，显示认证标识、用户名 @BotFather 和 START BOT 按钮。
:class: agent-guide-image
:figclass: agent-guide-shot

通过官方 BotFather 创建和管理机器人。
```

2. 点击 **START BOT**，在 Telegram 中打开 BotFather 会话。如果使用网页版，也可以登录后搜索 **@BotFather**，打开同一个官方账号。
3. 在 BotFather 会话中发送 `/newbot`。
4. 按提示填写机器人的显示名称，例如“MOI 通知”。
5. 按提示填写机器人用户名，例如 `example_moi_notice_bot`。用户名需未被占用，长度为 5～32 个字符，只能包含英文字母、数字和下划线，并以 `bot` 结尾。如果用户名已被占用，更换后重新提交。
6. 创建成功后，从 BotFather 的回复中复制 **Bot Token**，同时记录机器人的用户名或访问链接，便于后续核对目标。

Bot Token 是调用该机器人的凭据；机器人显示名称、`@用户名` 和个人登录验证码都不能替代它。Token 只填写在 MOI 的 **Bot Token** 字段，不放入描述、对话提示词或公开截图中。

## 三、在 MOI 中创建 Telegram 实例

1. 打开 MOI 的**通道管理**，在**沟通**分类中选择 **Telegram**。
2. 在**工具实例**列表点击**新增**，打开**配置 Bot 消息与 Webhook**表单。

```{figure} /assets/images/agents/guide-5-hd/telegram-channel-instance-form.png
:alt: MOI Telegram 通道配置表单，包含工具实例名称、Bot Token、描述、Webhook Secret 和连接超时。
:class: agent-guide-image
:figclass: agent-guide-shot

填写 BotFather 签发的 Bot Token，按需展开高级配置。
```

3. 按下表填写配置。**描述**、**Webhook Secret** 和**连接超时（秒）**位于**高级配置**中。

| 字段 | 是否必填 | 填写说明 |
| --- | --- | --- |
| 工具实例名称 | 必填 | 自行命名，例如“Telegram 项目通知”。用于在 MOI 中区分不同实例，不必与机器人的显示名称相同。 |
| Bot Token | 必填 | 粘贴 BotFather 签发的完整 Token，不要填写机器人用户名或在 Token 前添加 `bot`。 |
| 描述 | 可选 | 说明实例用途，例如“项目测试通知”。 |
| Webhook Secret | 可选 | 自行设置的 Webhook 校验密钥，与 Bot Token 分开配置。Telegram 请求中的 `secret_token` 必须使用同一个值。 |
| 连接超时（秒） | 可选 | 用于测试连接与工具调用。留空使用系统默认 30 秒，最大 300 秒。 |

Webhook Secret 对应 Telegram Bot API 的 `secret_token`：长度为 1～256 个字符，只能包含 `A-Z`、`a-z`、`0-9`、`_` 和 `-`。Telegram 会通过请求头 `X-Telegram-Bot-Api-Secret-Token` 携带这个值，用于校验回调请求。

4. 点击**保存**。返回实例列表后，确认刚创建的实例已出现，名称与预期一致。

```{note}
本页完成通道实例的凭据配置。填写 Webhook Secret 不等于已经向 Telegram 注册 Webhook，也不代表已经收到消息事件；保存后还需单独检测连接。
```

## 四、测试连接并核对配置

1. 在 Telegram 实例列表中找到刚创建的实例，点击对应的**测试连接**；也可以打开实例详情后点击**测试连接**。
2. 等待测试结果。通过时页面提示**连接测试通过**，列表中的**最近检测**显示本次检测结果和时间。
3. 打开实例详情，核对实例名称及连接超时。需要修正配置时，点击**编辑**，保存后重新测试。

**连接测试通过**表示当前连接检测通过，不代表已经发送消息或完成 Webhook 事件投递。验证实际业务时，还需分别核对 Telegram 中的接收结果或 MOI 中的事件处理结果。

## 五、维护实例与 Token

需要更换 Bot Token 时，在**通道管理 > Telegram**中编辑对应实例，填写新的 Token，保存并重新测试连接。不要用敏感字段是否明文回显判断 Token 是否正确，应以连接检测结果为准。

如果 Token 丢失或泄露，可在 BotFather 中使用 `/token`，按提示为对应机器人生成新 Token，再同步更新 MOI 中使用该机器人的实例。

不再使用某个实例时，在列表中核对名称后执行**断开连接**，并按提示确认。MOI 中断开实例与 Telegram 中删除 Bot 是两项独立操作。

## 常见问题

| 现象 | 处理方法 |
| --- | --- |
| 无法通过网页登录 | 已在手机登录时，使用手机 Telegram 的设备管理入口扫码；否则选择 **LOG IN BY PHONE NUMBER** 并按提示完成验证。 |
| 点击 START BOT 后没有打开会话 | 先登录 Telegram 客户端或网页版，再搜索带认证标识的 **@BotFather**。 |
| BotFather 不接受机器人用户名 | 检查用户名是否未被占用、长度是否为 5～32 个字符、是否以 `bot` 结尾，以及是否只使用英文字母、数字和下划线。 |
| 保存后连接测试失败 | 根据页面错误检查 Token 是否完整、是否来自目标 Bot，以及是否已被更换；同时检查 MOI 服务端到 Telegram Bot API 的网络连接。 |
| 不知道 Webhook Secret 从哪里获取 | 它由你自行设置，不是 BotFather 返回的 Bot Token。只在需要校验 Webhook 回调时配置，并保持两端取值一致。 |
| 增加超时后仍然失败 | 超时设置不能修正错误的 Token。先根据错误区分认证失败与网络超时，再处理对应配置。 |

## 相关链接

- [Telegram 网页版：登录账号](https://web.telegram.org/k/)
- [BotFather：创建和管理 Bot](https://t.me/BotFather)
- [查看连接与实例](../tool-detail.md)
- [返回工具配置指南目录](index.md)