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

# 配置钉钉 H5 工作台应用

本文介绍如何把已发布的 Xpert 数字专家添加到钉钉工作台。

请根据使用方式选择其中一种配置方法：

* **使用 Xpert 线上系统**：系统管理员已经配置好钉钉 SSO，你需要为自己的数字专家创建钉钉 H5 微应用和钉钉集成。
* **使用本地或私有化部署的 Xpert**：管理员先配置钉钉 SSO，然后数字专家创建者再配置自己的钉钉 H5 微应用。

<Note>
  本文配置的是钉钉 H5 工作台应用。如果你需要在钉钉群中通过机器人收发消息，请参考[钉钉机器人集成](/zh-Hans/ai/toolset/dingtalk)。
</Note>

## 方式一：使用已配置钉钉 SSO 的 Xpert 线上系统

这种方式适用于 Xpert 管理员已经完成钉钉 SSO 配置的线上系统。

钉钉 SSO 由管理员统一配置。你仍然需要创建自己的钉钉 H5 微应用，并在 Xpert 中为这个微应用新建钉钉集成。

<Note>
  钉钉 SSO 集成和 H5 微应用集成是两项独立配置。创建 H5 微应用集成时，请使用自己微应用的 Client ID、Client Secret，以及该微应用所属企业的 Corp ID。
</Note>

### 开始前：联系管理员确认 SSO 回调地址

钉钉 SSO 回调地址配置在管理员维护的 SSO 应用中，普通数字专家创建者通常没有权限添加。这个回调地址不需要添加到你自己的 H5 微应用中。

1. 向 Xpert 管理员确认当前系统的完整 SSO 回调地址，例如：

```text theme={null}
https://<Xpert 线上域名>/api/dingtalk-identity/callback
```

2. 请管理员将该地址加入钉钉 SSO 应用的登录回调地址列表。
3. 等待管理员确认配置完成后，再继续下面的步骤。

<Warning>
  如果回调地址使用临时域名，例如 `*.example.com`，域名发生变化后需要联系管理员重新添加。正式使用时建议配置固定的 HTTPS 域名。
</Warning>

### 第 1 步：创建自己的钉钉 H5 微应用

