配置飞书应用
在飞书开放平台为 ZAI 所在的自建应用选择接收方式、订阅事件、配置回调与权限，以及新增或更换应用。
ZAI 通过你们企业的一个飞书自建应用接收群和私聊里的消息。应用需要启用机器人能力，再按本页选择接收方式、订阅事件、配置卡片回调并开通权限，然后在开放平台发布新版本；接收方式、事件订阅和权限都在发布后才生效。应用名称就是成员在飞书里看到和 @ 的名字，建议填写 ZAI。
从飞书应用中心安装的商店版 ZAI 不需要本页的配置，见安装商店版 ZAI。
未订阅的事件 ZAI 收不到，对应功能不会生效，也不会报错提示。调整应用配置后，请逐项对照本页核对。
谁来做
本页的操作分在几个人手里。Z Tag 管理员是为你的组织运行和维护 Z Tag 服务的人或团队，不是控制台里的组织角色，见你会看到的词。
| 谁 | 做什么 |
|---|---|
| 开放平台上这个应用的管理员 | 创建自建应用、启用机器人能力，按本页配置接收方式、事件、回调、权限和重定向 URL，创建版本并发布；把下一节的值交给 Z Tag 管理员 |
| 飞书企业管理员 | 在管理后台审核应用版本，设置谁可以使用这个应用，见飞书企业管理员须知 |
| Z Tag 管理员 | 把应用接入本组织并登记它的凭证，提供请求地址与控制台登录用的重定向地址，切换接收方式 |
| 组织 Owner / Admin | 在控制台 组织管理 → IM 接入 查看接入状态，见查看 IM 接入 |
交给 Z Tag 管理员的值
- “凭证与基础信息”里的 App ID 和 App Secret。
- 使用请求地址接收时，“开发配置 → 事件与回调”的“加密策略”页签里的 Verification Token，以及 Encrypt Key（如已配置）。
之后在开放平台重置 App Secret 或“加密策略”里的任一项，都要同时把新值交给 Z Tag 管理员，否则 ZAI 会无法工作，见常见故障。
接收方式
开放平台“开发配置 → 事件与回调”中，“事件配置”和“回调配置”两个页签各有自己的“订阅方式”，两处都要选成 Z Tag 管理员为这个应用登记的接收方式。接收方式只能由 Z Tag 管理员登记和修改，请先向对方确认；组织 Owner / Admin 也可以在控制台 IM 接入 的应用详情里看到，显示为 长连接 或 HTTP 回调。
- 长连接（控制台显示为 长连接）：“事件配置”选“使用长连接接收事件”，“回调配置”选“使用长连接接收回调”。飞书只在应用已有在线长连接时允许保存，所以先把 App ID 和 App Secret 交给 Z Tag 管理员，等对方确认 ZAI 已用这个应用上线后再保存。
- 请求地址（控制台显示为 HTTP 回调）：两个页签分别选“将事件发送至开发者服务器”和“将回调发送至开发者服务器”，都填写 Z Tag 管理员提供的同一个请求地址。保存前，先把“加密策略”里的 Verification Token 和 Encrypt Key 交给 Z Tag 管理员，等对方确认已登记再保存：飞书保存时会立即校验这个地址，Z Tag 管理员登记之前保存会失败，提示 Challenge code 没有返回。地址通过校验后，再添加下文的事件和回调。
从长连接改为请求地址时，先请 Z Tag 管理员把应用切换到请求地址，再同时修改两个页签。只改“事件配置”时，消息能收到，但卡片按钮全部失效。已经改为请求地址的应用要改回长连接时，请先与 Z Tag 管理员商定，等对方把应用改回长连接后，再修改两个页签。
一个飞书应用只能接入一套 Z Tag 服务，也不要与其他接收这个应用事件的服务共用：长连接下会有一部分消息被另一个服务收走；请求地址方式下一个应用只能填一个地址。
常见故障
控制台 IM 接入 的连接状态显示 被平台拒绝 时，状态下方会写明原因，按下表处理。
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 保存长连接时提示应用未建立长连接 | ZAI 还没有用这个应用上线 | 请 Z Tag 管理员确认已登记 App ID 和 App Secret，ZAI 上线后再保存 |
| 保存请求地址时提示 Challenge code 没有返回 | Z Tag 管理员尚未登记这个应用，或登记的 Verification Token、Encrypt Key 与“加密策略”不一致；请求地址填错 | 核对地址，请 Z Tag 管理员确认登记的值后重新保存 |
| 消息有回复，但点击卡片按钮都提示出错 | “回调配置”的订阅方式或请求地址与“事件配置”不一致，或没有添加 card.action.trigger | 按卡片回调核对“回调配置”，修改后发布新版本 |
| 请求地址方式下，所有群和私聊里 ZAI 突然都不回复 | 有人重置了“加密策略”，或改动了“事件配置”的订阅方式或请求地址 | 把新的 Verification Token 或 Encrypt Key 交给 Z Tag 管理员更新，或把订阅方式与地址改回 |
| 长连接方式下，部分消息没有回复且没有规律 | 同一应用还被另一套 Z Tag 服务或其他程序用长连接接收 | 停止其他使用方，或为每套服务单独创建应用 |
| 长连接方式下，所有群和私聊里 ZAI 都不回复；连接状态为 被平台拒绝 · 事件连接被拒绝 | 同一应用的在线长连接已达飞书上限（每个应用 50 个），ZAI 连不上 | 停止其他使用这个应用的程序，再请 Z Tag 管理员确认 ZAI 已重新连接 |
| 连接状态为 被平台拒绝 · 应用已被停用或卸载 | 应用在飞书管理后台被停用 | 请飞书企业管理员在管理后台重新启用应用，并确认机器人能力仍开启 |
| 连接状态为 被平台拒绝 · 应用凭证被拒绝 | 有人在开放平台重置了 App Secret | 把新的 App Secret 交给 Z Tag 管理员更新 |
| 连接状态为 被平台拒绝 或 已连接，下方显示 接口调用额度已用尽 | 飞书企业当月的接口调用额度已经用完；同一企业的所有自建应用共用这份额度 | 升级飞书版本，或等下个月额度恢复；期间后台能力暂停，升级后回复马上恢复，后台能力要提前恢复请联系 Z Tag 管理员 |
恢复后，此前发出的消息可能陆续补答，但时间太久的不会再补答；成员看到的现象和做法见按现象排查问题。
事件订阅
在开放平台“事件与回调 → 事件配置”添加以下事件，订阅方式见接收方式。
| 事件 | 用途 |
|---|---|
接收消息 im.message.receive_v1 | 群和私聊中的消息，用于发起任务和执行命令 |
撤回消息 im.message.recalled_v1 | 用户撤回消息后，取消由它发起、尚未开始的任务 |
机器人进群 im.chat.member.bot.added_v1 | 记录 ZAI 加入的群 |
机器人被移出群 im.chat.member.bot.deleted_v1 | 停止处理 ZAI 已离开的群 |
用户进群 im.chat.member.user.added_v1 | 同步群成员 |
用户出群 im.chat.member.user.deleted_v1 | 同步群成员 |
撤销拉用户进群 im.chat.member.user.withdrawn_v1 | 同步群成员 |
群配置修改 im.chat.updated_v1 | 同步群名和群发言设置 |
群解散 im.chat.disbanded_v1 | 停止处理已解散的群 |
通讯录同步还需要订阅 contact.user.created_v3、contact.user.updated_v3、contact.scope.updated_v3、contact.department.created_v3、contact.department.updated_v3 和 contact.department.deleted_v3。这些事件触发资料与成员同步；ZAI 另有周期校准。人员离职、账号冻结的自动处理不在此功能内。
ZAI 不处理表情回复等其他消息事件，无需订阅。
卡片回调
在“事件与回调 → 回调配置”添加卡片回传交互 card.action.trigger。ZAI 卡片上的按钮都经由这个回调处理。回调配置的订阅方式与事件配置分开设置，须同样按接收方式选择；请求地址方式下填写与事件配置相同的地址，通过校验后才能添加回调。没有添加回调，或订阅方式、地址与事件配置不一致时，点击按钮后飞书客户端会提示出错。
权限
在“开发配置 → 权限管理”按功能开通以下权限。同一行列出多项时开通其中一项即可。群成员同步不要求通讯录相关权限。
| 功能 | 权限 |
|---|---|
| 接收私聊消息 | im:message.p2p_msg:readonly 或 im:message.p2p_msg |
| 接收群聊中的全部消息 | im:message.group_msg |
| 接收撤回事件、读取单条消息 | im:message 或 im:message:readonly |
| 读取消息下的表情回复 | im:message:readonly 或 im:message.reactions:read |
| 发送、回复和撤回自己发的消息 | im:message:send_as_bot |
| 更新进度卡与回复中的用量 | im:message:update |
| 在消息上添加处理状态表情 | im:message.reactions:write_only |
| 上传图片和文件 | im:resource |
| 读取群信息和群名 | im:chat:readonly |
| 读取群成员 | im:chat.members:read |
| 同步授权通讯录、读取成员资料 | contact:contact.base:readonly，并开通字段权限 contact:user.base:readonly |
| 完整读取通讯录授权范围 | contact:user.employee_id:readonly（缺少时授权用户列表可能被隐藏） |
| 读取部门基本信息 | contact:department.base:readonly |
| 展开授权范围中的用户组 | contact:group:readonly |
| 读取群里其他机器人的消息（仅自建应用，可选） | im:message.group_msg.include_bot:read |
只开通“接收群聊中 @ 机器人的消息”时，飞书不会推送话题里没有 @ ZAI 的回复：话题内免 @ 继续对话、读取聊天历史都无法正常工作。这些权限让应用能读到哪些内容，见飞书企业管理员须知。
“接收群聊中的全部消息”不包括其他机器人发的群消息。最后一行的可选权限只有自建应用能申请，商店应用申请不到；开通后，飞书把其他机器人的群消息也推送给 ZAI，ZAI 不会因此回复这些机器人。没有开通时 ZAI 怎样读到这些消息，见能读到哪些消息。
谁能使用
同企业用户可从应用授权通讯录或 Bot 所在群自动加入 Z Tag 组织，不必先互动或登录。群成员同步只需要群信息和群成员权限；通讯录权限缺失或调用失败不会阻断它。群内无法确认企业归属的用户不会自动加入。
应用可用范围另外决定谁能私聊 ZAI、登录控制台、收到受托私聊和审批通知。自动加入组织不代表一定能收到 Bot 消息。配置范围与资源授权的关系见飞书企业管理员须知。
控制台登录
成员用飞书账号登录控制台，登录经过本应用的网页授权。在开放平台“开发配置 → 安全设置 → 重定向 URL”添加 Z Tag 管理员提供的地址。没有添加时，从这个应用的 ZAI 打开控制台无法完成登录。
ZAI 发出的控制台链接（/organization 回复里的 打开控制台、审批通知）用发出它的应用登录。组织接入了多个应用时，直接打开控制台地址可能用另一个应用登录；这时请成员在自己企业的飞书里发送 /organization，从回复里的 打开控制台 进入，规则见一个组织接入多个 IM。
ZAI 发出的下载链接同样用链接所在聊天的应用登录；不在应用可用范围内的成员登录不了，下载链接的页面会请他找企业管理员加入可用范围，见下载链接的访问。
新增或更换应用
每个接入的飞书应用对应控制台里的一个 Workspace。一个组织可以接入多个飞书应用，例如另一个飞书企业的应用：请 Z Tag 管理员把新应用接入已有组织，新应用收到第一条消息后，控制台出现它的 Workspace。每个新应用都要按控制台登录添加重定向 URL。多个 Workspace 之间共用什么，见一个组织接入多个 IM。
原应用被删除，或要换成同一飞书企业的另一个应用时，请 Z Tag 管理员接入新应用并指定它接手原来的 Workspace。新应用收到第一条消息（例如被拉进群）时完成交接：
- 群、聊天记录、记忆、资源授权以及 Workspace 和群的设置都保留；
- 原应用正在进行的任务停止，没发出的回复不再发送，原应用随后断开；
- 新应用的机器人在飞书里是另一个身份：要把它拉进原来的群，才能在群里回复；私聊直接给新机器人发消息，仍对应控制台里同一个 个人范围；
- 在原话题里回复的定时任务和事件订阅改为每次新开话题；交接时恰好在发起中的那一次不再执行；原机器人发出的主动协助卡片不再响应；
- 原机器人发出的控制台链接仍可打开，改用新应用登录。
新应用收到第一条消息之前，可以请 Z Tag 管理员撤销这次交接，原应用照常服务。
Workspace 不能换到另一个飞书企业，也不能换成其他 IM；那样请 Z Tag 管理员新增一个 Workspace。各 Workspace 的应用与连接状态可以在控制台 组织管理 → IM 接入 查看，见查看 IM 接入。