​

变更记录

Custom Ticket Open API 版本变更与兼容性说明

​

v1.2 · 2026-07-16

​

新增

• Webhook 支持可选 messageId，用于标识第三方本次推送的消息。
• replyUrl 与 tagsUrl 回调会在入站提供 messageId 时原样返回该字段。
• 工单查询响应支持消息级附件：messages[].attachments。
• 工单查询响应支持消息格式：messages[].format，可选值为 text（默认）与 html。
• 当 format=html 时，Shulex 会从消息正文中抽取 URL 作为附件；与显式附件 URL 重复时只保留一份。
• 渠道配置新增 addHandoffReasonTag；开启后，转人工标签回调会附带本次转人工原因。

​

兼容性

• messageId 为可选字段。既有 Webhook 不传该字段时，原有处理流程保持不变，回复和标签回调也不会新增空字段。
• messages[].format 与 messages[].attachments 均为可选字段。缺省 format 按 text 处理。
• addHandoffReasonTag 默认 false，既有渠道不会因升级而额外收到转人工原因标签。
• 顶层 attachments 仍然支持，用于没有明确消息归属的工单级附件。

​

文档修正

• 明确 queryUrl 必须返回 { code, msg, data } 包装结构。
• 修正 customFields 的说明：该字段作为 supplemental metadata 透传，不会自动虚构为一条对话消息。
• 明确 tagsUrl 用于已回复、转人工等流程标签，不是任意 AI 意图分类标签回调。

​

v1.1 · 2026-05-28

• 补充 Custom Ticket 的 UI 配置、Webhook 安全约束、包装查询响应和 AI Summary 文档。
• 支持 replyFormat 的 HTML 与 TEXT 两种回复格式。

​

v1.0

• 发布 Custom Ticket 基础对接能力：Webhook 触发、工单查询、AI 回复回调和可选标签回调。