跳到主要内容

对接钉钉机器人

概述

通过对接钉钉机器人，可以把 DecideX 智能体发布到钉钉。配置完成后，用户可以在钉钉客户端向机器人提问，机器人会调用已绑定的 DecideX 智能体返回回答。

支持通过 Webhook 兼容模式 或 Stream 模式 接入钉钉机器人。两种方式任选其一，完成对应配置后，再按 [钉钉客户端提问](../../04-消费者使用指南/04-在企业 IM 中使用.md#ask-in-dingtalk) 验证。

接入方式钉钉消息接收方式DecideX 所需凭据回调地址
Webhook 兼容模式HTTP 模式Callback Signing Secret需要配置
Stream 模式Stream 模式同一应用的 Client ID、Client Secret无需配置公网回调地址

前提条件

开始前，请确认已具备以下条件：

  • 已创建并保存一个 DecideX 智能体。若只验证机器人是否接通，可先使用测试智能体；若需要回答业务问题，再为智能体绑定对应的 BI 资产、业务本体、参考文件或 Skill。
  • 当前账号具备编辑智能体和配置渠道入口的权限。
  • 已具备钉钉开发者平台的企业内部应用管理权限。
  • 需要使用机器人的成员已获得该智能体的发布授权。未授权成员即使完成钉钉账号绑定，也无法使用该智能体。

创建钉钉机器人

两种接入方式均需先准备钉钉企业内部应用及机器人能力，再进入对应模式的配置步骤。

  1. 以管理员身份登录 钉钉开发者平台 > 应用开发模块，创建一个新应用。
  2. 在应用详情页，点击「添加应用能力」，选择「机器人」能力并添加。
  3. 在机器人配置页面，打开「机器人配置」开关，配置机器人信息。
  4. 按下方选择的接入方式完成消息接收配置，并在「版本管理与发布」中发布版本，设置包含测试成员的可见范围。

方式一：Webhook 兼容模式

Webhook 兼容模式通过 HTTP 回调接收钉钉消息，经过签名校验后路由到对应智能体。使用此方式需配置回调地址和「Callback Signing Secret」。

在 DecideX 配置钉钉渠道入口

  1. 进入 DecideX，点击左侧导航「智能体」，找到需要接入钉钉的智能体，点击「设置」进入智能体配置页。

    进入智能体配置页

  2. 在「发布与集成 > 渠道入口」页面的「聊天平台」区域点击添加按钮，选择「钉钉」，再选择「Webhook 兼容模式」。

  3. 按页面提示填写 Callback Signing Secret。该字段来源于钉钉机器人开放平台应用凭证中的 Client Secret。

    8b11a19f204735c3a2e81db7b033092a_MD5

  4. 点击「添加频道」保存入口，复制页面显示的「钉钉回调地址」。同一 DecideX 环境中的钉钉 Agent 共用此回调地址，应以页面显示的地址为准。

    Webhook 方式添加频道与复制回调地址|400

    添加后入口显示「待回调激活」，继续完成下一节的 HTTP 回调配置。

    Webhook 入口待回调激活

配置钉钉机器人回调地址

  1. 返回钉钉开发者平台的机器人配置页面，将「消息接收模式」设为「HTTP 模式」，在「消息接收地址」中填写从 DecideX 复制的「钉钉回调地址」。

    Webhook 方式配置 HTTP 消息接收地址

  2. 保存配置后，进入「版本管理与发布」，创建新版本并重新发布应用，使消息接收配置生效。

  3. 按 [钉钉客户端提问](../../04-消费者使用指南/04-在企业 IM 中使用.md#ask-in-dingtalk) 发送测试消息，检查回调激活状态及实际回复。

方式二：Stream 模式

Stream 模式使用钉钉应用的 Client ID 和 Client Secret 建立长连接，无需配置公网回调地址。创建钉钉渠道时，接入方式默认选择「Stream」。

准备 Stream 应用配置

  1. 完成 创建钉钉机器人 中的应用与机器人准备工作。

  2. 在钉钉开放平台，将机器人的消息接收模式设为「Stream 模式」。

  3. 准备同一应用的「Client ID」和「Client Secret」。

  4. 配置应用所需权限，在「版本管理与发布」中发布版本，并确认可见范围包含测试成员。

在 DecideX 配置 Stream 入口

  1. 进入「智能体」，打开目标智能体的配置页，选择「渠道入口」。

  2. 在「聊天平台」区域点击添加按钮，选择「钉钉」，保持默认选择「Stream」。

  3. 向下滚动至「机器人入口」，填写同一钉钉应用的「Client ID」和「Client Secret」。该 Client ID 应只由当前入口使用。确认勾选「已启用」，点击「添加频道」。

    填写 Stream 应用凭据并添加频道|400

  4. 点击「添加频道」后，系统校验连接状态。连接正常时，「连接状态」显示「已连接」。若连接失败，检查应用凭据、网络及钉钉侧的 Stream 配置，并点击「测试连接」重新检查。确认连接正常后，点击「保存」。

    查看 Stream 连接状态与测试连接|400

  5. 保存后返回「聊天平台」列表，可以看到钉钉入口，状态显示「已启用」。

    聊天平台列表中的钉钉入口已启用

  6. 按 [钉钉客户端提问](../../04-消费者使用指南/04-在企业 IM 中使用.md#ask-in-dingtalk) 发送测试消息，验证机器人是否能正常回复。

注意

「已连接」仅表示长连接已建立，还需确认机器人消息接收模式、应用权限和发布状态，并验证实际消息回复。

在钉钉客户端使用与验证

完成接入配置后，按 [在钉钉中使用智能体](../../04-消费者使用指南/04-在企业 IM 中使用.md#ask-in-dingtalk) 完成账号绑定、单聊提问和群聊中 @ 机器人提问，并检查机器人是否正常回复。

常见问题

钉钉机器人没有响应

先检查两种模式共有的配置：

  • 确认钉钉应用已发布，且应用可见范围包含当前测试用户。
  • 确认钉钉机器人已开启，并已配置名称、图标和简介等基础信息。
  • 如果在群聊中提问，确认机器人已加入当前群，并按钉钉要求唤起机器人。

再按实际接入方式排查：

接入方式检查内容
Webhook 兼容模式钉钉侧使用「HTTP 模式」；消息接收地址与 DecideX 显示的回调地址一致；「Callback Signing Secret」填写正确；修改回调配置后已重新发布应用；入口已完成回调激活。
Stream 模式钉钉侧使用「Stream 模式」；「Client ID」与「Client Secret」来自同一应用；检查「连接状态」、应用权限和版本发布情况，再验证实际回复。

机器人能响应，但无法返回业务数据

请检查以下配置：

  • 当前钉钉用户是否已完成 DecideX 账号绑定。
  • 当前 DecideX 用户是否获得该智能体的发布授权。
  • 智能体是否已绑定正确的 BI 资产、业务本体或参考文件。
  • 当前用户是否拥有相关数据权限。
  • 提问内容是否超出该智能体的角色指令、数据范围或工具能力。

钉钉账号绑定链接打不开或绑定后仍无权限

请检查以下配置：

  • 打开绑定链接前，确认浏览器中已登录正确的 DecideX 账号。
  • 如果绑定后仍提示无权限，确认该 DecideX 账号已被加入智能体的「发布授权」范围。
  • 如果企业启用了统一身份映射，确认钉钉账号与企业账号已完成关联。
  • 如更换了测试用户，建议重新触发机器人消息，使用新生成的绑定链接完成绑定。

使用建议

  • 群聊机器人适合经营复盘、异常追踪、门店巡检、销售日报等多人协同场景。
  • 机器人绑定的智能体应有清晰职责，避免一个群机器人同时承担过多分析任务。
  • 对涉及经营数据的问题，应先在 DecideX 调试页验证回答质量，再开放到钉钉群。
  • 如需区分不同团队或业务线，可为不同群配置不同机器人或不同智能体。