> ## 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 与外部平台连通；要让外部消息进入某个数字专家，还需要在目标数字专家工作流中添加对应触发器并发布版本。

## 集成与触发器的边界

外部 IM 接入通常拆成两个对象：

* **集成**：保存平台凭证、回调地址、长连接配置和运行状态，负责让 Xpert AI 与外部平台连通。
* **触发器**：出现在数字专家工作流中，负责把某个集成绑定到当前数字专家，并决定会话超时、消息汇总和消息路由。

因此，创建飞书、企业微信或钉钉机器人时，不是只保存集成就结束了。还需要在目标数字专家工作流中添加对应触发器并发布版本，消息才会进入该数字专家。

## 通信类插件安装要求

<Tip>
  飞书、企业微信、钉钉这类通信类插件必须安装在**租户级别**。这些插件会注册系统集成提供方、Webhook 或长连接入口、触发器策略和消息分发能力；如果只在组织、项目或个人范围安装，系统集成和触发器选择器可能无法找到对应提供方，外部消息也无法稳定路由到数字专家。
</Tip>

## 推荐接入模式

| 平台   | 插件                          | 推荐模式                                        | 备用模式                                      |
| ---- | --------------------------- | ------------------------------------------- | ----------------------------------------- |
| 飞书   | `@xpert-ai/plugin-lark`     | **飞书长连接**（`connectionMode=long_connection`） | Webhook，仅在已有稳定公网 HTTPS 回调地址时使用            |
| 企业微信 | `@xpert-ai/plugin-wecom`    | **企业微信-长连接**（`wecom_long`）                  | 企业微信-短连接（`wecom`），仅在已有稳定公网回调地址时使用         |
| 钉钉   | `@xpert-ai/plugin-dingtalk` | **钉钉-Stream模式**（`dingtalk_long`）            | 钉钉-HTTP模式（`dingtalk`），仅在无法使用 Stream 模式时使用 |

## 通用配置流程

1. 在租户级别安装对应通信类插件。
2. 在外部平台创建企业自建应用或机器人，并开通机器人、消息接收、通讯录或群聊读取等必要权限。
3. 先切换到要使用该机器人的目标组织，再进入 **设置 -> 系统集成**，创建对应平台的集成。系统集成是组织级别创建的，后续触发器只能选择当前组织下已有的集成。
4. 按推荐模式优先选择长连接或 Stream 模式；如果使用 Webhook/HTTP/短连接模式，确认 `API_BASE_URL` 是外部平台可访问的公网 HTTPS 地址。
5. 保存并测试集成，确认凭证、连接状态和回调地址可用。
6. 打开目标数字专家工作流，添加对应触发器，选择刚创建的集成。
7. 发布数字专家工作流，让外部消息进入当前数字专家。

## 集成文档

* [飞书集成](./lark-integration/)
* [企业微信集成](./wecom-integration/)
* [钉钉集成](./dingtalk-integration/)

## 关联触发器

* [飞书触发器](../trigger/lark-trigger/)
* [企业微信触发器](../trigger/wecom-trigger/)
* [钉钉触发器](../trigger/dingtalk-trigger/)