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

# 标签回调

> Shulex → 第三方：回传流程标签（可选）

# 标签回调

> Shulex → 第三方：回传流程标签（可选）

当渠道配置了 `tagsUrl` 时，Shulex 会在回复成功或需要转人工时回传流程标签。调用时会携带渠道配置的 `replyAuthHeader`（如有）。

## 触发场景

| 场景             | 回调标签来源        | 默认值                 |
| -------------- | ------------- | ------------------- |
| 回复成功后          | `repliedTags` | `shulex_ai_replied` |
| 转人工，或前置规则命中转人工 | `handoffTags` | `transfer_to_agent` |

## 请求格式

```http theme={null}
POST {tagsUrl}
Content-Type: application/json
{replyAuthHeader}
```

### 回复成功示例

```json theme={null}
{
  "ticketId": "order-2024-88001",
  "messageId": "msg-20260716-001",
  "tags": ["shulex_ai_replied"]
}
```

### 转人工示例

```json theme={null}
{
  "ticketId": "order-2024-88001",
  "messageId": "msg-20260716-001",
  "tags": ["transfer_to_agent", "需要人工介入"]
}
```

## 字段说明

| 字段          | 类型     | 说明                      |
| ----------- | ------ | ----------------------- |
| `ticketId`  | string | 对应原始工单 ID               |
| `messageId` | string | 可选；仅当 Webhook 提供该值时原样返回 |
| `tags`      | array  | 需要第三方写入工单的流程标签列表        |

<Note>
  `tagsUrl` 用于同步“已回复”“转人工”等流程状态，不是任意业务分类标签回调。
</Note>

## 转人工标签

默认情况下，转人工只回传 `handoffTags`。当渠道配置 `addHandoffReasonTag=true` 时，Shulex 会在标签数组末尾追加本次转人工原因；该原因会随触发条件变化。

转人工分支不会调用 `replyUrl`，第三方应以 `handoffTags` 作为进入人工处理流程的依据。

## 期望响应

第三方成功处理后应尽快返回任意 2xx 状态码。例如：

```json theme={null}
{
  "code": 0,
  "message": "success"
}
```

## 幂等与失败处理

* 建议使用 `ticketId + messageId + tags` 作为幂等依据；未传 `messageId` 时可退化为 `ticketId + tags`。
* `tagsUrl` 未配置时不会发送标签回调。
* 标签回调失败不会撤销已完成的回复或转人工判断；仍建议记录失败并按第三方策略补偿。