跳转到主要内容

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 多智能体平台支持企业微信集成功能。通过本集成，企业用户可以直接在企业微信中向数字专家发起对话，也可以在会话中使用 ChatBI 工具集进行数据分析，并接收平台返回的分析结果。 本教程将指导您完成企业微信接入、工作流触发器绑定和会话管理配置。 当前企业微信接入可分为两种方式：
  • 短连接配置（URL 回调）：由企业微信回调 Xpert AI 的服务地址，适合已经具备公网回调地址的部署方式。
  • 长连接配置（WebSocket）：由 Xpert AI 服务端主动连接企业微信 WebSocket 地址，适合不方便提供公网回调地址的场景。
无论选择哪一种接入方式，都需要在数字专家工作流中添加并发布 WeCom Trigger（企业微信触发器）。企业微信集成只负责连接企业微信；消息最终路由到哪个数字专家，由 WeCom Trigger 绑定关系决定。 当前企业微信接入可分为两种方式：
  • 短链接配置（URL 回调）：由企业微信回调您的服务地址，适合已经具备公网回调地址的部署方式。
  • 长链接配置（WebSocket）：由服务端主动连接企业微信 WebSocket 地址，适合不方便提供公网回调地址的场景。
请根据您的部署方式选择其一进行配置，如果是需要让数字专家主动向企业微信推送消息的场景，建议使用长链接配置方式。

​
一、短链接配置（URL 回调）

​
第一步：创建企业微信应用并获取必要信息

在开始前，请确认您已经具备以下条件：
  • 已有可正常使用的 Xpert AI 数字专家。
  • 如果数字专家需要进行数据分析，已在工具集中启用对应的 ChatBI 能力。
  • 已拥有企业微信管理后台权限。
  • 如果选择短连接模式，Xpert AI API 服务需要能被企业微信公网访问。
  • 如果选择长连接模式，Xpert AI 服务端需要能访问企业微信 WebSocket 地址 wss://openws.work.weixin.qq.com。

​
二、短连接配置（URL 回调）

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

​
第一步：在企业微信中准备 API 回调配置

  1. 登录 企业微信管理后台。
  2. 进入需要接入的应用或 API 模式机器人配置页面。
  3. 启用消息接收或 API 回调能力。
  4. 记录或生成以下信息：
    • Token
    • EncodingAESKey
✅ 至此，你已经获得了以下四项重要信息：
  • AgentId
  • Secret
  • Token
  • EncodingAESKey
保存成功后，系统会生成企业微信 Callback URL，格式通常为：

​
第二步：配置数字专家与企业微信集成

  1. 登录 Xpert AI 平台，前往“数字专家”模块，创建一个新的数字专家智能体。
  2. 在配置工具集时，若该智能体用于数据分析，请选择工具集类型为 “与企业微信对话 BI”，以启用 ChatBI 分析能力。
  3. 完成智能体配置后，点击“发布版本”，并在发布到第三方平台步骤中添加“企业微信”发布渠道。
  4. 填写刚才在企业微信管理后台中获取的四项信息：
    • AgentId
    • Secret
    • Token
    • EncodingAESKey
如果校验失败，请优先检查 Callback URL 是否可公网访问，以及 Token、EncodingAESKey 是否完全一致。

​
第三步：将回调地址填入企业微信以完成验证

长连接模式使用企业微信智能机器人 API 模式。Xpert AI 服务端会主动连接企业微信 WebSocket，因此不需要配置公网 Callback URL。 企业微信 API 模式同一时间只能选择一种接入方式：如果切换为长连接，则原有回调地址模式将不再生效；如果切回回调地址模式，则现有长连接也会失效。

​
第一步：在企业微信创建 API 模式机器人

  1. 登录企业微信管理后台。
  2. 进入“安全与管理” → “管理工具” → “智能机器人”。
  3. 创建机器人时，选择 API 模式，并将接入方式设置为长连接。
  4. 创建完成后，记录以下信息：
    • Bot ID
    • Secret

