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

# 钉钉触发器

`DingTalk Trigger` 用于把钉钉消息接入数字专家工作流，实现“用户在钉钉单聊或群聊中发消息，Xpert AI 路由到指定数字专家执行”的触发链路。

钉钉集成负责保存 AppKey、AppSecret、HTTP 回调或 Stream 模式配置；钉钉触发器负责把某个钉钉集成绑定到当前数字专家。

## 适用场景

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

## 关键配置

钉钉触发器当前包含：

* `enabled`：是否启用触发器
* `integrationId`：钉钉集成实例 ID（必填，可选择 HTTP 模式或 Stream 模式集成）
* `sessionTimeoutSeconds`：会话超时时间，默认 `3600` 秒
* `summaryWindowSeconds`：消息汇总时间，默认 `0` 秒

发布前会校验：

1. 是否选择了有效的钉钉集成；
2. 当前集成是否已绑定到其他数字专家；
3. 触发器启用时，同一个钉钉集成同一时间只能绑定一个数字专家。

## 配置流程

1. 先创建并测试 [钉钉集成](../integration/dingtalk-integration/)。
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`；
* 依赖数据库中的触发器绑定恢复消息路由；
* 外部钉钉消息再次到达时，会按持久化绑定继续分发。

这种方式适合由外部消息持续驱动的触发器，避免系统重启后重复注册运行时回调。

## 关联功能

* 钉钉集成配置： [钉钉集成](../integration/dingtalk-integration/)
* 触发器节点总览： [工作流触发器](../../workflow/trigger/)
* 插件触发器总览： [Trigger 插件](./)
* 源码地址： [xpert-plugins / dingtalk integration](https://github.com/xpert-ai/xpert-plugins/tree/main/xpertai/integrations/dingtalk)