# 企业微信应用消息与通讯录配置

使用企业微信自建应用后，智能体可以向应用可见范围内的成员发送应用消息并查询通讯录。需要企业微信消息触发 MOI 时，再配置消息回调。

## 准备企业微信自建应用

需要能够登录[企业微信管理后台](https://work.weixin.qq.com/wework_admin/)并管理自建应用。没有管理员权限时，请由管理员创建应用并提供同一应用的 CorpID、AgentID 和 Secret。

### 1. 创建应用

打开 **应用管理 > 应用管理**。

```{figure} /assets/images/agents/guide-5-hd/wecom-admin-app-management.png
:alt: 企业微信管理后台中的应用管理入口。
:class: agent-guide-image
:figclass: agent-guide-shot

在企业微信管理后台打开应用管理。
```

在“自建”区域点击 **创建应用**。

```{figure} /assets/images/agents/guide-5-hd/wecom-create-application-entry.png
:alt: 企业微信应用管理页面中的创建应用入口。
:class: agent-guide-image
:figclass: agent-guide-shot

点击创建应用。
```

填写应用名称，例如“MOI 通知”；在 **可见范围** 中至少选择用于测试的成员，然后点击 **创建应用**。

```{figure} /assets/images/agents/guide-5-hd/wecom-create-application-form.png
:alt: 在企业微信管理后台填写自建应用名称和可见范围。
:class: agent-guide-image
:figclass: agent-guide-shot

填写应用名称和可见范围后创建应用。
```

### 2. 复制企业和应用凭据

在 **我的企业 > 企业信息** 中复制“企业 ID”，它对应 MOI 的 **CorpID**。

```{figure} /assets/images/agents/guide-5-hd/wecom-company-id.png
:alt: 企业微信企业信息页面中的企业 ID。
:class: agent-guide-image
:figclass: agent-guide-shot

企业 ID 对应 MOI 的 CorpID。
```

回到 **应用管理 > 应用管理**，打开刚创建的应用。复制 **AgentId** 和 **Secret**；它们分别对应 MOI 的 **AgentID** 和 **Secret**。

```{figure} /assets/images/agents/guide-5-hd/wecom-app-credentials.png
:alt: 企业微信自建应用详情中的 AgentId 和 Secret。
:class: agent-guide-image
:figclass: agent-guide-shot

从同一个自建应用复制 AgentId 和 Secret。
```

## 在 MOI 创建应用消息实例

返回 **资源中心 > 工具库 > 企业微信**，点击 **新增 > 应用消息/通讯录**。

```{figure} /assets/images/agents/guide-5-hd/wecom-select-app-message.png
:alt: 在企业微信工具的新增菜单中选择应用消息和通讯录。
:class: agent-guide-image
:figclass: agent-guide-shot

选择“应用消息/通讯录”。
```

填写名称、CorpID、AgentID 和 Secret。需要接收消息回调时，再点击 **生成** 创建 Callback Token；只有在企业微信使用加密消息时才生成 EncodingAESKey。

```{figure} /assets/images/agents/guide-5-hd/wecom-moi-application-form.png
:alt: MOI 企业微信应用消息和通讯录实例表单。
:class: agent-guide-image
:figclass: agent-guide-shot

填写企业微信自建应用凭据。
```

| MOI 字段 | 填写内容 |
| --- | --- |
| 工具实例名称 | 自行命名，例如“MOI 企业微信测试应用”。 |
| CorpID | 企业微信 **我的企业 > 企业信息** 中的企业 ID。 |
| AgentID | 自建应用的 AgentId。 |
| Secret | 自建应用的 Secret。 |
| Callback Token | 仅配置“接收消息”回调时生成并填写。 |
| EncodingAESKey | 仅企业微信回调使用加密模式时生成并填写。 |
| 连接超时（秒） | 可留空，系统默认 30 秒。 |

点击 **保存** 后测试连接。测试通过表示 MOI 可以使用当前 CorpID、AgentID 和 Secret 调用企业微信应用接口；它不表示消息已经送达成员。

## 配置接收消息回调（可选）

只有需要“企业微信中的新消息触发智能体或任务”时，才配置这一部分。

1. 保存实例后，进入实例详情并复制 **公网回调 URL**。
2. 编辑实例，为 **Callback Token** 点击 **生成** 并复制值。企业微信使用加密模式时，同时生成并复制 **EncodingAESKey**。

   ```{figure} /assets/images/agents/guide-5-hd/wecom-callback-token.png
   :alt: 在 MOI 企业微信实例编辑页生成 Callback Token 和 EncodingAESKey。
   :class: agent-guide-image
   :figclass: agent-guide-shot

   在 MOI 生成回调校验值。
   ```

3. 在企业微信自建应用的“接收消息”设置中填入公网回调 URL、Callback Token，以及需要时的 EncodingAESKey，完成地址校验。
4. 回到 MOI 实例详情，新增一条转发规则，选择收到消息后要触发的智能体或任务。
5. 用企业微信向该应用发送一条测试消息，确认目标被触发。

## 验证与排查

将实例绑定到目标智能体，要求它向可见范围内的测试成员发送一条消息，再在企业微信客户端确认收到消息。

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 连接测试失败 | CorpID、AgentID、Secret 是否来自同一企业和同一应用 | 重新复制三个值；检查应用权限和可信 IP 设置。 |
| 无法发送消息 | 测试成员是否在应用可见范围 | 把成员加入可见范围后重试。 |
| 回调地址校验失败 | 回调 URL、Callback Token、EncodingAESKey 是否来自同一实例 | 重新复制；明文模式不要填写 EncodingAESKey。 |
| 已校验但没有触发 | MOI 是否已有启用的转发规则 | 新增规则并指定目标智能体或任务。 |

- [返回企业微信配置指南](../wecom.md)