​
第二步：在 Xpert AI 中创建企业微信长连接集成

  1. 登录 Xpert AI 平台。
  2. 进入“集成”或“插件集成”配置页面。
  3. 新建企业微信集成，选择 企业微信-长连接。
  4. 填写以下字段：
    • Bot ID：企业微信智能机器人 API 模式中的 Bot ID。
    • Secret：企业微信智能机器人的长连接认证密钥。
    • WebSocket Origin：可选，仅当网络策略要求设置 Origin 时填写。
    • 首选语言：可选，用于错误提示、系统提示和卡片文案。
    • 请求超时：可选，用于等待 WebSocket 命令回执。
  5. 保存集成。
长连接集成保存后，系统会尝试建立 WebSocket 连接。但只有该集成已经绑定到发布后的 WeCom Trigger，并且集成处于启用状态时，长连接才会持续运行。

​
第三步：查看长连接状态

​
第四步：在企业微信中对话数字专家

  • 当前连接状态
  • 连接方式
  • 持有连接的服务实例
  • 最近连接时间
  • 最近断开时间
  • 最近回调时间
  • 最近心跳时间
  • 最近错误
  • 重连次数
  • 停止或禁用原因
在状态页签中，也可以执行刷新、重连和断开操作。

​
二、长链接配置（WebSocket）

长链接模式与短链接模式是两套不同的接入方式。短链接模式依赖 Callback URL、Token 和 EncodingAESKey 完成 URL 验证；长链接模式则由服务端主动发起 WebSocket 连接，不再依赖“接收消息服务器地址”。 企业微信 API 模式同一时间只能选择一种方式：如果切换为长链接，则原有回调地址模式将不再生效；如果切回回调地址模式，则现有长链接也会失效。 现有企微配置项主要包括：
  • WECOM_TOKEN
  • WECOM_AES_KEY
  • WECOM_AGENT_ID
  • WECOM_SECRET
这组配置对应的是当前文档上半部分使用的短链接模式。如果您要接入企业微信长链接模式，则需要改为按照企业微信长链接协议，使用 BotID 和 Secret 建立 WebSocket 连接。

​
第一步：在企业微信创建 API 模式机器人并选择长链接

  1. 登录企业微信管理后台。
  2. 进入**“安全与管理”** → “管理工具” → “智能机器人”。
  3. 创建机器人时，选择 API 模式，并将接入方式设置为长连接。
  4. 创建完成后，记录以下两项信息：
    • BotID
    • Secret

​
第二步：准备长链接所需的服务端配置

长链接模式下，服务端需要具备以下连接信息：
  • BotID：企业微信长链接机器人的唯一标识
  • Secret：长链接认证密钥
  • WebSocket 连接地址：企业微信文档中的 WebSocket 地址 wss://openws.work.weixin.qq.com，本项可选择性配置，如果不配置，系统会使用企业微信官方文档中默认的 WebSocket 地址。
与短链接模式不同，长链接模式不需要再配置以下字段：
  • Callback URL
  • Token
  • EncodingAESKey

​
第三步：由服务端建立 WebSocket 连接并完成认证

  1. 服务端向企业微信 WebSocket 地址发起出站连接。
  2. 连接建立后，按照企业微信长链接协议使用 BotID 和 Secret 完成认证。
  3. 认证成功后，服务端持续监听消息、事件与回执，并维护心跳与断线重连机制。
这种模式下，消息由服务端通过长连接持续接收和回复，因此不需要企业微信反向请求您的公网回调地址。

​
第四步：验证消息收发是否正常

  1. 在企业微信中打开该机器人，或将其加入有权限的群聊。
  2. 发送一条测试消息，确认服务端能够正常收到并回复。
  3. 如需主动推送消息，也应在连接建立成功后由服务端按企业微信协议发送对应消息。

​
常见问题（FAQ）

  1. 进入“数字专家”模块。
  2. 打开需要接收企业微信消息的数字专家。
  3. 进入该数字专家的工作流编辑页面。