1. 登录[钉钉开放平台](https://open.dingtalk.com/)。
2. 创建一个企业内部应用。
3. 为应用启用 H5 微应用或网页应用能力。
4. 记录应用的 **Client ID（AppKey）** 和 **Client Secret（AppSecret）**。
5. 在钉钉企业管理后台复制该微应用所属企业的 **Corp ID**。
6. 设置应用的可见范围。

### 第 2 步：在 Xpert 中创建自己的钉钉集成

1. 登录 Xpert 线上系统。
2. 进入当前组织的 **系统集成** 页面。
3. 新建钉钉集成。
4. 填写自己 H5 微应用的 Client ID、Client Secret 和 Corp ID。
5. 保存并确认集成状态正常。

这个集成属于你的 H5 微应用，不是管理员配置的钉钉 SSO 集成。

### 第 3 步：发布数字专家

1. 打开需要嵌入钉钉的数字专家。
2. 完成数字专家的模型、知识库、工具和欢迎语配置。
3. 点击发布，确认数字专家可以正常对话。

### 第 4 步：启用钉钉工作台入口

1. 打开数字专家的 **Chat App（聊天应用）** 设置。
2. 启用 **DingTalk workbench app（钉钉工作台应用）**。
3. 选择第 2 步中自己创建的钉钉集成。
4. 保存设置。
5. 再次发布数字专家，使新的应用设置生效。

### 第 5 步：复制数字专家的钉钉 H5 地址

发布后，复制系统生成的钉钉工作台地址，例如：

```text theme={null}
https://<Xpert 线上域名>/x-chatkit/h5/dingtalk/<数字专家标识>
```

### 第 6 步：配置钉钉 H5 微应用首页

1. 回到自己创建的钉钉企业内部应用。
2. 进入应用的 H5 微应用或网页应用配置。
3. 将上一步复制的地址填写为应用首页地址。
4. 将 Xpert 线上系统的域名加入应用的安全域名或 JSAPI 安全域名。
5. 再次确认应用的可见范围。
6. 发布应用版本。
7. 将应用添加到企业工作台。

### 第 7 步：在钉钉中验收

1. 使用可见范围内的员工账号登录钉钉。
2. 从工作台打开应用。
3. 确认页面显示正确的数字专家。
4. 在输入框中发送一条消息。
5. 确认数字专家能够正常回复。

第一次使用时，如果页面提示登录或绑定账号，请按提示完成一次绑定。后续可以直接从钉钉工作台进入。

## 方式二：本地或私有化部署 Xpert

这种方式适用于部署在自己服务器上的 Xpert。请按下面的顺序完成配置。

### 第 1 步：准备可访问的 HTTPS 域名

为 Xpert 准备一个钉钉客户端可以访问的 HTTPS 域名，例如：

```text theme={null}
https://xpert.example.com
```

部署完成后，先在普通浏览器中确认该地址可以正常打开。

### 第 2 步：配置 Xpert 的线上访问地址

在 Xpert 的部署环境变量中配置实际域名：

```dotenv theme={null}
CLIENT_BASE_URL=https://xpert.example.com
API_BASE_URL=https://xpert.example.com
WEBAPP_API_BASE_URL=same-origin
VITE_CHATKIT_FRAME_URL=/chatkit
```

应用配置后，重新部署或重启 Xpert 服务。

<Note>
  正式部署不需要修改前端的 `project.json`，也不需要把线上域名加入开发服务器的 `allowedHosts`。
</Note>

### 第 3 步：安装钉钉插件

1. 以管理员身份登录 Xpert。
2. 打开插件管理页面。
3. 安装并启用钉钉插件。
4. 安装并启用钉钉 SSO 插件。
5. 按照部署方式重启 Xpert 服务，确认插件已经生效。

### 第 4 步：由管理员创建钉钉 SSO 应用

1. 登录[钉钉开放平台](https://open.dingtalk.com/)。
2. 创建一个企业内部应用。
3. 记录该应用的 **Client ID（AppKey）** 和 **Client Secret（AppSecret）**。
4. 为应用开通登录和用户身份所需的权限。
5. 设置应用的可见范围。

### 第 5 步：由管理员在 Xpert 中配置钉钉 SSO

1. 打开 Xpert 的 **系统设置 > 系统集成**。
2. 新建钉钉登录或钉钉 SSO 集成。
3. 填写上一步记录的 Client ID 和 Client Secret。
4. 保存集成。
5. 复制页面显示的回调地址；如果需要手动填写，请使用：

```text theme={null}
https://xpert.example.com/api/dingtalk-identity/callback
```

6. 回到钉钉开放平台，将该地址添加为应用的登录回调地址。

一个 Xpert 租户只配置一套有效的钉钉 SSO。

如果 Xpert 管理员没有钉钉 SSO 应用的管理权限，请将完整回调地址发送给该钉钉应用的管理员，由应用管理员添加。

<Warning>
  如果部署使用的公网地址会变化，变化后需要同步更新钉钉 SSO 应用中的回调地址。正式使用时建议配置固定的 HTTPS 域名。
</Warning>

### 第 6 步：由数字专家创建者创建自己的 H5 微应用

1. 登录钉钉开放平台。
2. 创建自己的企业内部应用。
3. 为应用启用 H5 微应用或网页应用能力。
4. 记录该 H5 微应用的 Client ID 和 Client Secret。
5. 在钉钉企业管理后台复制该 H5 微应用所属企业的 Corp ID。
6. 设置该 H5 微应用的可见范围。

### 第 7 步：由数字专家创建者配置自己的钉钉集成

1. 打开需要使用该应用的 Xpert 组织。
2. 进入 **系统集成**。
3. 新建钉钉集成。
4. 填写自己 H5 微应用的 Client ID、Client Secret 和 Corp ID。
5. 保存并确认集成状态正常。

H5 微应用集成与管理员配置的 SSO 集成是两项独立配置，不需要比较两者的 Corp ID。

### 第 8 步：发布数字专家

1. 创建或打开需要嵌入钉钉的数字专家。
2. 完成数字专家配置并发布一次。
3. 打开数字专家的 **Chat App（聊天应用）** 设置。
4. 启用 **DingTalk workbench app（钉钉工作台应用）**。
5. 选择第 7 步中自己创建的钉钉集成。
6. 保存设置并再次发布数字专家。

### 第 9 步：配置自己的钉钉 H5 微应用首页

1. 复制数字专家发布后生成的钉钉 H5 地址，例如：

```text theme={null}
https://xpert.example.com/x-chatkit/h5/dingtalk/<数字专家标识>
```

2. 回到自己 H5 微应用的配置页面。
3. 将该地址填写为应用首页地址。
4. 将 `xpert.example.com` 加入应用的安全域名或 JSAPI 安全域名。
5. 再次确认应用可见范围。
6. 发布应用版本。
7. 将应用添加到企业工作台。

### 第 10 步：完成首次账号绑定

1. 使用可见范围内的员工账号登录钉钉。
2. 从工作台打开应用。
3. 如果页面提示登录或绑定账号，请按提示完成一次绑定。
4. 绑定完成后，关闭应用并从工作台重新打开。

### 第 11 步：验收

依次确认以下结果：

* 钉钉工作台可以找到并打开应用。
* 页面显示的是刚才发布的数字专家。
* 输入框可以正常输入中英文。
* 发送消息后可以收到数字专家回复。
* 数字专家打开的视图可以正常加载。

## 常见问题

### 钉钉中打不开页面

检查应用首页是否使用 HTTPS、域名是否可以从公网访问，以及域名是否已经加入钉钉应用的安全域名。

### 工作台中找不到应用

检查应用版本是否已发布、是否已添加到工作台，以及当前员工是否在应用可见范围内。

### 打开后不是预期的数字专家

重新复制该数字专家发布后生成的钉钉 H5 地址，并确认钉钉应用首页没有填写其他数字专家的地址。

### 页面打开但不能发送消息

检查数字专家是否已发布、是否启用了钉钉工作台应用，以及是否选择了正确的钉钉集成。首次使用的员工还需要先完成账号绑定。

### 数字专家的视图一直显示加载中

确认部署中的 `/chatkit` 地址可以正常访问，并确认服务器使用的是当前 Xpert 版本要求的 ChatKit 包。

## 参考文档

* [钉钉教程中心](https://open.dingtalk.com/tutorial/)
* [创建企业内部应用](https://open.dingtalk.com/document/org/configure-orgapp)
* [获取用户个人信息](https://open.dingtalk.com/document/orgapp/tutorial-obtaining-user-personal-information)