> ## 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.

# 企业微信触发器

`WeCom Trigger` 用于将企业微信消息接入数字专家工作流，实现“用户在企业微信中发消息，Xpert AI 自动路由到指定数字专家执行”的触发链路。

企业微信集成负责连接企业微信，企业微信触发器负责决定消息进入哪个数字专家。当前企业微信触发器同时支持短连接回调和长连接 WebSocket 两种接入方式。

## 适用场景

* 在企业微信单聊或群聊中向数字专家提问
* 将企业微信机器人作为企业内部知识问答、数据分析或流程助手入口
* 不同数字专家分别绑定不同企业微信机器人或回调配置
* 用户习惯连续发送多条短消息，需要先汇总再交给数字专家处理
* 需要保留企业微信会话上下文，并支持用户主动开启新会话

## 接入方式

企业微信触发器可以绑定以下两类企业微信集成：

| 集成类型     | 适合场景                             | 关键配置                     | 消息入口                                             |
| -------- | -------------------------------- | ------------------------ | ------------------------------------------------ |
| 企业微信-短连接 | Xpert AI API 服务可被企业微信公网访问        | `Token`、`EncodingAESKey` | 企业微信回调 `POST /api/wecom/webhook/<integrationId>` |
| 企业微信-长连接 | 不方便提供公网回调地址，服务端可访问企业微信 WebSocket | `Bot ID`、`Secret`        | `wss://openws.work.weixin.qq.com`                |

短连接模式需要在企业微信后台配置 Callback URL，并完成 URL 校验。长连接模式由 Xpert AI 服务端主动连接企业微信 WebSocket；只有集成启用且已经被发布后的 WeCom Trigger 绑定时，长连接才会持续运行。

## 关键配置

WeCom Trigger 的核心配置包括：

* `enabled`：是否启用触发器
* `integrationId`：企业微信集成实例 ID（必填，可选择短连接或长连接集成）
* `sessionTimeoutSeconds`：会话超时时间，默认 `3600` 秒（一个小时）
* `summaryWindowSeconds`：消息汇总时间，默认 `0` 秒

发布前会校验：

1. 是否选择了有效的企业微信集成；
2. 当前集成是否已绑定到其他数字专家；
3. 触发器启用时，同一个企业微信集成同一时间只能绑定一个数字专家。

这种绑定关系可以避免一个企业微信机器人收到消息后同时触发多个数字专家，保证消息路由明确。

## 配置流程

### 1. 创建企业微信集成

如果使用短连接：

1. 在企业微信后台启用消息接收或 API 回调能力；
2. 获取 `Token` 和 `EncodingAESKey`；
3. 在 Xpert AI 中创建 **企业微信-短连接** 集成；
4. 保存后复制系统生成的 Callback URL，格式通常为：

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

5. 将 Callback URL、`Token` 和 `EncodingAESKey` 填回企业微信后台，并完成 URL 校验。

如果使用长连接：

1. 在企业微信后台创建智能机器人，并选择 API 模式长连接；
2. 获取 `Bot ID` 和 `Secret`；
3. 在 Xpert AI 中创建 **企业微信-长连接** 集成；
4. 确认服务端可以访问 `wss://openws.work.weixin.qq.com`；
5. 保存集成后，在集成详情页查看连接状态和最近错误。

### 2. 添加 WeCom Trigger

1. 打开需要接收企业微信消息的数字专家工作流；
2. 添加 **WeCom Trigger（企业微信触发器）**；
3. 选择已经创建好的企业微信集成；
4. 根据需要设置会话超时时间和消息汇总时间；
5. 将触发器连接到后续 Agent、工具或知识库节点；
6. 发布数字专家工作流。

发布成功后，平台会持久化 `integrationId -> xpertId` 绑定关系。企业微信消息到达时，会按这个绑定关系找到对应数字专家。

## 运行机制

1. **publish 阶段**：
   * 校验企业微信集成是否存在；
   * 检查同一个集成是否已被其他数字专家占用；
   * 写入或更新企业微信触发器绑定；
   * 如果绑定的是长连接集成，同步长连接运行状态。
