> ## 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 摘要主动生成

> 第三方 → Shulex：独立的工单摘要生成能力

当第三方需要为指定工单生成摘要时，可主动调用此接口。它独立于 Webhook、AI 回复和标签回调，不会由这些流程自动触发。

## 调用地址与鉴权

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

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

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

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

## 请求格式

可直接传入已整理的文本：

```json theme={null}
{
  "ticketId": "ticket-2026-0716-001",
  "subject": "Package damaged",
  "content": "user: My package is damaged.\nassistant: Please share a photo of the package.",
  "language": "en"
}
```

也可以传入按对话顺序排列的消息列表：

```json theme={null}
{
  "ticketId": "ticket-2026-0716-001",
  "subject": "Package damaged",
  "messages": [
    {
      "role": "user",
      "content": "My package is damaged.",
      "createdAt": "2026-07-16T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Please share a photo of the package.",
      "createdAt": "2026-07-16T10:02:00Z"
    }
  ],
  "language": "en"
}
```

### 请求字段

| 字段         | 类型     | 必填 | 说明                             |
| ---------- | ------ | -- | ------------------------------ |
| `ticketId` | string | 建议 | 第三方工单 ID；会在响应和异步回调中原样返回        |
| `subject`  | string | 否  | 工单标题，用于帮助 Shulex理解摘要主题         |
| `content`  | string | 否  | 摘要输入正文；非空时优先于 `messages`       |
| `messages` | array  | 否  | 对话消息列表；仅在 `content` 为空时使用      |
| `language` | string | 否  | 期望的摘要输出语言，例如 `en`、`zh-CN`、`ja` |

<Warning>
  建议至少提供 `content` 或 `messages` 之一。两者均为空时，Shulex 仍会受理请求，但生成的摘要可能不可用。
</Warning>

### `messages[]` 字段

| 字段          | 类型     | 必填 | 说明                                                    |
| ----------- | ------ | -- | ----------------------------------------------------- |
| `role`      | string | 否  | 消息发送方，例如 `user`、`assistant`、`agent`；未传时按 `unknown` 处理 |
| `content`   | string | 建议 | 消息正文；空白内容不会进入摘要输入                                     |
| `createdAt` | string | 否  | 建议使用 ISO-8601 格式；不参与排序，以数组顺序为准                        |

### 内容构造规则

1. `content` 非空时，Shulex 直接使用它生成摘要。
2. `content` 为空且 `messages` 非空时，Shulex 按数组顺序拼接非空消息：

```text theme={null}
{role}: {content}
{role}: {content}
```

3. 空消息会跳过；未提供 `role` 时使用 `unknown`。
4. 避免同时传入大量重复的 `content` 与 `messages`，以免摘要输入冗余。

## 响应与异步模式

默认同步返回，成功时 `data.status` 为 `COMPLETED`，`summary` 即生成结果。

只有渠道配置同时开启“异步摘要”并配置 Summary 回调地址时，接口会立即返回 `PENDING`；完成后 Shulex 会向已配置的回调地址发送同一份 `data` 对象。回调地址和鉴权由渠道配置管理，不能通过本次请求指定。

### 响应字段

| 字段                  | 类型      | 说明                               |
| ------------------- | ------- | -------------------------------- |
| `code`              | string  | 业务状态码；成功时为 `"200"`               |
| `msg`               | string  | 响应说明；成功时为 `"success"`            |
| `success`           | boolean | 是否成功                             |
| `data.taskId`       | string  | 本次摘要任务 ID；可用于关联异步回调和排查           |
| `data.ticketId`     | string  | 请求中的 `ticketId`，原样返回             |
| `data.status`       | string  | `PENDING`、`COMPLETED` 或 `FAILED` |
| `data.summary`      | string  | 已完成时的摘要内容                        |
| `data.errorMessage` | string  | 异步失败时的错误说明；成功时为空                 |

### 同步成功响应

```json theme={null}
{
  "code": "200",
  "msg": "success",
  "success": true,
  "data": {
    "taskId": "4c0f98df5b534bf5a2cc34b25f23d911",
    "ticketId": "ticket-2026-0716-001",
    "status": "COMPLETED",
    "summary": "The customer reported package damage and was asked to provide a photo.",
    "errorMessage": null
  }
}
```

### 异步受理响应

```json theme={null}
{
  "code": "200",
  "msg": "success",
  "success": true,
  "data": {
    "taskId": "4c0f98df5b534bf5a2cc34b25f23d911",
    "ticketId": "ticket-2026-0716-001",
    "status": "PENDING",
    "summary": null,
    "errorMessage": null
  }
}
```

<Note>
  `code="200"` 且 `data.status="COMPLETED"` 表示摘要已生成；`PENDING` 仅表示异步任务已受理。
</Note>

## 常见错误

| code    | 场景            | 处理建议                             |
| ------- | ------------- | -------------------------------- |
| `"400"` | `xToken` 无效   | 从渠道配置页面重新复制完整地址                  |
| `"400"` | 渠道不存在或不属于当前账号 | 确认 `xToken` 与 `channelId` 来自同一渠道 |
| `"400"` | 渠道未完成摘要能力配置   | 在 Shulex 渠道配置中完成必要设置后重试          |
| `"500"` | 摘要生成异常        | 保留 `taskId` 并联系 Shulex 支持排查      |

## 接入建议

* 始终传递 `ticketId`，方便将响应或异步回调写回对应工单。
* 优先使用 `content`，当第三方已完成上下文筛选或脱敏时更可控。
* 使用 `messages` 时，确保数组已按实际对话顺序排序。
* 对异步回调按 `taskId` 幂等处理；当状态为 `FAILED` 时记录 `errorMessage`。