IM 应用¶
IM 应用用于接入飞书，为故障作战室提供创建群聊、邀请成员、同步故障信息和响应卡片操作等能力。
拥有工作空间管理或集成管理权限的成员，可进入集成 > IM 应用查看和管理已接入的应用。应用列表展示应用信息和连接状态，支持按应用名称搜索；点击应用可进入详情。
接入应用¶
进入集成 > IM 应用，点击接入应用并选择飞书，然后按照页面提示填写凭证并完成飞书开放平台配置。
接入飞书¶
1. 创建飞书应用¶
- 登录飞书开放平台，创建一个企业自建应用；
- 在应用能力中添加机器人能力。
2. 填写应用参数¶
进入集成 > IM 应用，点击接入应用并选择飞书。填写应用名称及以下参数：
| 字段 | 是否必填 | 说明 |
|---|---|---|
App ID |
是 | 飞书应用的唯一标识 |
App Secret |
是 | 用于获取应用访问凭证；加密保存且不回显 |
Verification Token |
是 | 用于校验事件及卡片回调是否来自当前应用 |
Encrypt Key |
否 | 启用飞书回调加密时用于解密请求 |
各参数在飞书开放平台中的获取位置如下：
App ID、App Secret：进入开发者后台 > 选择应用 > 基础信息 > 凭证与基础信息；Verification Token：进入开发者后台 > 选择应用 > 开发配置 > 事件与回调 > 加密策略，复制系统显示的 Verification Token；Encrypt Key：同样在加密策略页获取。未启用回调加密时，该项显示为未开启，接入页面中留空即可；如需启用，请点击重置或自定义编辑生成或设置 Encrypt Key，并确保两端填写完全一致。
App ID、App Secret 校验成功后即可进入下一步；Verification Token 和 Encrypt Key 将在飞书发起回调时进行校验。
3. 开通应用权限¶
在飞书开放平台的权限管理中，为应用开通以下权限：
| 权限 | 用途 |
|---|---|
im:chat |
创建、管理和解散作战室群聊，邀请成员并生成群分享链接 |
im:message |
发送和更新故障卡片 |
contact:user.id:readonly |
通过邮箱或手机号匹配飞书用户，用于自动邀请成员 |
配置通讯录数据范围¶
contact:user.id:readonly 开通后，还需要配置该权限可访问的通讯录数据范围：
- 在权限管理中找到
contact:user.id:readonly，点击可访问的数据范围 > 配置； - 在通讯录中选择全部成员，或指定允许访问的部门和成员；
- 确保数据范围包含所有可能被邀请进入作战室的成员。
通讯录数据范围必须覆盖被邀请成员
系统只能获取授权范围内的飞书用户信息。成员不在 contact:user.id:readonly 的通讯录数据范围内时，系统无法通过邮箱或手机号找到该成员，创建作战室群聊时将无法邀请该成员。
4. 配置事件与回调¶
凭证校验成功后，接入页面第三步会生成以下两个地址：
| 回调地址 | 飞书配置位置 | 用途 |
|---|---|---|
| 事件订阅请求 URL | 事件配置 | 接收群被解散、机器人被移出群等事件 |
| 卡片回调 URL | 回调配置 | 接收故障卡片中的认领、关闭等操作 |
进入飞书开放平台的开发配置 > 事件与回调，分别配置事件订阅和卡片回调。
配置事件订阅¶
- 在事件配置中选择将事件发送至开发者服务器，填写接入页面生成的事件订阅请求 URL；
- 添加以下事件：
- 群被解散：
im.chat.disbanded_v1 - 机器人被移出群：
im.chat.member.bot.deleted_v1
- 群被解散：
配置卡片回调¶
- 在回调配置中选择将回调发送至开发者服务器，填写接入页面生成的卡片回调 URL；
- 添加卡片回调：
card.action.trigger。
回调可以稍后配置：未配置回调不影响应用显示为已连接和创建群聊，但群解散状态同步、机器人被移出群识别及卡片交互暂不可用。
5. 发布应用¶
- 进入飞书开放平台的应用发布 > 版本管理与发布，点击创建版本；
- 配置应用的可用范围，选择全部成员，或指定允许使用该应用的部门和成员；
- 确保可用范围包含可能创建作战室、作为故障处理人或被邀请进入作战室的成员；
- 提交并完成应用发布。
应用可用范围必须覆盖作战室成员
成员不在应用可用范围内时，无法正常使用该应用，创建群聊或邀请成员可能失败。若选择部分成员或部门，请在人员范围发生变化后及时更新并重新发布应用。
6. 完成接入¶
完成应用凭证校验后，即可完成接入，应用状态显示为已连接。进入应用详情的回调配置，可继续查看回调状态或复制回调地址。
查看和管理应用¶
点击应用行进入详情，可查看基本信息、连接状态、作战室能力和操作记录。
- 应用详情提供回调配置，用于查看并复制事件订阅请求 URL 和卡片回调 URL；
- 应用名称、App ID、App Secret、Verification Token 等均可以修改；
- 可以在详情页中选择删除不需要的应用。
飞书的事件订阅请求 URL 和卡片回调 URL 仅拥有 IM 应用管理权限的工作空间管理员可以查看和复制。查看、复制、配置变更及应用删除等操作均会写入审计记录。
删除应用前需要二次确认。删除后配置不可恢复，也不能再用于创建新的作战室；已经创建的外部群聊和访问记录不受影响。
连接状态¶
| 状态 | 说明 |
|---|---|
| 待验证 | 应用凭证尚未通过校验，不能用于创建作战室 |
| 已连接 | 凭证与基础能力校验成功，可以用于创建作战室 |
| 连接异常 | 凭证失效、权限不足或企业侧应用不可用，不能创建新的作战室 |
飞书应用还会独立显示回调配置状态：
| 状态 | 说明 |
|---|---|
| 待配置 | 尚未收到通过校验的事件或卡片回调；仍可创建群聊，但回调相关能力暂不可用 |
| 正常 | 已收到并通过来源校验的事件或卡片回调 |
| 异常 | 回调持续不可达，或验签、解密失败；请检查飞书平台和应用详情中的回调配置 |
应用连接异常时，请根据页面提示检查凭证、应用权限和应用可用范围。已有作战室的外部群聊不会因此被自动关闭。
常见问题¶
为什么应用无法完成接入？¶
请按照页面提示检查以下配置：
- 应用凭证是否正确；
- 飞书应用是否已经添加机器人能力并发布应用版本；
- 飞书权限、通讯录数据权限和应用可用范围是否配置完整；
- 飞书事件订阅请求 URL、卡片回调 URL 和对应订阅项是否配置完整；
Verification Token是否与飞书应用一致；启用回调加密时，Encrypt Key是否一致。
为什么已接入的应用不能创建作战室？¶
只有状态为已连接的应用可以创建作战室。请进入应用详情查看连接状态和操作记录，并根据异常提示修复配置。
更换 Secret 后需要重新配置平台权限吗？¶
如果 App ID 和应用本身没有变化，仅更换 App Secret 通常不需要重新开通平台权限或事件订阅。保存新 App Secret 后，请确认应用恢复为已连接状态。
为什么飞书应用已连接，但卡片操作或群状态没有同步？¶
请进入应用详情查看回调配置状态：
- 状态为待配置：请将事件订阅请求 URL 和卡片回调 URL 配置到飞书开放平台，并添加所需事件和卡片回调；
- 状态为异常：请检查回调地址、
Verification Token，以及启用回调加密时使用的Encrypt Key。
回调恢复正常前，仍可创建和进入飞书群聊，但系统无法及时识别群被解散、机器人被移出群，也无法处理群内故障卡片操作。
更多阅读¶
您可能对以下内容感兴趣：