> ## 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 的 AI 推荐回复接口

# 推荐回复

> 第三方 → Shulex：基于工单上下文生成一条推荐回复

当第三方希望在自己的工单系统中获取 Shulex AI 生成的推荐回复时，可调用此接口。

## 调用地址与鉴权

在 Shulex 中创建 Custom Ticket 渠道后，从渠道配置页面复制推荐回复地址；请勿手动拼接 URL。

```http theme={null}
POST https://<host>/api_v2/intelli/custom-ticket/reply-suggestion/{xToken}/{channelId}
Content-Type: application/json
```

| 路径字段        | 类型     | 必填 | 说明                             |
| ----------- | ------ | -- | ------------------------------ |
| `xToken`    | string | 是  | Shulex 生成的渠道访问凭证               |
| `channelId` | number | 是  | Shulex 生成的 Custom Ticket 渠道 ID |

Shulex 会校验凭证与渠道归属同一账号，且该渠道必须为 Custom Ticket 渠道。请求体不支持覆盖 `xToken`、`channelId`、租户 ID 或 botId。

## 请求格式

```json theme={null}
{
  "subject": "Package damaged",
  "messages": [
    {
      "role": "USER",
      "content": "My package is damaged.",
      "attachments": ["https://example.com/package-photo.png"]
    }
  ],
  "targetLanguage": "ENGLISH",
  "contentFormat": "PLAIN"
}
```

### 请求字段

| 字段               | 类型     | 必填 | 默认值      | 说明                               |
| ---------------- | ------ | -- | -------- | -------------------------------- |
| `subject`        | string | 否  | 不传时为空    | 工单标题，用于补充回复上下文                   |
| `messages`       | array  | 是  | 无默认值     | 工单消息列表，至少一条                      |
| `targetLanguage` | string | 否  | 不传时保持原语言 | 目标语言；可写值见下方 `targetLanguage` 枚举表 |
| `contentFormat`  | string | 否  | `HTML`   | 输出格式；可写值见下方 `contentFormat` 枚举表  |
| `metadata`       | object | 否  | 不传时为空    | 业务元数据                            |

<Warning>
  `messages` 不能为空，且每条消息必须提供 `role`。`content` 可以为空，但空内容会降低推荐回复质量。`contentFormat` 不传时按 `HTML` 处理。
</Warning>

### `messages[]` 字段

| 字段            | 类型        | 必填 | 默认值    | 说明                                |
| ------------- | --------- | -- | ------ | --------------------------------- |
| `role`        | string    | 是  | 无默认值   | 消息角色；可写值见下方 `messages[].role` 枚举表 |
| `content`     | string    | 否  | 不传时为空  | 消息正文，允许为空                         |
| `attachments` | string\[] | 否  | 不传时无附件 | 消息附件地址列表                          |

### 枚举可写值

#### `messages[].role`

| 值           | 说明         |
| ----------- | ---------- |
| `SYSTEM`    | 系统消息       |
| `USER`      | 用户消息       |
| `ASSISTANT` | AI 或客服助手消息 |
| `FUNCTION`  | 函数调用消息     |
| `TOOL`      | 工具调用消息     |

#### `targetLanguage`

| 值                     | 说明           |
| --------------------- | ------------ |
| `AUTO`                | 自动识别或按默认策略处理 |
| `ENGLISH`             | 英语           |
| `CHINESE`             | 简体中文         |
| `TRADITIONAL_CHINESE` | 繁体中文         |
| `CANTONESE`           | 粤语           |
| `JAPANESE`            | 日语           |
| `FRENCH`              | 法语           |
| `GERMAN`              | 德语           |
| `SPANISH`             | 西班牙语         |
| `ARABIC`              | 阿拉伯语         |
| `RUSSIAN`             | 俄语           |
| `PORTUGUESE`          | 葡萄牙语         |
| `ITALIAN`             | 意大利语         |
| `KOREAN`              | 韩语           |
| `DUTCH`               | 荷兰语          |
| `INDONESIAN`          | 印尼语          |
| `TURKISH`             | 土耳其语         |
| `ROMANIAN`            | 罗马尼亚语        |
| `POLISH`              | 波兰语          |
| `PHILIPPINES`         | 菲律宾语         |
| `VIETNAMESE`          | 越南语          |
| `THAI`                | 泰语           |
| `SWEDISH`             | 瑞典语          |
| `NORWEGIAN`           | 挪威语          |
| `FINNISH`             | 芬兰语          |
| `DANISH`              | 丹麦语          |
| `CZECH`               | 捷克语          |
| `SLOVAK`              | 斯洛伐克语        |
| `ESTONIAN`            | 爱沙尼亚语        |
| `LITHUANIAN`          | 立陶宛语         |
| `LATVIAN`             | 拉脱维亚语        |
| `BULGARIAN`           | 保加利亚语        |
| `HUNGARIAN`           | 匈牙利语         |
| `CROATIAN`            | 克罗地亚语        |
| `SLOVENIAN`           | 斯洛文尼亚语       |
| `BENGALI`             | 孟加拉语         |
| `HEBREW`              | 希伯来语         |
| `GREEK`               | 希腊语          |
| `HINDI`               | 印地语          |

