推荐回复

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

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

调用地址与鉴权

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

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。

请求格式

{
  "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	否	不传时为空	业务元数据

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

`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 判断原因说明

成功响应

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

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

常见错误

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 的动作值做兜底处理。

总览

Webhook

Open API

推荐回复

推荐回复

调用地址与鉴权

请求格式

请求字段

`messages[]` 字段

枚举可写值

`messages[].role`

`targetLanguage`

`contentFormat`

响应枚举字段

响应格式

响应字段

成功响应

常见错误

接入建议

​推荐回复

​调用地址与鉴权

​请求格式

​请求字段

​messages[] 字段

​枚举可写值

​messages[].role

​targetLanguage

​contentFormat

​响应枚举字段

​响应格式

​响应字段

​成功响应

​常见错误

​接入建议

推荐回复

调用地址与鉴权

请求格式

请求字段

`messages[]` 字段

枚举可写值

`messages[].role`

`targetLanguage`

`contentFormat`

响应枚举字段

响应格式

响应字段

成功响应

常见错误

接入建议