2. **消息到达阶段**：
   * 短连接由企业微信回调接口接收并验签、解密；
   * 长连接由 WebSocket 接收企业微信机器人事件；
   * 系统解析出会话、发送者、消息内容和回复上下文。
3. **路由阶段**：
   * 根据 `integrationId` 查找已发布的 WeCom Trigger 绑定；
   * 没有绑定时，会向企业微信返回“当前企业微信集成未绑定触发器”一类提示；
   * 命中绑定后，把消息转换为数字专家工作流输入。
4. **执行阶段**：
   * 运行时回调仍可用时，直接推进当前工作流；
   * 回调不可用时（例如服务重启后），进入持久化分发队列；
   * 数字专家执行完成后，通过企业微信上下文回复用户。

## 会话管理

企业微信触发器会按企业微信集成、会话和发送者生成会话标识，用于延续数字专家上下文。

`sessionTimeoutSeconds` 控制会话保留时间。用户超过该空闲时长后再次发送消息，系统会自动开启新会话；未超时时，会继续使用上一次数字专家会话。

用户也可以主动发送：

```text theme={null}
/new
```

这会清空当前企业微信会话与数字专家会话的绑定关系。也可以直接在同一条消息里带上新问题：

```text theme={null}
/new 帮我分析本月销售额变化
```

这种情况下，系统会先重置会话，再把 `/new` 后面的文本作为新会话的第一条输入。

## 消息汇总

`summaryWindowSeconds` 用于处理用户连续发送多条短消息的场景。

* 设置为 `0`：每条消息立即触发数字专家；
* 设置为大于 `0`：同一会话在该时间窗口内收到的消息会先暂存，并合并为一条输入再发送给数字专家。

汇总期间如果又收到新消息，系统会刷新汇总版本，只分发最新版本，避免旧消息窗口重复触发。

## 回复能力

企业微信触发器会把企业微信回复上下文传入数字专家执行链路，后续节点可以通过企业微信通道回复用户。

短连接模式主要依赖企业微信回调中的 `response_url` 回复。长连接模式主要依赖 `req_id` 和 WebSocket 命令回复，并支持更完整的机器人交互体验：

* 收到消息后发送“正在思考”提示；
* 对长回答尽量使用企业微信长连接流式回复；
* 支持更新模板卡片；
* 会话失败或需要重置时，可发送重置会话卡片；
* 将 Markdown 转换为更适合企业微信展示的格式。

## 启动恢复策略

WeCom Trigger 使用 `bootstrap.mode = skip`：

* 启动时不重放 `publish`；
* 依赖数据库中的触发器绑定恢复消息路由；
* 外部企业微信消息再次到达时，会按持久化绑定继续分发；
* 长连接集成会结合绑定状态同步连接，未绑定时不会持续运行。

这种方式适合由外部消息持续驱动的触发器，避免系统重启后重复注册运行时回调。

## 常见问题

### 发送消息后没有回应

优先检查：

* 数字专家工作流是否已经添加并发布 WeCom Trigger；
* WeCom Trigger 是否启用，并选择了正确的企业微信集成；
* 是否有其他数字专家占用了同一个企业微信集成；
* 短连接 Callback URL 是否可公网访问，企业微信 URL 校验是否成功；
* 长连接集成是否处于连接状态，`Bot ID` 和 `Secret` 是否正确。

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

说明企业微信消息已经到达 Xpert AI，但没有找到可用的 `integrationId -> xpertId` 绑定。

请确认触发器已发布、未被禁用，并且选择的是当前企业微信机器人实际使用的集成。

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

可以让用户发送 `/new` 开启新会话。管理员也可以在企业微信集成详情页的会话列表中重置指定会话。

如果经常出现用户多条短消息被拆开处理，可以适当增大 `summaryWindowSeconds`；如果希望每条消息都立即响应，则保持默认值 `0`。

## 关联功能

* 触发器节点总览： [工作流触发器](../../workflow/trigger/)
* 数字专家多 Channel 接入： [数字专家](../../agent/agent/)
* 企业微信集成配置： [企业微信集成](../integration/wecom-integration/)
* 插件触发器总览： [Trigger 插件](./)
* 源码地址： [xpert-plugins / wecom integration](https://github.com/xpert-ai/xpert-plugins/tree/main/xpertai/integrations/wecom)