> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 企业微信集成

企业微信集成用于把企业微信机器人接入 Xpert AI。它负责保存企业微信回调或长连接凭证，并提供运行状态和会话管理；消息要进入某个数字专家，还必须在数字专家工作流中添加并发布 [企业微信触发器](../trigger/wecom-trigger/)。

当前 `@xpert-ai/plugin-wecom` 提供两类集成：

<Tip>
  企业微信属于通信类插件，必须在**租户级别**安装 `@xpert-ai/plugin-wecom`。租户级安装会注册企业微信系统集成提供方、回调/长连接入口和企业微信触发器；如果只在组织、项目或个人范围安装，后续创建集成和触发器时可能找不到对应能力。
</Tip>

| 集成提供方        | 页面显示     | 适合场景                                   | 关键配置                     |
| ------------ | -------- | -------------------------------------- | ------------------------ |
| `wecom`      | 企业微信-短连接 | Xpert AI API 服务可以被企业微信公网访问             | `Token`、`EncodingAESKey` |
| `wecom_long` | 企业微信-长连接 | 推荐模式，不方便提供公网回调地址，服务端可以访问企业微信 WebSocket | `Bot ID`、`Secret`        |

默认推荐使用 **企业微信-长连接**（`wecom_long`）。只有在已经具备稳定公网回调地址，或需要兼容短连接部署时，再使用 **企业微信-短连接**（`wecom`）。同一个企业微信机器人在企业微信后台通常也只能选择一种接入方式：短连接依赖回调地址，长连接依赖 WebSocket。

## 一、短连接配置

短连接使用企业微信的回调地址接收消息。企业微信会向 Xpert AI 的 Callback URL 发起 URL 校验和消息推送。

### 准备企业微信配置

