Skip to main content
本文介绍如何把已发布的 Xpert 数字专家添加到钉钉工作台。 请根据使用方式选择其中一种配置方法：
  • 使用 Xpert 线上系统：系统管理员已经配置好钉钉 SSO，你需要为自己的数字专家创建钉钉 H5 微应用和钉钉集成。
  • 使用本地或私有化部署的 Xpert：管理员先配置钉钉 SSO，然后数字专家创建者再配置自己的钉钉 H5 微应用。
本文配置的是钉钉 H5 工作台应用。如果你需要在钉钉群中通过机器人收发消息，请参考钉钉机器人集成。

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

这种方式适用于 Xpert 管理员已经完成钉钉 SSO 配置的线上系统。 钉钉 SSO 由管理员统一配置。你仍然需要创建自己的钉钉 H5 微应用，并在 Xpert 中为这个微应用新建钉钉集成。
钉钉 SSO 集成和 H5 微应用集成是两项独立配置。创建 H5 微应用集成时，请使用自己微应用的 Client ID、Client Secret，以及该微应用所属企业的 Corp ID。

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

钉钉 SSO 回调地址配置在管理员维护的 SSO 应用中，普通数字专家创建者通常没有权限添加。这个回调地址不需要添加到你自己的 H5 微应用中。
  1. 向 Xpert 管理员确认当前系统的完整 SSO 回调地址，例如：
  1. 请管理员将该地址加入钉钉 SSO 应用的登录回调地址列表。
  2. 等待管理员确认配置完成后，再继续下面的步骤。
如果回调地址使用临时域名，例如 *.example.com，域名发生变化后需要联系管理员重新添加。正式使用时建议配置固定的 HTTPS 域名。

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

  1. 登录钉钉开放平台。
  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 地址

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

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

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

​
第 7 步：在钉钉中验收

  1. 使用可见范围内的员工账号登录钉钉。
  2. 从工作台打开应用。
  3. 确认页面显示正确的数字专家。
  4. 在输入框中发送一条消息。
  5. 确认数字专家能够正常回复。
第一次使用时，如果页面提示登录或绑定账号，请按提示完成一次绑定。后续可以直接从钉钉工作台进入。

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

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

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

为 Xpert 准备一个钉钉客户端可以访问的 HTTPS 域名，例如：
部署完成后，先在普通浏览器中确认该地址可以正常打开。

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

在 Xpert 的部署环境变量中配置实际域名：
应用配置后，重新部署或重启 Xpert 服务。
正式部署不需要修改前端的 project.json，也不需要把线上域名加入开发服务器的 allowedHosts。

​
第 3 步：安装钉钉插件

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

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

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

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

  1. 打开 Xpert 的 系统设置 > 系统集成。
  2. 新建钉钉登录或钉钉 SSO 集成。
  3. 填写上一步记录的 Client ID 和 Client Secret。
  4. 保存集成。
  5. 复制页面显示的回调地址；如果需要手动填写，请使用：
  1. 回到钉钉开放平台，将该地址添加为应用的登录回调地址。
一个 Xpert 租户只配置一套有效的钉钉 SSO。 如果 Xpert 管理员没有钉钉 SSO 应用的管理权限，请将完整回调地址发送给该钉钉应用的管理员，由应用管理员添加。
如果部署使用的公网地址会变化，变化后需要同步更新钉钉 SSO 应用中的回调地址。正式使用时建议配置固定的 HTTPS 域名。

​
第 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 地址，例如：
  1. 回到自己 H5 微应用的配置页面。
  2. 将该地址填写为应用首页地址。
  3. 将 xpert.example.com 加入应用的安全域名或 JSAPI 安全域名。
  4. 再次确认应用可见范围。
  5. 发布应用版本。
  6. 将应用添加到企业工作台。

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

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

​
第 11 步：验收

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

​
常见问题

​
钉钉中打不开页面

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

​
工作台中找不到应用

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

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

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

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

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

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

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

​
参考文档