POST/api/public/widget/message
将访客的消息发送给聊天机器人并返回其回复——聊天小部件的核心端点。
发送 `widget_code`、`message`、`visitor_id`,以及从第二条消息起上一次响应中的 `session_id`。首次调用新对话时,将 `session_id` 留空或设为 `null`。响应在 `data` 对象中包含 `session_id`、回复文本 `response`,以及视情况包含按钮(`buttons`)、产品建议(`products`)和对话状态(`state`)。 需要带有嵌入令牌的 `X-Widget-Token` 请求头以及 `widget_code`。若令牌缺失,服务器以 401 `WIDGET_TOKEN_MISSING` 响应;若无效,则为 401 `WIDGET_TOKEN_INVALID`;来自未获批准域名的调用会收到 403 `WIDGET_ORIGIN_DENIED`,已停用的小部件为 404 `WIDGET_DISABLED`。若 `visitor_id` 缺失,服务器以 400 `VISITOR_ID_REQUIRED` 响应。 此调用不是幂等的:每次发送都会生成另一条访客消息和另一条回复。请求进行期间请锁定输入,不要自动重试。
概览
调用:POST /api/public/widget/message。该端点属于 Zentor App API 的“聊天小部件”分组。 该端点需要有效的 Widget 嵌入令牌。 该调用不是幂等的:每次成功调用都会再次触发该操作。 必填参数:widget_code (请求体), message (请求体), visitor_id (请求体)。 可选参数:session_id (请求体)。 已记录的错误情况:401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED。 下方的示例响应展示了 JSON 格式的成功响应结构。
身份验证与安全
组件嵌入令牌(请求头 X-Widget-Token)+ 来源(Origin)许可列表
幂等: 否
参数
widget_code(body, string,必填)— 来自您嵌入代码的小部件代码message(body, string,必填)— 访客消息的文本visitor_id(body, string,必填)— 由小部件生成并存储在浏览器中的访客 IDsession_id(body, string)— 来自上一次响应的会话 ID;首次调用新对话时为空或 `null`请求示例
{"widget_code":"...","message":"你好,Zentor App 能做什么?","visitor_id":"<UUID 或客户端生成的 ID>"}响应示例
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}错误代码
401 WIDGET_TOKEN_MISSING — 缺少 `X-Widget-Token` 请求头。401 WIDGET_TOKEN_INVALID — 嵌入令牌与小部件代码不匹配。400 VISITOR_ID_REQUIRED — `visitor_id` 字段缺失。已验证的行为
有效消息返回 200 并附带聊天机器人的回复;缺失或无效的令牌以及缺失的 `visitor_id` 返回文档中列出的错误代码。
聊天小部件
GET /api/public/widget/health对小部件服务进行简单的可用性检查。GET /api/public/widget/config/:widget_code返回小部件的公开配置(显示名称、欢迎语、设计、语言、语音功能),供浏览器初始化使用。GET /api/public/widget/history加载小部件对话此前的消息历史,例如在页面重新加载后使用。POST /api/public/widget/poll获取在某个时间点之后收到的消息——例如接管对话的员工所发的回复。POST /api/public/widget/rating存储访客对某次对话的评价(有帮助或没有帮助)。POST /api/public/widget/track记录小部件的匿名使用事件(例如“小部件已打开”),用于仪表盘中的分析。POST /api/public/widget/voice-transcribe如果小部件启用了语音功能,将访客的语音录音转换为文本(语音输入)。POST /api/public/widget/voice-speak如果语音功能已启用,将文本转换为语音(小部件中的语音输出)。