TG机器人（TelegramNotice）使用文档

作者：kuakeba.cn | 版本：1.0.0 | 适用于 Zsens Admin 3.0+（PHP 8.2+，需 curl 扩展）

一、插件简介

通过 Telegram 机器人推送站点评论通知，并提供后台文章手动推送能力：

• 评论通知推送：站点新评论以 HTML 模板推送到 Telegram（主题、评论者、内容、状态、时间）
• 多 Chat ID 群发：通知目标支持逗号 / 换行分隔多个 Chat ID，逐个送达
• 邮箱 → Chat ID 绑定：用户在 /tgn/bind 页获取绑定码，向机器人发送 /bind 绑定码 完成绑定；绑定后评论被回复时定向推送，且对方可在 Telegram 中直接回复通知消息，内容将以绑定用户身份发布回站点
• 内联快捷审核：审核员会话收到的评论通知带「✅ 通过 / 🚫 垃圾 / 🗑 删除」内联按钮，点击即回调执行（通过 / 下架 / 软删除，并同步主题回复计数）
• 后台文章手动推送：文章列表一键推送到频道/群，支持群发或指定目标
• 后台一键检测/配置 Webhook：检测机器人（getMe）、检测 Webhook 状态、一键配置（自动生成密钥）、删除
• 后台版本检查：本地版本对比 kuakeba.cn 插件市场
• 零侵入：不修改任何宿主文件；评论监听采用增量轮询（前台渲染/后台操作/Webhook 触发，15 秒节流，仅一条索引查询），卸载即清理菜单，重装数据表保留

二、环境要求

三、快速开始

1. 向 @BotFather 创建机器人，拿到 Bot Token
2. 将 TelegramNotice 目录放入 plugins/，后台 应用中心 → TG机器人 → 安装（自动建表 + 注册菜单）
3. 到 应用中心 → TG机器人 → 配置：填写 Bot Token、通知目标 Chat ID、审核员 Chat ID，保存
4. 进入后台菜单 TG机器人 → 机器人状态：

  - 点「检测机器人」确认 Token 有效

  - 点「一键配置 Webhook」，看到「配置成功」即可

1. 用任意会话向机器人发一条消息测试；站点发布新评论后，Telegram 中将收到通知

获取自己的 Chat ID：向 @userinfobot 发送任意消息即可查询。

四、配置项说明

后台 应用中心 → TG机器人 → 配置：

五、邮箱绑定与 Telegram 回复评论

1. 登录站点，访问 /tgn/bind，输入邮箱点击「获取绑定码」（15 分钟有效）
2. 在 Telegram 中向机器人发送：/bind 绑定码
3. 绑定成功后：

  - 定向推送：别人的回复指向你的评论时，机器人私聊推送给你

  - Telegram 回复评论：直接回复那条通知消息，输入文字发送，即以你的站点身份发布回复评论（自动 @被回复人，500 字内）

1. 其他命令：/unbind 解除绑定、/help 帮助

绑定关系管理在后台 TG机器人 → 绑定管理：查看全部绑定、手工添加、删除。

匹配规则：优先按绑定时关联的用户 ID，其次按绑定邮箱反查站点用户；未关联站点的邮箱仅可收定向推送，无法代发评论。

六、后台功能

机器人状态：机器人检测 / Webhook 检测·配置·删除 / 检查新评论（手动轮询）/ 版本检查

文章推送：列出最近 20 篇文章，每行「群发推送」按钮 + 可选指定 Chat ID；推送模板含标题、摘要、评论数、时间与全文链接

绑定管理：绑定列表（邮箱、Chat ID、关联用户、时间）、手工添加、删除

七、接口说明

Webhook 处理内容：callback_query（内联审核回调，仅审核员）、message（/bind、/unbind、/help、回复通知消息发布评论）。始终返回 200，避免 Telegram 重试。

八、实现说明（零侵入机制）

• 评论监听：宿主未提供评论插件钩子，插件在 tg_state 表维护「已处理最大回复 ID」游标，借前台 renderAssets（每次页面渲染）/ 后台操作 / Webhook 触发增量拉取（status ∈ {0,1}，单批 20 条，15 秒节流）
• 消息映射：tgmessagemap 记录「通知消息 ↔ 站点评论」，支撑 Telegram 内回复发布站点评论；30 天自动清理
• 审核动作：通过 → status=1；垃圾 → status=0（下架）；删除 → 软删除；可见状态变化时同步主题 reply_count
• 数据表：tgbinding（绑定）、tgmessagemap（映射）、tgstate（运行状态）；卸载不删表，重装免重绑

九、常见问题

Q：一键配置 Webhook 提示失败？

Telegram 要求 HTTPS 与有效证书。检查站点是否可被公网 HTTPS 访问；本地开发环境无法配置，可用 ngrok 等内网穿透后测试（配置页使用当前域名生成地址）。

Q：收不到评论通知？

依次检查：① 插件已启用且配置已保存；② Bot Token 有效（机器人状态页检测）；③ Webhook 已配置（检测 Webhook 看最近错误）；④ 新评论推送到 Telegram 有分钟级延迟（轮询依赖站点访问或后台操作触发，可点「检查新评论」立即推送）。

Q：审核按钮点了没反应？

操作会话必须在「审核员 Chat ID」列表中；确认推送该通知的目标与审核员配置一致。按钮点击后自动消失，防止重复操作。

Q：在 Telegram 回复通知消息没有发布到站点？

需满足：① 该通知是「定向推送」（发给绑定邮箱对应的会话）；② 绑定邮箱已关联站点用户；③ 内容 1～500 字。群发通知（非定向）的回复不会发布。

Q：卸载会删除数据吗？

不会。卸载仅清理后台菜单；绑定关系与运行状态保留，重装后无需重新绑定。