Telegram 集成配置
约 2161 字大约 7 分钟
2026-05-02
Telegram 集成是 ResourceTool 自动化能力的核心。通过配置 Bot 和 MTProto Session,实现频道监控、消息转发、链接自动转存和用户交互。本指南按功能模块分步讲解,从零搭建完整的 Telegram 自动化链路。
前置条件
- Telegram 账号
- 已在 my.telegram.org 创建应用,获取 API ID 和 API Hash
- 已在 @BotFather 创建 Bot,获取 Bot Token
第一部分:MTProto Session 登录
MTProto Session 使用你的 Telegram 用户账号登录,用于实时监听频道消息。这是频道监控和自动转存的基础。
为什么需要 Session?
Telegram Bot 无法监听非自己管理的频道消息,也无法读取频道历史消息。MTProto Session 以用户身份登录,可以实时监听所有已加入频道的消息,无上述限制。
登录步骤
进入侧边栏 插件库 → Telegram 助手,在 MTProto Session 区域:
填写 API 信息
输入 API ID、API Hash 和手机号
获取验证码
点击「发送验证码」,Telegram 会向该手机号发送验证码
输入验证码
在弹窗中输入收到的验证码
二步验证(如已开启)
如果账号开启了二步验证,还需输入二步验证密码
登录成功
Session 状态变为 已登录
Session 状态说明
| 状态 | 说明 |
|---|---|
| 在线 | Session 正常连接,频道监控运行中 |
| 离线 | 未登录或已断开,监控不工作 |
| 重连中 | 网络中断后自动重连 |
安全提示
- Session 等同于用你的个人账号登录 Telegram,请确保在安全环境下操作
- Session 信息加密存储在数据库中
- 一个账号同时只能有一个活跃的 MTProto Session
- 如果在其他设备登录相同账号,可能导致 Session 失效
第二部分:Bot 配置
主 Bot 配置
在同一个页面的 主 Bot 配置 区域:
| 配置项 | 说明 |
|---|---|
| Bot Token | 从 @BotFather 获取的 Bot Token |
| 白名单 | 允许使用 Bot 的用户 ID 列表,留空不限制 |
| Chat ID | Bot 发送通知的目标聊天 ID(用户/群组/频道) |
保存后 Bot 自动上线。
Bot 可用命令
| 命令 | 说明 |
|---|---|
/start | 启动 Bot,显示欢迎信息 |
/search 关键词 | 搜索影视资源(TMDB + HDHive) |
/logs | 查看最近的系统日志 |
/version | 查看当前版本号 |
Bot 通知类型
| 通知类型 | 触发场景 |
|---|---|
| 转存通知 | 成功 / 已转存 / 已失效 / 失败 |
| 离线通知 | 成功 / 审核中 / 已失效 / 失败 |
| 番号信息 | 自动从消息中提取的番号 |
转存通知和离线通知独立发送,状态精准区分。
Bot 重试机制
Bot 启动时如遇网络故障,会自动重试最多 3 次(指数退避 3s → 6s → 12s),避免网络抖动导致 Bot 永久离线。
副 Bot(按 115 账号绑定)
每个内置 115 账号可绑定独立的副 Bot,详见 115 云盘配置 - 步骤 2。
第三部分:频道监控转发
频道监控基于 MTProto Session 实时监听指定频道的消息,按规则自动转发到目标频道。
进入侧边栏 监控 → 监控转发,点击 添加规则:
基本信息
| 配置项 | 说明 |
|---|---|
| 规则名称 | 自定义名称 |
| 启用 | 开关 |
| 源频道 | 要监听的频道,支持搜索 TG 用户名或昵称,可添加多个 |
| 目标频道 | 转发目标频道,同样支持搜索,可添加多个 |
关键词过滤
| 配置项 | 说明 |
|---|---|
| 白名单 | 只转发包含这些关键词的消息,输入后回车添加 |
| 黑名单 | 过滤掉包含这些关键词的消息 |
过滤优先级
白名单优先于黑名单。同时设置时,消息必须匹配白名单且不匹配黑名单才会被转发。
消息模板
自定义转发消息格式,支持文本查找替换:
查找文本 => 替换文本每行一条规则,只写关键词表示删除该行。
HDHive 自动解锁
| 配置项 | 说明 |
|---|---|
| HDHive 自动解锁 | 开关。监控到 HDHive 链接时自动解锁 |
| 积分上限 | 单次解锁最大积分消耗,超过则跳过(填 0 不限制) |
启用后,监控到频道中的 HDHive 链接会自动解锁并转存。建议配合积分上限使用,防止积分过度消耗。
消息增强
| 配置项 | 说明 |
|---|---|
| 显示来源 | 在转发消息中附带源频道信息 |
| 显示 Bot 搜索 | 附加 Bot 搜索按钮 |
| 自定义搜索 URL | 自定义搜索链接地址 |
| 显示投稿按钮 | 附加投稿按钮 |
| 广告位 1 / 2 | 可配置两条自定义广告按钮(文本 + URL) |
手动转发
每条规则卡片上的「手动转发」按钮支持两种模式:
- 按消息 ID — 输入具体消息 ID 转发
- 按时间范围 — 选择时间段,批量转发该时段内的所有消息
第四部分:频道自动转存
频道转存监控频道中的 115 分享链接、磁力链接和 ed2k 链接,自动提交到 115 网盘。
进入侧边栏 监控 → 监控转存,点击 添加规则:
基本信息
| 配置项 | 说明 |
|---|---|
| 规则名称 | 自定义名称 |
| 启用 | 开关 |
| 源频道 | 要监听的频道,支持搜索,可添加多个 |
115 转存目标
每条规则可绑定 多个 115 账号(多目标转存):
| 配置项 | 说明 |
|---|---|
| 115 配置 | 从已有 115 账号下拉选择 |
| 转存目录 | 115 分享链接的转存目标目录 |
| 离线目录 | magnet/ed2k 的离线下载目录 |
每个 115 目标可独立配置转存目录和离线目录,便于分类管理。
关键词过滤
与监控转发相同的白名单/黑名单过滤机制。
智能去重
当手动转发消息且源频道→目标频道链路同时匹配监控转发和监控转存规则时,系统自动跳过转发步骤,直接执行转存,避免同一链接被重复处理。
第五部分:Bot 定时任务
Bot 定时任务可在指定时间通过 Bot 自动发送指令到群组/频道/Bot,支持 Cron 表达式灵活调度。
任务管理
进入 插件库 → Telegram 签到(对应路由 /plugin-store/telegram-signin),或直接访问 /bot-tasks:
| 配置项 | 说明 |
|---|---|
| 任务名称 | 自定义名称 |
| 启用 | 开关 |
| 目标 Chat ID | 目标群组/频道/Bot,频道 ID 通常为负数 |
| 签到指令 | 要发送的消息(如 /sign、签到、打卡 等任意文本) |
| 执行时间 | 支持 Cron 表达式和随机间隔两种模式 |
执行模式
| 模式 | 说明 |
|---|---|
| Cron 定时 | 按 Cron 表达式在精确时间执行 |
| 随机间隔 | 在指定的时间范围内随机执行,更贴近人类行为 |
执行日志
每个任务可查看执行历史:成功/失败状态、执行时间、返回结果。支持批量清除历史记录。
定时任务依赖 MTProto Session 发送消息,确保 Session 状态正常。请遵守目标群组规则,避免因自动化操作被封禁。
获取 Chat ID
- 将 Bot 拉入群组,使用
/id命令获取 - 使用 @userinfobot 转发消息获取
- 频道 ID 通常为负数(如
-1001234567890)
第六部分:使用统计
进入侧边栏 监控 → 使用统计,查看 Bot 使用情况的聚合数据:
- 汇总卡片:可切换日报/周报视角,展示解锁成功次数、搜索次数、受限次数、活跃用户数
- Top 用户排行:按解锁成功次数排序
- 趋势图表:7 天面积趋势图(解锁成功、搜索次数、受限次数)
- 明细记录表:按时间、用户、操作类型筛选,支持关键词搜索和分页
典型工作流
将以上功能串联,构建完整的自动化链路:
用户搜索 HDHive → Bot 通知群组有新资源
↓
频道消息 → MTProto Session 监听 → 关键词过滤
↓ ↓
监控转发(转发到内部频道) 监控转存(自动存到 115)
↓
Bot 发送转存成功/失败通知 → 用户在 Emby 中直接播放功能关联
| 功能 | 关联文档 |
|---|---|
| Bot 搜索影视 | HDHive 搜刮 |
| 链接转存到 115 | 115 云盘配置 |
| Emby 播放 | Emby 302 直链播放 |

