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.
Shulex 收到 Webhook 触发后，会主动向你在 UI 中配置的 queryUrl 发起 GET 请求。
请求格式
GET {queryUrl}?ticketId={ticketId}
{queryAuthHeader}
GET https://example.com/open-api/tickets/detail?ticketId=order-2024-88001
Authorization: Bearer xxx
响应体格式
当前实现要求 queryUrl 返回包装结构，工单详情必须放在 data 字段中。旧版直接返回工单对象的格式已不兼容。
{
"code": 200,
"msg": "ok",
"data": {
"ticketId": "order-2024-88001",
"subject": "Package damaged upon arrival",
"customerEmail": "buyer@example.com",
"supportEmail": "support@yourstore.com",
"messages": [
{
"role": "user",
"content": "Hi, my package arrived damaged.",
"createdAt": "2026-04-23T09:30:00Z"
},
{
"role": "assistant",
"content": "Could you share a photo of the damage?",
"createdAt": "2026-04-23T09:32:00Z"
},
{
"role": "user",
"content": "Here is the photo.",
"createdAt": "2026-04-23T09:35:00Z"
}
],
"attachments": [
{
"name": "damage.jpg",
"url": "https://your-cdn.com/uploads/damage.jpg",
"contentType": "image/jpeg"
}
],
"customFields": {
"orderId": "ORD-20240420-001",
"trackingNumber": "1Z999AA10123456784",
"carrier": "UPS",
"orderStatus": "delivered"
}
},
"total": null
}
顶层包装字段
| 字段 | 类型 | 是否必填 | 说明 |
|---|
code | number/string | 建议必填 | 业务状态码，建议成功时返回 200 或 0 |
msg | string | 选填 | 业务提示信息 |
data | object | 必填 | 工单详情对象，Shulex 实际读取该字段 |
total | number/object | 选填 | 当前链路不使用，可返回 null |
data 工单字段
| 字段 | 类型 | 是否必填 | 说明 |
|---|
ticketId | string | 必填 | 工单唯一标识，需与 Webhook 中的 ticketId 一致 |
subject | string | 选填 | 工单主题 |
customerEmail | string | 选填 | 客户邮箱，会写入 Tars customer，并作为补充 metadata 透传 |
supportEmail | string | 选填 | 客服邮箱，会作为补充 metadata 透传 |
messages | array | 必填 | 完整消息历史 |
attachments | array | 选填 | 工单附件列表 |
customFields | object | 选填 | 工单业务字段 |
messages 数组字段
| 字段 | 类型 | 是否必填 | 说明 |
|---|
role | string | 必填 | user 或 assistant；非 assistant 会按 user 处理 |
content | string | 必填 | 消息文本内容 |
createdAt | string | 选填 | ISO 8601 时间，例如 2026-04-23T09:30:00Z |
attachments 数组字段
| 字段 | 类型 | 是否必填 | 说明 |
|---|
name | string | 选填 | 文件名 |
url | string | 必填 | Shulex 可访问的文件 URL |
contentType | string | 选填 | MIME 类型，例如 image/jpeg、application/pdf |
Shulex 对查询结果的使用方式
messages 是 AI 回复的主要上下文；其中 assistant 消息表示历史客服/AI 回复。customFields 会被转换为一条业务上下文消息，格式类似 [Business context: orderId=..., carrier=...]，并作为结构化 metadata 透传。attachments 当前为工单级附件，会挂到最近一条用户消息上进入 Tars Inbox。customerEmail 会写入 Tars customer 的 email 字段。customerEmail / supportEmail / customFields 会作为 supplemental metadata 透传给 Tars。
接入方建议
