Telegram 配置指南¶
在通道管理中添加 Telegram Bot 实例，保存 Bot Token 和可选的 Webhook 校验设置。本指南说明如何登录 Telegram、通过 BotFather 获取 Token、在 MOI 中创建实例并测试连接。
配置前准备¶
准备一个可登录的 Telegram 账号，用于创建和管理 Bot。
确认当前 MOI 工作区提供 通道管理 > Telegram 入口，并且你可以新增实例。
确认浏览器可以访问 Telegram，MOI 服务可以访问 Telegram Bot API。浏览器登录成功不能代替 MOI 服务端的网络检查。
一、登录 Telegram¶
打开 Telegram 网页版。如果手机已经登录 Telegram，可以在手机中打开 Settings > Devices > Add Device（设置 > 设备 > 添加设备），扫描网页版当前显示的二维码并确认登录。
也可以点击 LOG IN BY PHONE NUMBER，按页面提示使用手机号登录；点击 使用简体中文继续 可以切换界面语言。
使用当前网页中的二维码登录；截图仅用于展示登录入口。¶
二、创建 Bot 并获取 Bot Token¶
打开官方 BotFather 页面，确认用户名为 @BotFather，并带有认证标识。
通过官方 BotFather 创建和管理机器人。¶
点击 START BOT，在 Telegram 中打开 BotFather 会话。如果使用网页版，也可以登录后搜索 @BotFather，打开同一个官方账号。
在 BotFather 会话中发送
/newbot。按提示填写机器人的显示名称，例如“MOI 通知”。
按提示填写机器人用户名，例如
example_moi_notice_bot。用户名需未被占用，长度为 5～32 个字符，只能包含英文字母、数字和下划线，并以bot结尾。如果用户名已被占用，更换后重新提交。创建成功后，从 BotFather 的回复中复制 Bot Token，同时记录机器人的用户名或访问链接，便于后续核对目标。
Bot Token 是调用该机器人的凭据；机器人显示名称、@用户名 和个人登录验证码都不能替代它。Token 只填写在 MOI 的 Bot Token 字段，不放入描述、对话提示词或公开截图中。
三、在 MOI 中创建 Telegram 实例¶
打开 MOI 的通道管理，在沟通分类中选择 Telegram。
在工具实例列表点击新增，打开配置 Bot 消息与 Webhook表单。
填写 BotFather 签发的 Bot Token，按需展开高级配置。¶
按下表填写配置。描述、Webhook Secret 和连接超时（秒）位于高级配置中。
字段 |
是否必填 |
填写说明 |
|---|---|---|
工具实例名称 |
必填 |
自行命名，例如“Telegram 项目通知”。用于在 MOI 中区分不同实例，不必与机器人的显示名称相同。 |
Bot Token |
必填 |
粘贴 BotFather 签发的完整 Token，不要填写机器人用户名或在 Token 前添加 |
描述 |
可选 |
说明实例用途，例如“项目测试通知”。 |
Webhook Secret |
可选 |
自行设置的 Webhook 校验密钥，与 Bot Token 分开配置。Telegram 请求中的 |
连接超时（秒） |
可选 |
用于测试连接与工具调用。留空使用系统默认 30 秒，最大 300 秒。 |
Webhook Secret 对应 Telegram Bot API 的 secret_token：长度为 1～256 个字符，只能包含 A-Z、a-z、0-9、_ 和 -。Telegram 会通过请求头 X-Telegram-Bot-Api-Secret-Token 携带这个值，用于校验回调请求。
点击保存。返回实例列表后，确认刚创建的实例已出现，名称与预期一致。
备注
本页完成通道实例的凭据配置。填写 Webhook Secret 不等于已经向 Telegram 注册 Webhook，也不代表已经收到消息事件；保存后还需单独检测连接。
四、测试连接并核对配置¶
在 Telegram 实例列表中找到刚创建的实例，点击对应的测试连接；也可以打开实例详情后点击测试连接。
等待测试结果。通过时页面提示连接测试通过，列表中的最近检测显示本次检测结果和时间。
打开实例详情，核对实例名称及连接超时。需要修正配置时，点击编辑，保存后重新测试。
连接测试通过表示当前连接检测通过，不代表已经发送消息或完成 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 个字符、是否以 |
保存后连接测试失败 |
根据页面错误检查 Token 是否完整、是否来自目标 Bot，以及是否已被更换；同时检查 MOI 服务端到 Telegram Bot API 的网络连接。 |
不知道 Webhook Secret 从哪里获取 |
它由你自行设置，不是 BotFather 返回的 Bot Token。只在需要校验 Webhook 回调时配置，并保持两端取值一致。 |
增加超时后仍然失败 |
超时设置不能修正错误的 Token。先根据错误区分认证失败与网络超时，再处理对应配置。 |