跳转到主要内容
DingTalk Trigger 用于把钉钉消息接入数字专家工作流，实现“用户在钉钉单聊或群聊中发消息，Xpert AI 路由到指定数字专家执行”的触发链路。 钉钉集成负责保存 AppKey、AppSecret、HTTP 回调或 Stream 模式配置；钉钉触发器负责把某个钉钉集成绑定到当前数字专家。

​
适用场景

  • 在钉钉单聊中向数字专家提问
  • 在钉钉群聊中 @ 机器人触发数字专家
  • 使用钉钉机器人作为内部问答、审批辅助、数据分析或运维助手入口
  • 用户连续发送多条短消息，需要先汇总再交给数字专家处理
  • 需要用钉钉卡片按钮继续会话，例如确认、拒绝或结束会话

​
关键配置

钉钉触发器当前包含：
  • enabled：是否启用触发器
  • integrationId：钉钉集成实例 ID（必填，可选择 HTTP 模式或 Stream 模式集成）
  • sessionTimeoutSeconds：会话超时时间，默认 3600 秒
  • summaryWindowSeconds：消息汇总时间，默认 0 秒
发布前会校验：
  1. 是否选择了有效的钉钉集成；
  2. 当前集成是否已绑定到其他数字专家；
  3. 触发器启用时，同一个钉钉集成同一时间只能绑定一个数字专家。

​
配置流程

  1. 先创建并测试 钉钉集成。
  2. 打开目标数字专家的工作流。
  3. 添加 DingTalk Trigger（钉钉触发器）。
  4. 选择刚创建的钉钉集成。
  5. 按需设置会话超时时间和消息汇总时间。
  6. 将触发器连接到后续 Agent、工具集或知识库节点。
  7. 发布数字专家工作流。
发布成功后，平台写入 integrationId -> xpertId 绑定。后续该集成收到的钉钉消息会路由到当前数字专家。

​
运行机制

  1. publish 阶段：
    • 校验钉钉集成是否存在；
    • 检查同一个集成是否已被其他数字专家占用；
    • 写入或更新钉钉触发器绑定；
    • 注册当前运行时回调。
  2. 消息到达阶段：
    • HTTP 模式由 POST /api/dingtalk/webhook/<integrationId> 接收加密回调；
    • Stream 模式由钉钉 Stream 长连接接收机器人消息和卡片回调；
    • 系统解析会话 ID、发送者 ID、消息内容、卡片动作和 sessionWebhook。
  3. 路由阶段：
    • 根据 integrationId 查找触发器绑定；
    • 群聊中只有 @ 机器人消息会进入处理；
    • 命中绑定后转换为数字专家输入。
  4. 执行阶段：
    • 运行时回调存在时直接推进当前工作流；
    • 回调不存在时进入持久化 handoff 队列；
    • 数字专家执行完成后通过钉钉上下文回复用户。

​
会话管理

钉钉插件会按集成、钉钉会话和发送者生成会话键，用于延续数字专家上下文。 路由优先级为：
  1. 已有会话绑定；
  2. 钉钉触发器绑定。
如果两者都不存在，消息无法找到处理目标。 sessionTimeoutSeconds 控制会话保留时间。超过该空闲时长后，用户下一次发送消息会开启新会话。 用户可以通过钉钉卡片上的结束会话动作清理当前会话状态。系统也提供 GET /api/dingtalk/action?action=dingtalk:end 这一类会话动作入口，用于卡片按钮回调后结束会话。

​
消息汇总

summaryWindowSeconds 用于处理连续短消息：
  • 设置为 0：每条消息立即触发数字专家。
  • 设置为大于 0：同一会话在该时间窗口内收到的消息先暂存，最终合并成一条输入发送给数字专家。
汇总期间如果又收到新消息，系统会刷新汇总版本，只分发最新版本，避免旧消息窗口重复触发。

​
常见问题

​
配置了触发器但不生效

检查：
  • 是否已经重新发布数字专家；
  • 触发器是否启用；
  • 触发器选择的集成是否是当前钉钉机器人实际使用的集成；
  • 是否有其他数字专家占用了同一个集成；
  • HTTP 模式回调地址是否通过校验；
  • Stream 模式状态页是否显示 connected。

​
单聊正常，群聊不触发

钉钉群聊默认只处理 @ 机器人的消息。请确认机器人已加入目标群，并且用户消息中确实 @ 了该机器人。

​
已有会话没有切到新专家

已有会话绑定优先级高于触发器绑定。需要结束当前会话后，再由新消息触发新的路由。

​
连续短消息被过早处理

适当增大 summaryWindowSeconds。如果希望每条消息都立即响应，保持默认值 0。

​
启动恢复策略

DingTalk Trigger 使用 bootstrap.mode = skip：
  • 启动时不重放 publish；
  • 依赖数据库中的触发器绑定恢复消息路由；
  • 外部钉钉消息再次到达时，会按持久化绑定继续分发。
这种方式适合由外部消息持续驱动的触发器，避免系统重启后重复注册运行时回调。

​
关联功能