​
第二步：添加企业微信触发器

  1. 在工作流中添加 WeCom Trigger（企业微信触发器）。
  2. 在触发器配置中选择刚创建的企业微信集成。
  3. 根据需要配置以下参数：
    • 启用：开启后，该触发器才会接收企业微信消息。
    • 企业微信集成：选择短连接或长连接集成。
    • 会话超时时间（秒）：用户超过该空闲时间后再发消息，会开启新会话。
    • 汇总时间（秒）：在该时间窗口内收到的连续消息会先合并，再发送给数字专家。设置为 0 表示不汇总，立即发送。
  4. 连接触发器与后续工作流节点。
  5. 发布数字专家工作流。
同一个企业微信集成同一时间只能绑定到一个数字专家。如果多个数字专家同时绑定同一个集成，系统会在校验时提示冲突。

​
第三步：验证消息路由

  1. 在企业微信中打开对应应用或机器人。
  2. 发送一条测试消息。
  3. 确认数字专家能够正常回复。
如果企业微信返回“当前企业微信集成未绑定触发器”的提示，说明该集成还没有绑定到已发布的 WeCom Trigger，或绑定的工作流尚未发布成功。

​
五、会话管理

企业微信插件会为每个企业微信会话保存数字专家的上下文会话状态。这样用户连续提问时，数字专家可以延续上一轮上下文。

​
开启新会话

用户可以在企业微信中发送： 
/new
系统会清空当前企业微信会话与数字专家会话的绑定关系，下一条消息将从新会话开始。 也可以直接发送带问题的指令，例如： 
/new 帮我分析本月销售额变化
系统会先重置会话，再把后面的内容作为新会话的第一条问题发送给数字专家。

​
会话超时

WeCom Trigger 中的“会话超时时间（秒）”用于控制上下文保留时间。超过该空闲时间后，用户下一次发送消息时，系统会自动开启新会话。

​
消息汇总

如果 WeCom Trigger 中的“汇总时间（秒）”大于 0，系统会在该时间窗口内暂存同一会话中的连续消息，并将它们合并为一条输入发送给数字专家。 该能力适合用户习惯连续发送多条短消息的场景，可以减少数字专家过早响应导致的上下文不完整问题。

​
在集成详情页管理会话

企业微信集成详情页提供“会话”页签，可以查看当前集成下的会话列表，包括：
  • 会话类型
  • 会话 ID
  • 发送者 ID
  • 数字专家 ID
  • 数字专家会话 ID
  • 更新时间
管理员可以在会话列表中重置指定会话。该操作与用户发送 /new 的效果一致。

​
六、回复体验与长连接增强

长连接模式支持更完整的企业微信机器人交互体验：
  • 收到用户消息后，系统会优先发送“正在思考”的流式提示。
  • 数字专家生成回答时，系统会尽量通过企业微信长连接流式更新可见内容。
  • 如果流式回复失败，系统会回退为普通文本回复。
  • 用户进入单聊时，系统可以发送欢迎卡片。
  • 当会话失败或需要重置时，系统会发送可点击的重置会话卡片。
  • 企业微信 Markdown 会被转换为更适合企业微信展示的格式。
短连接模式仍通过企业微信回调上下文回复消息；长连接模式则通过 req_id、会话上下文和 WebSocket 命令完成回复。

​
5. 长链接模式下 WebSocket 无法建立或收不到消息

可能原因及解决方法：
  • 误用了短链接模式的配置项
    👉 长链接模式应使用 BotID 和 Secret，而不是 Callback URL、Token、EncodingAESKey。
  • 企业微信后台未选择 API 模式的长连接方式
    👉 请确认创建机器人时选择的是长连接，而不是“接收消息服务器地址”模式。
  • 服务端无法访问企业微信 WebSocket 地址
    👉 请检查服务端是否允许访问 wss://openws.work.weixin.qq.com，并确认网络策略没有拦截出站 WebSocket 连接。
如需进一步了解 ChatBI 功能或企业定制化需求，欢迎联系我们的产品支持团队！