AI 摘要主动生成

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

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

调用地址与鉴权

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

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 或渠道配置。

请求格式

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

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

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

{
  "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`

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

`messages[]` 字段

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

内容构造规则

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

{role}: {content}
{role}: {content}

空消息会跳过；未提供 role 时使用 unknown。
避免同时传入大量重复的 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	异步失败时的错误说明；成功时为空

同步成功响应

{
  "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
  }
}

异步受理响应

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

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

常见错误

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

接入建议

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

总览

Webhook

Open API

AI摘要主动生成

AI 摘要主动生成

调用地址与鉴权

请求格式

请求字段

`messages[]` 字段

内容构造规则

响应与异步模式

响应字段

同步成功响应

异步受理响应

常见错误

接入建议

​AI 摘要主动生成

​调用地址与鉴权

​请求格式

​请求字段

​messages[] 字段

​内容构造规则

​响应与异步模式

​响应字段

​同步成功响应

​异步受理响应

​常见错误

​接入建议

AI 摘要主动生成

调用地址与鉴权

请求格式

请求字段

`messages[]` 字段

内容构造规则

响应与异步模式

响应字段

同步成功响应

异步受理响应

常见错误

接入建议