常见问题

1. Webhook、Summary 地址需要自己拼接吗？

不需要。请在 Shulex 中创建渠道后，直接复制渠道配置页面展示的完整地址。地址中包含渠道访问凭证和渠道 ID，请勿用纯数字渠道 ID 替代。

2. Webhook body 可以直接传完整消息、不实现 queryUrl 吗？

不可以。Webhook 只用于触发处理，完整工单详情始终由 Shulex 通过渠道配置的 queryUrl 拉取。Webhook 至少需要传 ticketId，建议同时传 messageId。

3. queryUrl 可以直接返回工单对象吗？

不可以。响应必须使用包装结构，并将工单详情放在 data 中：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "ticketId": "order-2024-88001",
    "messages": []
  }
}

4. messageId 有什么作用？不传可以吗？

messageId 是本次触发消息的唯一标识，建议传递。存在时，Shulex 会在回复和标签回调中原样返回，可用于按 ticketId + messageId + callbackType 实现幂等处理；不传仍兼容原有接入方式。

5. messages[].role 支持哪些值？

推荐使用 user 表示客户消息，使用 assistant 表示客服或已发送的回复。其他值会按客户消息处理。请按真实对话顺序返回完整消息历史，避免 Shulex 将非客户最新消息误判为待回复消息。

6. 支持 HTML 正文和附件吗？

支持。消息 format 可为 text（默认）或 html；HTML 正文中的 URL 会被识别为附件。附件既可放在 messages[].attachments（推荐，用于明确归属），也可放在工单级 attachments。常见图片和 PDF 均可接入。所有附件 URL 必须能由 Shulex 服务端访问；同一 URL 在正文和显式附件中重复出现时仅保留一份。

7. customFields、customerEmail 和 supportEmail 会如何使用？

它们作为工单补充信息随工单上下文传递，不会自动伪造为一条对话消息。其中 customerEmail 可用于识别客户邮箱；supportEmail 和 customFields 可用于携带业务补充字段。

8. 是否支持 webhookSecret 或 X-Signature 签名校验？

当前不支持额外的 Webhook 签名字段。鉴权依赖 Shulex 提供的完整 Webhook 地址；服务端会校验访问凭证与渠道的归属关系。请妥善保管该地址，不要公开暴露。

9. 标签回调是 AI 自动生成的业务分类标签吗？

不是。标签回调用于同步流程状态：AI 回复成功后回传 repliedTags，转人工时回传 handoffTags。仅在渠道配置了 tagsUrl 时才会发送标签回调。若启用 addHandoffReasonTag，转人工时会在标签数组末尾附加本次转人工原因。

10. 转人工时还会调用 replyUrl 吗？

不会。转人工分支不会调用 replyUrl；如已配置 tagsUrl，Shulex 会通过 handoffTags 通知第三方系统进入人工处理流程。

11. AI Summary 是自动生成的吗？支持异步吗？

AI Summary 是独立能力，需要第三方主动调用 Summary 接口，不会由 Webhook、AI 回复或标签回调自动触发。默认同步返回摘要结果。只有渠道配置同时开启异步摘要并配置 Summary 回调地址时，请求才会先返回 PENDING，完成后再向配置的回调地址推送 COMPLETED 或 FAILED 结果。

​常见问题