1. 登录 [企业微信管理后台](https://work.weixin.qq.com/)。
2. 进入需要接入的应用或 API 模式机器人配置页面。
3. 启用消息接收或 API 回调能力。
4. 记录或生成：
   * **Token**
   * **EncodingAESKey**
5. 确认 Xpert AI API 服务有公网 HTTPS 地址，并能被企业微信访问。

### 在 Xpert AI 创建短连接集成

进入 **设置 -> 系统集成**，创建提供方为 **企业微信-短连接** 的集成。

| 配置项              | 说明                                   |
| ---------------- | ------------------------------------ |
| `回调 Token`       | 企业微信 API 模式中配置的 Token。               |
| `EncodingAESKey` | 企业微信 API 模式中配置的 43 位 EncodingAESKey。 |
| `首选语言`           | 可选，影响错误提示和系统提示。                      |
| `请求超时（毫秒）`       | 可选，外发 webhook 或回复请求的超时时间。            |

保存或测试后，系统会返回回调地址：

```text theme={null}
https://<your-api-domain>/api/wecom/webhook/<integrationId>
```

将该地址填入企业微信后台，并完成 URL 校验。短连接 URL 校验会使用 `msg_signature`、`timestamp`、`nonce`、`echostr` 与集成中的 Token、EncodingAESKey 完成验签和解密。

### 短连接回调检查

若只想确认回调路由可达，可以访问：

```text theme={null}
GET /api/wecom/webhook/<integrationId>
```

在没有企业微信校验参数时，该接口会返回 `success`，表示 Xpert API 路由和集成 ID 可读取；正式 URL 校验仍以企业微信携带的签名参数为准。

## 二、长连接配置

长连接使用企业微信智能机器人 API 模式。Xpert AI 服务端主动连接企业微信 WebSocket 地址，因此不需要公网 Callback URL。

企业微信长连接地址为：

```text theme={null}
wss://openws.work.weixin.qq.com
```

### 准备企业微信机器人

1. 登录企业微信管理后台。
2. 进入 **安全与管理 -> 管理工具 -> 智能机器人**。
3. 创建机器人时选择 **API 模式**，并将接入方式设置为 **长连接**。
4. 记录：
   * **Bot ID**
   * **Secret**
5. 确认 Xpert AI 服务端可以出站访问 `wss://openws.work.weixin.qq.com`。

### 在 Xpert AI 创建长连接集成

进入 **设置 -> 系统集成**，创建提供方为 **企业微信-长连接** 的集成。

| 配置项                | 说明                                       |
| ------------------ | ---------------------------------------- |
| `Bot ID`           | 企业微信智能机器人 API 长连接模式中的 Bot ID。            |
| `Secret`           | 用于 `aibot_subscribe` 的长连接 Secret。        |
| `WebSocket Origin` | 可选，为 WebSocket 握手设置 Origin 头，用于兼容部分网络策略。 |
| `首选语言`             | 可选，影响错误提示和系统提示。                          |
| `请求超时（毫秒）`         | 可选，等待 WebSocket 命令 ack 的超时时间。            |

保存长连接集成后，插件会尝试根据当前状态同步连接。但长连接只有在集成启用、配置有效，并且已绑定到发布后的企业微信触发器时才会持续运行。未绑定触发器时，系统会停止连接并标记为 `xpert_unbound`。

## 三、绑定数字专家

无论短连接还是长连接，保存集成都不等于机器人可用。还需要：

1. 打开目标数字专家工作流。
2. 添加 [企业微信触发器](../trigger/wecom-trigger/)。
3. 选择刚创建的企业微信集成。
4. 配置会话超时时间和消息汇总时间。
5. 发布数字专家工作流。

同一个企业微信集成同一时间只能绑定一个数字专家。如果多个数字专家同时绑定同一个集成，发布校验会提示冲突。

## 四、状态与会话管理

企业微信集成详情页提供扩展页签：

* **状态**：仅长连接集成显示，包含连接方式、状态、Bot ID、持有实例、最近连接/断开/回调/心跳时间、最近错误、重连次数和停止原因。
* **会话**：短连接和长连接都显示，包含会话类型、会话 ID、发送者 ID、数字专家 ID、对话 ID 和更新时间。

长连接状态页支持刷新、重连和断开。会话页支持重置会话，效果与用户发送 `/new` 一致：清空当前企业微信会话与数字专家会话的绑定，下一条消息会开启新会话。

## 五、消息与回复能力

短连接模式主要依赖企业微信回调中的 `response_url` 回复。长连接模式主要依赖 `req_id` 和 WebSocket 命令回复。

长连接模式支持更完整的机器人体验：

* 收到用户消息后发送“正在思考”提示；
* 对长回答尽量使用企业微信长连接流式回复；
* 支持更新模板卡片；
* 用户进入单聊时可以发送欢迎卡片；
* 会话失败或需要重置时发送可点击的重置会话卡片；
* 图片回调会下载图片资源并作为数字专家可见文件输入。

短连接仍可以接收和回复消息，但无法提供长连接下的完整流式体验。

## 常见问题

### 企业微信提示未绑定触发器

说明企业微信消息已经到达 Xpert AI，但没有找到当前集成的 `integrationId -> xpertId` 绑定。请确认：

* 目标数字专家已添加企业微信触发器；
* 触发器已启用；
* 选择的是当前机器人实际使用的集成；
* 数字专家工作流已发布成功。

### 短连接 URL 校验失败

检查：

* `API_BASE_URL` 是否是企业微信可访问的公网 HTTPS 地址；
* 反向代理是否转发 `/api/wecom/webhook/<integrationId>`；
* 企业微信后台 Token 与集成中的 `回调 Token` 是否一致；
* EncodingAESKey 是否为 43 位且完全一致。

### 长连接无法建立

检查：

* 企业微信后台是否选择 API 模式长连接；
* 是否误用了短连接的 Token/EncodingAESKey；
* Bot ID 和 Secret 是否来自同一个机器人；
* 服务端是否允许访问 `wss://openws.work.weixin.qq.com`；
* 集成是否已绑定到发布后的企业微信触发器。

### 会话上下文不符合预期

可以让用户发送 `/new` 开启新会话，也可以在集成详情页的会话列表中重置指定会话。如果用户经常连续发送多条短消息，可以在企业微信触发器中增大 `summaryWindowSeconds`。