#### `contentFormat`

| 值          | 说明          |
| ---------- | ----------- |
| `MARKDOWN` | Markdown 格式 |
| `HTML`     | HTML 格式     |
| `PLAIN`    | 纯文本格式       |

#### 响应枚举字段

| 字段                   | 可返回值                                                                          |
| -------------------- | ----------------------------------------------------------------------------- |
| `data.language`      | 同 `targetLanguage`                                                            |
| `data.contentFormat` | `MARKDOWN`、`HTML`、`PLAIN`                                                     |
| `data.actionType`    | `MESSAGE`、`NOTHING`、`CONFUSED`、`STOPPED`、`TO_AGENT`、`NO_REPLY`、`HUMAN_REVIEW` |

## 响应格式

成功时返回 `ResponseResult` 包装结构。`data` 中不会返回模型用量 `usages`；枚举字段统一返回字符串。

### 响应字段

| 字段                       | 类型      | 说明                                         |
| ------------------------ | ------- | ------------------------------------------ |
| `code`                   | string  | 业务状态码；成功时为 `"200"`                         |
| `msg`                    | string  | 响应说明；成功时为 `"success"`                      |
| `success`                | boolean | 是否成功                                       |
| `data.content`           | string  | AI 生成的推荐回复内容                               |
| `data.language`          | string  | 回复语言，例如 `ENGLISH`、`CHINESE`                |
| `data.contentFormat`     | string  | 内容格式，例如 `MARKDOWN`、`HTML`、`PLAIN`          |
| `data.chatId`            | string  | AI 侧会话 ID                                  |
| `data.actionType`        | string  | AI 建议动作，例如 `MESSAGE`、`TO_AGENT`、`NO_REPLY` |
| `data.handoff`           | boolean | 是否建议转人工                                    |
| `data.reason`            | string  | AI 判断原因编码                                  |
| `data.reasonDescription` | string  | AI 判断原因说明                                  |

### 成功响应

```json theme={null}
{
  "code": "200",
  "msg": "success",
  "success": true,
  "data": {
    "content": "I'm sorry to hear that your package arrived damaged. Could you please share a photo of the package and the shipping label?",
    "language": "ENGLISH",
    "contentFormat": "PLAIN",
    "chatId": "chat-20260729-001",
    "actionType": "MESSAGE",
    "handoff": false,
    "reason": null,
    "reasonDescription": null
  }
}
```

<Note>
  `data.actionType="MESSAGE"` 表示可直接使用 `data.content` 作为推荐回复；其他动作值请结合 `handoff`、`reason` 和 `reasonDescription` 判断是否转人工或不回复。
</Note>

## 常见错误

| code    | 场景                      | 处理建议                                            |
| ------- | ----------------------- | ----------------------------------------------- |
| `"400"` | `xToken` 无效             | 从渠道配置页面重新复制完整地址                                 |
| `"400"` | 渠道不存在或不属于当前账号           | 确认 `xToken` 与 `channelId` 来自同一 Custom Ticket 渠道 |
| `"400"` | `messages` 为空           | 至少传入一条消息                                        |
| `"400"` | `messages[].role` 为空或非法 | 按枚举可写值传入大写角色                                    |
| `"400"` | 目标语言或格式非法               | 检查 `targetLanguage` 与 `contentFormat` 是否为支持值    |
| `"500"` | 推荐回复生成异常                | 保留请求时间和渠道信息并联系 Shulex 支持排查                      |

## 接入建议

* 始终按实际对话顺序传递 `messages`。
* 只传第三方希望 AI 参考的上下文，避免传入大量重复或无关消息。
* 使用 `metadata` 传递第三方工单 ID、优先级等扩展信息，方便后续排查。
* 不传 `contentFormat` 时按 `HTML` 处理，适合保留邮件或富文本结构。
* 对 `handoff=true` 或非 `MESSAGE` 的动作值做兜底处理。