# 飞书事件订阅配置

配置事件订阅后，飞书会把已订阅的消息等事件发送到 MOI，再由 MOI 按事件路由触发目标智能体或任务。

## 准备飞书应用和凭据

需要一个已添加机器人能力的飞书企业自建应用。尚未创建应用时，先参考[飞书消息发送配置](message.md#准备飞书应用)完成应用创建和机器人添加。

在 **凭证与基础信息** 中复制 **App ID** 和 **App Secret**。然后打开 **事件与回调 > 加密策略**，复制 **Verification Token**；启用事件加密时，同时复制 **Encrypt Key**。

```{figure} /assets/images/agents/guide-5-hd/feishu-event-encryption.png
:alt: 飞书开放平台的事件与回调页面，显示 Verification Token 和 Encrypt Key。
:class: agent-guide-image
:figclass: agent-guide-shot

事件订阅使用 Verification Token；启用事件加密时还需使用 Encrypt Key。
```

App ID、App Secret、Verification Token 和 Encrypt Key 必须来自同一个应用。

## 在 MOI 创建事件订阅实例

1. 打开 **资源中心 > 工具库 > 飞书**。
2. 点击 **新增 > 事件订阅**。
3. 填写实例名称、App ID、App Secret 和 Verification Token；飞书应用启用事件加密时再填写 Encrypt Key。
4. 点击 **保存**，进入实例详情并复制 **MOI 回调 URL**。

## 在飞书配置事件

1. 在飞书开放平台打开同一个应用，进入 **事件与回调 > 事件配置**。
2. 将订阅方式设为 **将事件发送至开发者服务器**，填入 MOI 实例的回调 URL，并按页面提示完成地址校验。配置方法见[飞书请求地址配置说明](https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case)。
3. 点击 **添加事件**。需要接收聊天消息时，选择 **接收消息 v2.0**（`im.message.receive_v1`）并确认添加。

```{figure} /assets/images/agents/guide-5-hd/feishu-receive-event-reference.png
:alt: 飞书添加事件弹窗中选中接收消息 v2.0，事件标识为 im.message.receive_v1。
:class: agent-guide-image
:figclass: agent-guide-shot

添加接收消息事件。
```

4. 在 **权限管理** 中开通事件要求的权限。以[飞书接收消息事件说明](https://open.feishu.cn/document/server-docs/im-v1/message/events/receive)列出的权限为准。
5. 在 **版本管理与发布** 中创建并发布版本，确认测试用户在应用可用范围内。

## 配置 MOI 事件路由并验证

返回 MOI 事件订阅实例，配置事件路由目标。在测试群或单聊中发送一条符合订阅范围的消息，然后分别检查飞书事件投递结果和 MOI 目标任务是否被触发。

| 现象 | 检查方法 |
| --- | --- |
| 回调地址校验失败 | 核对 MOI 回调 URL、Verification Token、Encrypt Key 和网络可达性。 |
| 飞书没有投递事件 | 检查事件是否已添加、所需权限是否开通，以及应用版本是否重新发布。 |
| MOI 收到事件但没有触发目标 | 检查事件订阅实例是否配置了正确的路由目标和事件类型。 |

- [返回飞书配置指南](../feishu.md)