整体对接流程

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

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

正常回复与转人工时序

处理阶段说明

阶段	调用方向	发生时机	关键点
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`

完整字段定义请查看 Webhook 推送、工单查询、AI 回复回调和标签回调。

概述渠道配置