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

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

0. 你需要提前准备好的东西

项	值	来源
飞书企业管理员账号	——	需要有权限创建企业自建应用
云讯通服务器域名	https://dev.ysykj.icu/	项目运维
服务器可外网访问	✅	飞书回调需要 POST 到你的域名

1. 创建飞书企业自建应用

操作步骤

1. 打开飞书开放平台：点击此处

2. 登录你的飞书企业管理员账号

3. 点击 「创建企业自建应用」

4. 填写应用名称（比如"云讯通消息机器人"）、应用描述、上传头像

5. 创建完成后进入应用详情页，在左侧菜单找到 「凭证与基础信息」

记录下这两个值（后面要用）

字段	示例	在云讯通后台对应
App ID	`cli_aaf305db29781bb6`	`feishu_app_id`
App Secret	`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`	`feishu_app_secret`

2. 配置应用权限（⚠️ 必须全部申请）

左侧菜单 → 「权限管理」

方法一：一键 JSON 导入（推荐 ⭐）

飞书开放平台支持通过 JSON 批量导入权限，不用一个个手动搜。

1. 在「权限管理」页面找到 「导入权限」按钮（通常在右上角或批量操作区域）

2. 复制下面这段 JSON，粘贴进去：

{ "

scopes": { "tenant": [ "admin:app.info:readonly", "contact:contact.base:readonly", "contact:user.base:readonly", "im:chat:readonly", "im:message.group_msg.include_bot:read", "im:message:readonly", "im:message:send_as_bot" ], "user": [] } }

3. 点击确认导入，系统会自动勾选所有这些权限

方法二：手动逐个搜索申请

如果不想用 JSON 导入，就手动搜这几个权限：

#	权限标识	说明
1	`im:message.group_msg.include_bot:read`	读群消息
2	`im:message:readonly`	下载用户发的图片/文件/视频/音频
3	`contact:contact.base:readonly`	取消息发送者姓名和头像
4	`contact:user.base:readonly`	获取用户详细信息（额外需要）
5	`im:chat:readonly`	读取群聊信息（额外需要）
6	`im:message:send_as_bot`	以机器人身份发消息（额外需要）
7	`admin:app.info:readonly`	读取应用基础信息（额外需要）

🚨 踩坑提醒：权限 1 和权限 2 是两个独立权限！之前以为"读群消息"就包含了下载媒体，结果飞书返回 99991672 permission denied。必须分开申请。

填写申请理由（简单写："用于将飞书群消息转发到自建 IM 系统"）

权限有效期选"永久"

提交

全部申请完后，状态应该是「已开通」或者「审批中」。如果是审批中，需要企业管理员在飞书管理后台审批通过。

3. 配置事件订阅（核心步骤）

左侧菜单 → 「事件与回调」→「事件订阅」

3.1 配置请求地址

请求地址填：自定义云讯通域名/api/im-robot-feishu-event.php

这个地址就是云讯通后端的飞书事件回调入口，会自动处理 URL 验证、签名校验、消息解密。

点击保存后，飞书会向这个地址发一个 type=url_verification 的 POST 请求进行验证。云讯通后端会自动返回正确的 challenge，验证应该秒过。

3.2 配置 Encrypt Key（必须）

如果你想让飞书回调消息加密传输：

在云讯通机器人后台生成的Encrypt Key

记录下来，后面要填到飞书加密策略后台

后端用 AES-256-CBC + SHA256(key) 解密，已内置支持

如果不配 Encrypt Key，回调以明文发送，不能用

配置	值	说明
Encrypt Key	云讯通机器人后台生成的Encrypt Key	填入飞书加密策略后台
Verification Token	（不用管）	云讯通后端用签名校验，不用这个

3.3 订阅事件

在「事件列表」区域，点击「添加事件」，搜索并添加：

事件	事件标识	说明
接收消息	`im.message.receive_v1`	只需要这一个，覆盖文本/图片/文件/视频/音频

4. 配置机器人信息

左侧菜单 → 「应用功能」→「机器人」

1. 开启机器人能力的开关

2. 设置机器人名称（用户在群里看到的显示名）

3. 上传机器人头像（会显示在云讯通消息气泡旁边）

5. 发布应用版本（⚠️ 必须做！权限/事件变更后都要发版）

左侧菜单 → 「版本管理与发布」

1. 点击「创建版本」

2. 填写版本号（如 1.0.0）和更新说明

3. 点击「申请发布」

4. 如果是企业自建应用，可能需要管理员审批

🚨 踩坑提醒：每次修改权限、事件订阅、机器人设置后，必须发版才能生效！之前改了权限没发版，结果调了半天还是权限报错。

6. 在云讯通后台创建飞书机器人

1. 左侧菜单 → 「机器人管理」

2. 点击「添加机器人」

3. 填写：

字段	填什么
机器人名称	随便起，如"飞书消息转发"
集成类型	feishu
飞书 App ID	第 1 步拿到的（如 `cli_aaf305db29781bb6`）
飞书 App Secret	第 1 步拿到的
飞书 Encrypt Key	第 3.2 步生成的（如果没配就留空）

4. 点击「测试连接」—— 系统会调用飞书 API 验证 App ID/Secret 是否正确

- ✅ 成功：显示「连接成功」

- ❌ 失败：检查 App ID / Secret 是否复制错，或者飞书权限是否已开通并发版

5. 保存

7. 将机器人拉入飞书群

方法一：飞书 App 里直接加

1. 打开你要转发的飞书群

2. 群设置 → 群机器人 → 添加机器人

3. 搜索你刚创建的应用名称 → 添加

8. 验证：发消息测试

8.1 先看后端日志

服务器上查看飞书事件回调日志（调试用）：

每收到一条事件，日志会追加一行，包含：

INCOMING: encrypted=yes/no — 加密状态

MSG_TYPE: text/image/file/video/audio — 消息类型

CHAT: chat_id=xxx chat_type=group — 群信息

MEDIA_DOWNLOAD / MEDIA_OK / MEDIA_PARSE — 媒体下载状态

8.2 逐类测试

在飞书群里发以下消息，每条都检查云讯通是否收到：

顺序	测试类型	操作	预期结果
1	纯文本	`@机器人你好`	云讯通收到文本消息，带发送者名字
2	图片	发一张照片	云讯通收到图片气泡，可点开查看
3	语音	发一段语音	云讯通收到音频气泡，文件名正确
4	文件 (doc/docx/pdf)	发一个 Word 文档	云讯通收到文件气泡，可点击在线预览
5	视频	发一段视频	云讯通收到视频气泡，按原始比例显示，有封面图

8.3 消息格式

转发到云讯通的消息会包含：

所属平台：飞书 Bot标识ID：cli_aaf305db29781bb6 群组会话ID：oc_xxx（飞书群 chat_id）群名：群成员列表拼合消息发送方：张三（飞书用户昵称）消息正文：[图片] / [视频] / [文件] / 实际文本内容

9. 常见问题排查

消息没转发

现象	排查步骤
feishu_event.log 完全没追加	飞书事件回调 URL 配置错了？服务器 443 端口开了吗？
日志显示 `CHAT: chat_type=p2p`	机器人只转发群消息，私聊不转发。把机器人拉进群里测试
日志显示 `MEDIA_DOWNLOAD FAIL 234001`	用错了下载接口，飞书用户发送的图片不能用 `/im/v1/images/{key}` → 必须用 `/im/v1/messages/{msg_id}/resources/{key}?type=image`
日志显示 `MEDIA_DOWNLOAD FAIL 99991672`	缺少 `im:message:readonly` 权限，去飞书开放平台申请，然后发版
日志显示空消息	检查机器人是否已拉入对应飞书群
同一条消息重复收到多条	飞书事件有重试机制，后端已用 `event_id` + `INSERT IGNORE` 去重。如果还重复，检查数据库去重表是否正常

文件预览/下载问题

现象	排查步骤
文件传过来了但点不开	检查 im-image.php 白名单是否包含该文件扩展名
视频转圈放不动	Nginx storage 块加 `Accept-Ranges bytes`，im-image.php 处理 Range 请求返回 206
视频没有封面	后端 `imagecreatefromwebp` 崩溃？确认 PHP 是 8.2 且 GD 扩展已装
文件保存后手机文件管理器搜不到	0 字节文件系统不显示 → 查 App 日志 `_size` 是否为 0（transferTo 可能没写成功）

附录 A：飞书开放平台关键 URL 速查

用途	URL
开放平台首页	https://open.feishu.cn/app
创建企业自建应用	https://open.feishu.cn/app/new
消息下载 API 文档	https://open.feishu.cn/document/server-docs/im-v1/message-resource/get
`im.message.receive_v1` 事件文档	https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTMukTM/reference/im-v1/message/events/receive

附录 B：云讯通后端关键文件

文件	作用
`backend/api/im-robot-feishu-event.php`	飞书事件回调入口（URL 验证 + 消息解密 + 转发）
`backend/api/im-robot-feishu-check.php`	测试飞书 App ID/Secret 是否有效
`backend/im-robots.php`	机器人管理逻辑（创建/更新/删除/飞书凭据校验）
`backend/im.php`	消息分发核心函数 `im_robot_dispatch_message()`
`backend/storage/feishu_event.log`	飞书事件调试日志

附录 C：配置参数对照表

飞书开放平台字段	云讯通后台字段	数据库列	当前值
App ID	feishu_app_id	config_json.app_id	`cli_aaf305db29781bb6`
App Secret	feishu_app_secret	config_json.app_secret	（加密存储）
Encrypt Key	feishu_encrypt_key	config_json.encrypt_key	（可选）
事件回调 URL	——	——	自定义云讯通域名 + 对应接口路径
事件类型	——	——	`im.message.receive_v1`

欢迎回来

功能已关闭

个人中心

修改密码