Telegram 消息渠道配置
2026/7/19大约 5 分钟
📱 Telegram 消息渠道配置
Telegram 渠道支持系统通知推送，也支持开启交互后在私聊/群聊里远程搜索、订阅、下载与执行命令。
交互不依赖公网回调，由 Media Saber 主动长轮询 Bot 更新，家宽 / NAS 环境即可使用。
配置前请先阅读 消息通知 了解通用流程。
📋 配置流程概览
- 用 BotFather 创建机器人，拿到 Bot Token
- 获取接收通知的 Chat ID
- 在 Media Saber 添加 Telegram 渠道并保存
- （可选）开启「是否交互」，填写可交互用户
- 私聊机器人或在群内
@机器人验证交互
🤖 准备机器人
1. 创建 Bot
- 打开 Telegram，搜索并打开
@BotFather - 发送
/newbot，按提示设置名称与用户名 - 创建成功后复制 Bot Token（形如
123456:ABC-DEF...）
请妥善保管 Token，勿泄露到公开仓库或截图外传。
2. 获取 Chat ID
Chat ID 用于接收系统通知（订阅完成、下载结果等）。
常见方式：
- 私聊
@userinfobot或@getidsbot，按其提示获取你的用户 ID - 若通知打到群组：把机器人拉进群，用群 ID 机器人获取（群 ID 多为负数）
- 频道场景使用频道 ID（通常也是负数）
🛠 在 Media Saber 中配置
进入：系统设置 → 消息通知 → 添加渠道，类型选择 Telegram。
基础字段
| 字段 | 是否必填 | 说明 |
|---|---|---|
| Bot Token | 是 | BotFather 下发的 Token |
| Chat ID | 是 | 系统通知默认接收会话 |
| 代理域名 | 否 | 无法直连 api.telegram.org 时填写可访问的反向代理根地址，默认官方地址 |
| 可交互用户 | 否 | 允许执行交互命令的 Telegram 用户数字 ID，多个用 ; 分隔；为空表示不限制 |
开关建议
- 是否开启：打开后才会推送通知
- 是否交互：打开后才会启动长轮询并接收命令；只做通知可关闭
- 推送业务类型：按需勾选订阅、下载、系统等业务
保存成功后：
- 未开交互：仅出站推送
- 已开交互：自动启动监听，一般无需重启；修改 Token 后建议再保存一次确认监听已刷新
🔄 交互能力说明
开启「是否交互」后，可用同一套命令/流程远程操作 Media Saber。
私聊
直接给机器人发：
- 关键词：搜索媒体
订阅+ 关键词 / 序号：订阅- 序号、
下载+ 序号：选择与下载 n/下一页、p/上一页：翻页/help：帮助与命令列表
机器人输入框旁的命令菜单（如 /help、/ssi、/nas 等）也会自动同步。
群聊
为避免刷屏，群内规则更严格：
- 命令（以
/开头）会处理 - 普通关键词需
@机器人后才会处理 - 未 @ 的普通闲聊会被忽略
按钮交互
搜索结果、种子列表、云端资源列表等，除了文字输入外，还可点消息下方按钮：
- 序号按钮：选择对应条目
- 上一页 / 下一页
- 下载类列表：
下载1、下载2…
按钮与文字指令等价，可混用。
回执与通知的区别
| 类型 | 发到哪里 |
|---|---|
| 系统业务通知 | 配置里的 Chat ID |
| 交互命令回执 | 你当前对话的会话（私聊或群） |
因此可以把「通知群」和「交互私聊」分开使用：Chat ID 填群，人在私聊里搜片也不会把过程刷到群里。
权限
- 可交互用户 非空：仅名单内用户可交互；其他人会收到无权限提示
- 为空：任何能给机器人发消息的人都能交互（自担风险，建议生产环境填写）
- 用户数字 ID 可私聊
@userinfobot获取
🧪 联调检查清单
- 测试通知：渠道页点「测试」，确认配置 Chat ID 能收到消息
- 私聊交互：私聊机器人发
/help，应返回帮助 - 搜索闭环：发影片名 → 出列表 → 点序号或输入数字 → 继续订阅/下载
- 群聊：未 @ 发关键词应无响应；
@机器人 关键词应有响应 - 权限：把「可交互用户」设为你的 ID，用另一账号试应被拒绝
🌐 网络与代理
- 默认请求
https://api.telegram.org - 服务器无法直连时：
- 配置系统代理，或
- 在「代理域名」填写可用的 Telegram API 反代根地址（不要多写路径）
- 交互与推送共用同一 Token/代理配置
⚠️ 注意事项
- 同一 Bot 不要多实例同时开交互
多个 Media Saber 实例对同一 Token 做长轮询会冲突（Telegram 409），表现为交互时灵时不灵。一个 Bot 只给一个运行中的实例开交互。 - 不要给 Bot 同时配置 Webhook 又开本系统交互
系统启动监听前会清理 webhook；若你在其它平台又设了 webhook，会再次冲突。 - Token 变更后请重新保存渠道；系统会刷新监听并清理旧的拉取进度。
- 关闭交互或删除渠道后，监听会停止，命令菜单会清理。
- 群组请给机器人必要发言权限；禁言状态下无法回执。
- 图文通知使用 HTML 格式发送；列表过长会自动分页/分段，属正常行为。
🆘 常见问题
收不到系统通知？
检查 Bot Token、Chat ID、渠道是否开启，以及机器是否能访问 Telegram API。
能收通知但不能交互？
确认已打开「是否交互」并保存成功；私聊发 /help 试一次。
群里没反应？
是否 @了机器人 或发送了 /命令；是否被「可交互用户」拦截。
提示无权限？
把你的用户数字 ID 填进「可交互用户」，多个用 ; 分隔。
日志出现 getUpdates Conflict？
同一 Token 被多个进程轮询，或仍存在外部 webhook。保留单一交互实例即可。