> ## 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 对接常见问题 FAQ

# 常见问题

> Custom Ticket 对接中的常见问题与处理建议

<AccordionGroup>
  <Accordion title="1. Webhook、Summary 地址需要自己拼接吗？">
    不需要。请在 Shulex 中创建渠道后，直接复制渠道配置页面展示的完整地址。地址中包含渠道访问凭证和渠道 ID，请勿用纯数字渠道 ID 替代。
  </Accordion>

  <Accordion title="2. Webhook body 可以直接传完整消息、不实现 queryUrl 吗？">
    不可以。Webhook 只用于触发处理，完整工单详情始终由 Shulex 通过渠道配置的 `queryUrl` 拉取。Webhook 至少需要传 `ticketId`，建议同时传 `messageId`。
  </Accordion>

  <Accordion title="3. queryUrl 可以直接返回工单对象吗？">
    不可以。响应必须使用包装结构，并将工单详情放在 `data` 中：

    ```json theme={null}
    {
      "code": 0,
      "msg": "ok",
      "data": {
        "ticketId": "order-2024-88001",
        "messages": []
      }
    }
    ```
  </Accordion>

  <Accordion title="4. messageId 有什么作用？不传可以吗？">
    `messageId` 是本次触发消息的唯一标识，建议传递。存在时，Shulex 会在回复和标签回调中原样返回，可用于按 `ticketId + messageId + callbackType` 实现幂等处理；不传仍兼容原有接入方式。
  </Accordion>

  <Accordion title="5. messages[].role 支持哪些值？">
    推荐使用 `user` 表示客户消息，使用 `assistant` 表示客服或已发送的回复。其他值会按客户消息处理。请按真实对话顺序返回完整消息历史，避免 Shulex 将非客户最新消息误判为待回复消息。
  </Accordion>

  <Accordion title="6. 支持 HTML 正文和附件吗？">
    支持。消息 `format` 可为 `text`（默认）或 `html`；HTML 正文中的 URL 会被识别为附件。附件既可放在 `messages[].attachments`（推荐，用于明确归属），也可放在工单级 `attachments`。

    常见图片和 PDF 均可接入。所有附件 URL 必须能由 Shulex 服务端访问；同一 URL 在正文和显式附件中重复出现时仅保留一份。
  </Accordion>

  <Accordion title="7. customFields、customerEmail 和 supportEmail 会如何使用？">
    它们作为工单补充信息随工单上下文传递，不会自动伪造为一条对话消息。其中 `customerEmail` 可用于识别客户邮箱；`supportEmail` 和 `customFields` 可用于携带业务补充字段。
  </Accordion>

  <Accordion title="8. 是否支持 webhookSecret 或 X-Signature 签名校验？">
    当前不支持额外的 Webhook 签名字段。鉴权依赖 Shulex 提供的完整 Webhook 地址；服务端会校验访问凭证与渠道的归属关系。请妥善保管该地址，不要公开暴露。
  </Accordion>

  <Accordion title="9. 标签回调是 AI 自动生成的业务分类标签吗？">
    不是。标签回调用于同步流程状态：AI 回复成功后回传 `repliedTags`，转人工时回传 `handoffTags`。仅在渠道配置了 `tagsUrl` 时才会发送标签回调。

    若启用 `addHandoffReasonTag`，转人工时会在标签数组末尾附加本次转人工原因。
  </Accordion>

  <Accordion title="10. 转人工时还会调用 replyUrl 吗？">
    不会。转人工分支不会调用 `replyUrl`；如已配置 `tagsUrl`，Shulex 会通过 `handoffTags` 通知第三方系统进入人工处理流程。
  </Accordion>

  <Accordion title="11. AI Summary 是自动生成的吗？支持异步吗？">
    AI Summary 是独立能力，需要第三方主动调用 Summary 接口，不会由 Webhook、AI 回复或标签回调自动触发。

    默认同步返回摘要结果。只有渠道配置同时开启异步摘要并配置 Summary 回调地址时，请求才会先返回 `PENDING`，完成后再向配置的回调地址推送 `COMPLETED` 或 `FAILED` 结果。
  </Accordion>
</AccordionGroup>