Telegram-云讯通消息转发部署文档

本文档从零开始手把手教你把 Telegram Bot 接入云讯通，实现Telegram 群消息（含图片/文件/视频/音频）自动转发到云讯通群

0. 前置准备清单

项	值	来源
Telegram 账号	常规可用账号	手机号注册，可正常创建 Bot 即可
云讯通服务器域名	`https://dev.ysykj.icu`	项目运维提供
服务器环境要求	境外服务器（香港/新加坡/日本/美国等）	自行部署配置
网络权限	支持外网公网访问	服务器开放外网端口，允许外网请求

1. 在 BotFather 创建 Telegram Bot

1.1 操作步骤

1. 打开 Telegram，搜索官方认证机器人 @BotFather（带蓝色官方认证勾）；

2. 发送指令：/newbot，启动新建机器人流程；

3. 根据系统提示，填写 Bot 对外显示名称（自定义，例如：云讯通消息转发）；

4. 填写 Bot 用户名（全局唯一，必须以 bot 结尾，示例：YunxuntongMsgBot）；

5. 创建成功后，BotFather 会返回核心信息，包含：

Bot Token：格式示例 1234567890:ABCdefGhIjKlMnOpQrStUvWxYz0123456789（对接核心凭证）；
机器人专属 t.me 访问链接。

1.2 核心信息留存对照表

字段	示例	云讯通 App 对应位置
Bot Token	`1234567890:ABCdefGhIjKlMnOpQrStUvWxYz0123456789`	机器人配置 - Bot Token 输入框

2. 配置 Bot 权限（必填，缺一不可）

所有权限配置均在 @BotFather 内操作，选中已创建的 Bot 逐一配置。

2.1 开启机器人入群权限

发送指令 /setjoingroups → 选择目标 Bot → 回复 Enable，允许机器人加入群组。

2.2 关闭隐私模式（核心关键）

发送指令 /setprivacy → 选择目标 Bot → 回复 Disable。

重要说明：Bot 默认隐私模式为开启（Enabled），仅能接收斜杠命令、@机器人、回复机器人的消息。必须关闭隐私模式，机器人才能捕获群组内所有普通消息、媒体消息。

2.3 权限最终校验

在 BotFather 发送/mybots → 选中目标 Bot → 进入「Bot Settings」，核对状态必须如下：

配置项	标准正确值
Groups（群组权限）	✅ Enabled（可加入群组）
Group Privacy（群组隐私）	❌ Disabled（隐私模式关闭）

3. 云讯通 App 创建 Telegram 机器人

1. 打开云讯通 App → 底部导航栏【消息】→ 右上角【+】→ 选择【添加机器人】；

2. 机器人类型选择：Telegram 机器人；

3. 按表单填写对应信息：

表单字段	填写规范
机器人名称	自定义（示例：纸飞机消息转发、Telegram消息同步）
Bot Token	粘贴第1步从BotFather获取的完整Token，不可遗漏、错字符

4. 点击【完成】提交配置。

系统将自动执行三项校验操作：

调用 Telegram getMe API，校验 Token 有效性；
弹出权限检测弹窗，校验Token、入群权限、消息接收权限；
保存机器人配置，跳转创建成功页面。

特殊兼容说明：全新未入群的Bot，Telegram接口会出现缓存延迟，导致 can_join_groups、can_receive_all_messages 显示为false。云讯通已适配该问题，对应项显示问号为正常现象，只要手动确认权限配置无误，直接点击【我已确认，继续保存】即可。

4. 设置 Webhook（核心部署步骤）

机器人创建成功后，页面会自动生成专属 Webhook 配置链接，用于绑定消息回调地址。

4.1 Webhook 标准链接格式

https://api.telegram.org/bot<你的BotToken>/setWebhook?url=https://dev.ysykj.icu/api/im-robot-telegram-event.php?token=<随机WebhookToken>

4.2 激活 Webhook

将完整链接复制到浏览器地址栏，直接回车访问。

配置成功返回参数：

提示

{ "ok": true, "result": true, "description": "Webhook was set" }

4.3 失败排查要点

核对 Bot Token 是否完整、无字符错误；
确认服务器支持外网访问、无防火墙拦截；
确认服务器为境外节点或已配置反向代理。

📷 截图位置：浏览器访问Webhook链接、返回成功JSON界面

4.4 校验 Webhook 配置状态

浏览器访问以下链接，查看回调地址是否配置生效：

https://api.telegram.org/bot<你的BotToken>/getWebhookInfo

页面正常展示 url、has_custom_certificate 等字段，即为配置成功。

5. 将机器人加入 Telegram 群组

方式一：客户端直接添加（推荐）

1. 打开需要同步消息的 Telegram 群组（普通群、超级群均支持）；

2. 进入群设置 → 添加成员 → 搜索本机 Bot 用户名；

3. 完成添加，仅需普通成员权限，无需管理员权限。

方式二：链接邀请添加

复制 BotFather 提供的 Bot t.me 链接，点击【Add to Group】，选择目标群组完成添加。、

6. 功能测试与效果验证

