> ## Documentation Index
> Fetch the complete documentation index at: https://beaver.voc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 整体对接流程

> Custom Ticket 接入 Shulex 的端到端链路

# 整体对接流程

> Custom Ticket 接入 Shulex 的端到端调用顺序与处理分支

Custom Ticket 的 Webhook 是**异步处理触发器**：Webhook 成功响应仅代表 Shulex 已接收请求，后续查询、AI 处理、回复和标签回调会在同一处理链路中继续执行。

## 正常回复与转人工时序

```mermaid theme={null}
sequenceDiagram
    participant T as 第三方工单系统
    participant S as Shulex

    T->>S: POST Webhook(ticketId, messageId)
    S-->>T: 200 已接收
    S->>T: GET queryUrl?ticketId=...
    T-->>S: 包装响应 { data: 工单详情 }
    S->>S: 分析工单并生成处理结果

    alt 正常 AI 回复
        S->>T: POST replyUrl(ticketId, messageId, reply, replyType)
        T-->>S: 2xx
        opt 已配置 tagsUrl
            S->>T: POST tagsUrl(ticketId, messageId, repliedTags)
            T-->>S: 2xx
        end
    else 转人工
        opt 已配置 tagsUrl
            S->>T: POST tagsUrl(ticketId, messageId, handoffTags[, handoffReason])
            T-->>S: 2xx
        end
    end
```

## 处理阶段说明

| 阶段       | 调用方向         | 发生时机                   | 关键点                                 |
| -------- | ------------ | ---------------------- | ----------------------------------- |
| 1. 触发    | 第三方 → Shulex | 新消息到达时                 | 至少传 `ticketId`；建议同时传 `messageId`    |
| 2. 接收确认  | Shulex → 第三方 | Webhook 校验通过后          | 仅表示请求已接收，不表示 AI 已回复                 |
| 3. 工单查询  | Shulex → 第三方 | 每次处理时                  | Shulex 调用 `queryUrl`，读取包装响应的 `data` |
| 4. 上下文处理 | Shulex       | 查询成功后                  | 使用完整消息历史、消息级附件和工单级附件                |
| 5. 回复回传  | Shulex → 第三方 | AI 生成回复后               | 调用 `replyUrl`；`messageId` 存在时会原样回传  |
| 6. 流程标签  | Shulex → 第三方 | 回复成功或转人工时且配置 `tagsUrl` | 回写 `repliedTags` 或 `handoffTags`    |
| 7. 幂等确认  | 第三方 → Shulex | 每个回调完成后                | 第三方应尽快返回 2xx，并按关联字段保证幂等             |

## 转人工规则

* 转人工分支不调用 `replyUrl`；第三方应以 `tagsUrl` 中的 `handoffTags` 作为转人工触发条件。
* 未配置 `tagsUrl` 时，Shulex 无法向第三方系统同步转人工标签。
* `addHandoffReasonTag=true` 时，`tags` 数组会在 `handoffTags` 后追加本次转人工原因。

## messageId 关联规则

| 场景                      | `messageId` 行为                                                               |
| ----------------------- | ---------------------------------------------------------------------------- |
| Webhook 提供 `messageId`  | Shulex 在 `replyUrl` 与 `tagsUrl` 回调中原样返回                                      |
| Webhook 未提供 `messageId` | 保持兼容；回调不包含空的 `messageId` 字段                                                  |
| 第三方幂等处理                 | 推荐使用 `ticketId + messageId + callbackType`；旧事件可退化为 `ticketId + callbackType` |

<Note>
  完整字段定义请查看 [Webhook 推送](/api/ticket-ai/open-api/webhook)、[工单查询](/api/ticket-ai/third-party-api/query)、[AI 回复回调](/api/ticket-ai/third-party-api/reply) 和 [标签回调](/api/ticket-ai/third-party-api/tags)。
</Note>