GET/api/public/widget/history
加载小部件对话此前的消息历史,例如在页面重新加载后使用。
将 `widget_code`、`session_id` 和 `visitor_id` 作为查询参数传递。响应在 `data` 对象中按对话顺序包含 `messages` 列表,含 `role`(`user` 或 `assistant`)、`text` 和 `created_at`。此调用为只读且幂等。 需要带有嵌入令牌的 `X-Widget-Token` 请求头以及 `widget_code`。若令牌缺失,服务器以 401 `WIDGET_TOKEN_MISSING` 响应;若无效,则为 401 `WIDGET_TOKEN_INVALID`;来自未获批准域名的调用会收到 403 `WIDGET_ORIGIN_DENIED`,已停用的小部件为 404 `WIDGET_DISABLED`。若 `session_id` 或 `visitor_id` 缺失,服务器以 400 `PARAMS_REQUIRED` 响应。若会话已不再可用,请开始新的对话。
概览
调用:GET /api/public/widget/history。该端点属于 Zentor App API 的“聊天小部件”分组。 该端点需要有效的 Widget 嵌入令牌。 该调用是幂等的:使用相同输入重复调用将返回相同结果。 必填参数:widget_code (查询), session_id (查询), visitor_id (查询)。 已记录的错误情况:400 PARAMS_REQUIRED。 下方的示例响应展示了 JSON 格式的成功响应结构。
身份验证与安全
组件嵌入令牌(请求头 X-Widget-Token)+ 来源(Origin)许可列表
幂等: 是
参数
widget_code(query, string,必填)— 来自您嵌入代码的小部件代码session_id(query, string,必填)— 来自 `message` 响应的对话会话 IDvisitor_id(query, string,必填)— 由小部件生成并存储在浏览器中的访客 ID响应示例
{"ok":true,"data":{"messages":[{"role":"user","text":"你好...","created_at":"..."},{"role":"assistant","text":"...","created_at":"..."}]}}错误代码
400 PARAMS_REQUIRED — `session_id` 或 `visitor_id` 缺失。已验证的行为
现有会话返回 200 并附带消息历史;缺失参数返回 400 `PARAMS_REQUIRED`。
聊天小部件
GET /api/public/widget/health对小部件服务进行简单的可用性检查。GET /api/public/widget/config/:widget_code返回小部件的公开配置(显示名称、欢迎语、设计、语言、语音功能),供浏览器初始化使用。POST /api/public/widget/message将访客的消息发送给聊天机器人并返回其回复——聊天小部件的核心端点。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如果语音功能已启用,将文本转换为语音(小部件中的语音输出)。