6.1 后端日志调试（精准排查）

服务器执行以下命令，实时查看消息回调日志：

tail -f /www/wwwroot/dev.ysykj.icu/storage/telegram_event.log

正常日志标识说明：

REQUEST: method=POST：成功接收外网回调请求；
INCOMING: body_len=xxx update_id=xxx：成功解析消息数据；
SKIP: chat_type=private：正常跳过私聊消息（仅同步群消息）；
MSG_TYPE: photo/video/voice/file：识别对应媒体消息类型；
MEDIA_OK：媒体文件下载保存成功；
OK: dispatched：消息成功转发至云讯通。

6.2 初始化成功提示

机器人首次入群、首次接收群消息时，会自动在 Telegram 群发送欢迎提示，代表配置完全生效：

提示

🎉 云讯通 Telegram 机器人配置成功！本群消息将自动转发到云讯通

6.3 全类型消息测试用例

序号	消息类型	测试操作	预期效果
1	纯文本消息	发送测试文字	云讯通同步展示文本、发送者、时间、群组信息
2	图片消息	发送实拍图片	云讯通展示图片气泡，支持点开查看
3	视频消息	发送短视频	云讯通展示带封面视频气泡，比例正常
4	语音消息	发送TG语音	服务端自动转码MP3，云讯通可正常播放
5	文件消息	发送zip/doc/pdf文件	云讯通展示文件气泡，支持下载
6	贴纸消息	发送TG贴纸	云讯通自动转为图片气泡展示

6.4 转发消息标准格式

文本消息展示格式：

所属平台：Telegram

Bot标识ID：@YunxuntongMsgBot

群组会话ID：-1001234567890

群名：某某交流群

消息发送方：@张三李四

消息时间：2026-08-12 22:15:30

消息正文：测试消息内容

媒体消息展示格式：优先展示媒体气泡，附带对应文字说明，标注消息类型、来源信息。

7. 常见问题排查手册

7.1 Token 异常问题

故障现象	排查方案
保存提示Token无效	完整复制Token首尾字符，杜绝遗漏、多空格、复制不全
getMe返回401 Unauthorized	Token失效或错误，返回BotFather重新获取新Token替换配置

7.2 群消息无法同步问题

故障现象	排查方案
日志无任何新增记录	重新执行第4步Webhook绑定，确认回调地址配置成功
日志显示SKIP: chat_type=private	当前为私聊消息，系统默认跳过，需在群组内测试消息
日志提示token mismatch	数据库im_robots表未适配telegram类型，执行附录C数据库语句修复
有媒体日志但云讯通无展示	程序版本过低，升级 `im-robot-telegram-event.php` 核心文件
消息重复多次接收	Telegram Webhook自动重试机制，后端可配置update_id去重优化

7.3 媒体文件异常问题

故障现象	排查方案
视频无封面、显示异常	升级核心程序文件，补充视频宽高、封面字段获取逻辑
语音无法播放	安装ffmpeg转码工具，赋予程序目录执行权限，解除open_basedir限制
图片下载失败、0字节	检测服务器是否可正常访问api.telegram.org，排查网络代理、防火墙拦截

7.4 权限检测红叉问题

故障现象	排查方案
可加入群组显示异常	重新执行`/setjoingroups`开启权限，接口存在缓存延迟，入群一次后自动恢复
可接收所有消息显示异常	确认`/setprivacy`已关闭，缓存延迟无需处理，手动确认即可保存

7.5 机器人头像异常

故障现象	排查方案
默认灰色方块头像	上传 `static/icons/robot-telegram.svg` 官方图标文件
显示旧版头像	覆盖新版图标文件，或删除旧机器人重新创建

附录 A：Telegram 核心 URL 速查

功能用途	URL地址
BotFather入口	`https://t.me/BotFather`
Token有效性校验(getMe)	`https://api.telegram.org/bot<Token>/getMe`
Webhook绑定接口	`https://api.telegram.org/bot<Token>/setWebhook?url=<Callback>`
Webhook状态查询	`https://api.telegram.org/bot<Token>/getWebhookInfo`
官方API文档	`https://core.telegram.org/bots/api`

附录 B：云讯通后端核心文件说明

文件路径	核心作用
`backend/api/im-robot-telegram-event.php`	Webhook回调入口，负责校验请求、下载媒体、消息转发分发
`backend/im-robots.php`	机器人新增、校验、Webhook配置管理逻辑
`backend/im.php`	消息分发核心函数，统一推送消息至云讯通
`backend/storage/telegram_event.log`	Telegram消息对接全程调试日志
`backend/database/schema.sql`	数据库表结构，包含机器人类型配置
`static/icons/robot-telegram.svg`	Telegram机器人默认展示图标

附录 C：配置参数映射表

Telegram配置字段	云讯通App字段	数据库存储字段
Bot Token	Bot Token输入框	external_config.bot_token（加密存储）
Bot Username	自动获取无需手动填写	external_config.bot_username
Webhook回调地址	后端自动拼接生成	external_config.webhook_token（64位随机密钥）

欢迎回来

功能已关闭

个人中心

修改密码