> ## 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.

# 变更记录

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

# 变更记录

> 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 回复回调和可选标签回调。