云客服在线客服支持飞书渠道接入，员工即可在飞书单聊或群聊中向客服应用发送消息，座席可在云客服工作台中统一接待。
一、接入准备
- 操作者为当前飞书企业的管理员，或拥有「应用管理」权限。
- 已登录 飞书开放平台。
- 已登录云客服管理后台，并进入「渠道管理 - 飞书渠道」页面
二、飞书-创建企业自建应用
进入飞书开放平台，点击右上角【开发者后台】
选择【创建企业自建应用】
填写应用名称、应用描述，选择应用图标，然后点击【创建】
三、飞书-添加机器人应用能力
- 进入应用详情，点击【添加应用能力】
- 在机器人卡片中，点击【添加】即可
3. 进入机器人详情界面编辑信息（可选）
编辑机器人配置-【如何开始使用】，该内容会在机器人应用卡片对用户显示。
四、飞书-开通权限
- 进入权限管理页面，点击左侧菜单【权限管理】-【开通权限】。
- 在搜索框中输入权限名称或者权限标识，逐一添加下表中所列权限。（建议直接搜索权限标识）
| 权限名称 | 权限标识 | 用途 |
| 获取用户基本信息 | contact:user.base:readonly | 获取发送消息用户的名称、头像等基础信息 |
| 获取用户组织架构信息 | contact:contact.base:readonly | 获取用户所属部门，用于企业组织架构展示 |
| 获取用户 user ID | contact:user.employee_id:readonly | 获取员工工号，便于与企业内部系统关联 |
| 获取与更新群组信息 | im:chat | 获取群聊基本信息，用于识别消息来源群 |
| 获取与发送单聊、群组消息 | im:message | 允许应用通过机器人向用户或群聊发送消息 |
| 获取群组中用户@机器人消息 | im:message.group_at_msg:readonly | 接收用户在群聊中 @ 机器人的消息事件 |
| 读取用户发给机器人的单聊消息 | im:message.p2p_msg:readonly | 接收用户与机器人私聊的消息事件 |
| 获取与上传图片或文件资源 | im:resource | 下载用户发送的图片、文件等3. |
| 获取群组中所有消息（敏感权限） | im:message.group_msg | 接收机器人所在群聊中所有的消息事件 |
3. 申请敏感权限
部分权限（如读取群聊 @ 消息、读取单聊消息）属于敏感权限。如果开通后需要提交使用说明，可按以下方式填写：
- 使用场景：本应用用于企业客服场景，需要接收用户在群聊或私聊中发送的咨询消息，并转发至云客服系统。
- 数据用途：仅用于消息展示、客服回复、会话记录存储，不会用于其他商业用途或外泄。
提交后通常需要等待飞书审核，审核通过后权限方可生效。
五、云客服-添加飞书渠道应用并获取回调地址
- 登录云客服设置后台，进入【渠道管理 】-【飞书渠道】。
- 点击【添加飞书应用】，填写所需的【App ID】、【App Secret】、【Encrypt Key】、【Verification Token】4项参数。
- 这四项参数可在飞书开放平台【凭证与基础信息】和【事件与回调】-【加密策略】处获取
Encrypt Key默认未开启，需点击“重置”来获取。
4. 填写好相关信息，点击【保存并校验】，系统会生成一个回调地址，复制该回调地址。
六、飞书-配置回调地址
页面一：事件与回调 → 事件配置地址
- 进入飞书开放平台，点击应用详情页左侧菜单「事件与回调」。
- 选择「事件配置」子菜单，订阅方式选择「将事件发送只开发者服务器」。
- 找到「请求地址」，将云客服系统生成的回调地址粘贴到「请求地址 URL」输入框中。
- 点击「保存」。
页面二：事件与回调 → 回调配置
- 在同一「事件与回调」菜单下，选择「回调配置」子菜单，订阅方式选择「将回调发送至开发者服务器」。
- 找到「请求地址」，将同样的回调地址粘贴到「请求地址 URL」输入框中。
- 点击「保存」。
注意：两个页面都需要填写，漏填任何一个都会导致消息无法正常推送。
七、飞书-订阅消息事件
- 在【事件与回调】 - 【事件配置】页面，点击【添加事件】。
- 搜索 im.message.receive_v1，勾选后保存。
八、飞书-发布应用
- 进入飞书开放平台，点击应用详情页左侧菜单【版本管理与发布】。
- 点击【创建版本】。
- 填写版本号（例如 1.0.0）、版本说明
- 设置可用性范围：
全部员工：企业内所有员工可见。
部分员工：指定部门或成员可见
5. 提交审核，审核通过后上线
九、云客服-触发方式和高级配置
1. 支持选择触发方式：
| 触发方式 | 适用场景 | 说明 |
| @触发 | 用户主动 @ 机器人时才创建会话 | 适合希望减少干扰、仅在用户明确求助时接入客服的场景 |
| 全部消息触发 | 群内所有消息均触发会话 | 适合需要全群消息自动接管、自动分配客服的场景 |
2. 支持进行高级设置：
| 配置项 | 适用触发方式 | 说明 |
| 视为私聊 | 全部 | 开启后，群聊消息以客户维度创建会话，便于一对一跟进 |
| 免@有效期 | 仅 @触发 | 用户 @ 应用后，N 分钟内发送的非 @ 消息继续归该应用处理 |
十、验证接入是否成功
发布上线后，建议按以下步骤验证：
（一）单聊验证
- 在飞书客户端中搜索并打开该客服应用。
- 发送一条测试消息，例如「你好」。
- 在云客服工作台中查看是否出现新的会话。
- 由座席回复一条消息，确认用户能在飞书中收到。
在飞书中搜索所添加的应用名称
（二）群聊验证
- 将客服应用对应的机器人拉入一个测试群。
- 在群中 @ 该应用 发送一条消息，例如「@客服助手 测试咨询」。
- 在云客服工作台中查看是否出现新的会话（会话列表统一展示，来源标识包含群名称）。
- 由座席回复一条消息，确认回复内容在群中正常展示。
（三）常见问题排查
| 现象 | 可能原因 | 解决方法 |
| 飞书侧发送消息后，云客服未收到 | 回调地址未正确填写或事件未订阅 | 检查「事件与回调」两个页面的请求地址是否一致，并确认已订阅 im.message.receive_v1 |
| 云客服回复后，用户未收到 | 应用未上线或被移出群聊 | 检查应用发布状态；检查机器人是否在目标群中 |
| 群聊中 @ 机器人无响应 | 未开通读取群聊 @ 消息权限 | 在权限管理中申请 im:message.group_at_msg:readonly 并通过审核 |
| 提示应用授权异常 | App Secret 或凭证失效 | 在云客服中重新填写应用凭证，并确认飞书侧应用状态正常 |
十一、注意事项
- 一个群聊中可添加多个客服应用：若群内存在多个应用，系统会按规则自动选择其中一个处理消息，避免重复创建会话。该过程由系统自动完成，无需额外配置。
- 触发方式配置需与业务匹配：@触发更适合控制会话量；全部消息触发适合全群自动接管。
- 敏感权限需提前申请：涉及消息读取的权限可能需要飞书审核，请预留审核时间。
- 凭证变更后需同步更新：若在飞书开放平台重置了 App Secret 或 Encrypt Key，请及时在云客服系统中更新，否则会导致消息接收或回复失败。