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

# AI 回复回调

> Shulex → 第三方：回传 AI 生成的回复内容

# AI 回复回调

> Shulex → 第三方：回传生成的回复内容

当 Shulex 完成回复生成后，会调用渠道配置中的 `replyUrl`。调用时会携带渠道配置的 `replyAuthHeader`（如有）。

## 请求格式

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

## 默认 HTML 回调体

当 `replyFormat` 未配置或配置为 `HTML` 时：

```json theme={null}
{
  "ticketId": "order-2024-88001",
  "messageId": "msg-20260716-001",
  "reply": "<p>I'm sorry about the damaged package. I've arranged a replacement for you.</p>\n",
  "replyType": "html"
}
```

## TEXT 回调体

当 `replyFormat` 配置为 `TEXT` 时，Shulex 会将生成内容转为纯文本：

```json theme={null}
{
  "ticketId": "order-2024-88001",
  "messageId": "msg-20260716-001",
  "reply": "I'm sorry about the damaged package. I've arranged a replacement for you.",
  "replyType": "text"
}
```

## 字段说明

| 字段          | 类型     | 说明                                    |
| ----------- | ------ | ------------------------------------- |
| `ticketId`  | string | 对应原始工单 ID                             |
| `messageId` | string | 可选；仅当 Webhook 提供该值时原样返回               |
| `reply`     | string | Shulex 生成的回复内容                        |
| `replyType` | string | `html` 或 `text`，由渠道的 `replyFormat` 决定 |

<Note>
  `messageId` 未提供时，回调体不会包含空的 `messageId` 字段。
</Note>

## 期望响应

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

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

## 幂等与失败处理

* 建议使用 `ticketId + messageId + replyType` 作为幂等键；旧事件可退化为 `ticketId + replyType`。
* 回调处理应先持久化或入队，再快速返回 2xx，避免网络超时造成重复投递。
* `replyUrl` 调用失败会被视为本次回复处理失败，请确保接口可用且鉴权配置正确。
* 回调内容可能包含 HTML；如需存储或渲染，请按第三方系统的安全策略处理。