POST/api/public/widget/voice-speak
如果语音功能已启用,将文本转换为语音(小部件中的语音输出)。
发送 `widget_code` 以及要朗读的文本到 `text`。响应包含用于在浏览器中播放的音频数据。为便于通过 `<audio>` 元素直接播放,同一路径也可通过 GET 使用。 若 `widget_code` 缺失,服务器以 400 `WIDGET_CODE_REQUIRED` 响应;若语音功能未启用或当前不可用,则为 503 `VOICE_UNAVAILABLE`。请等上一次播放结束后才开始新的播放。
概览
调用:POST /api/public/widget/voice-speak。该端点属于 Zentor App API 的“聊天小部件”分组。 该端点需要有效的 Widget 嵌入令牌。 该调用是幂等的:使用相同输入重复调用将返回相同结果。 必填参数:widget_code (请求体), text (请求体)。 已记录的错误情况:400 WIDGET_CODE_REQUIRED, 503 VOICE_UNAVAILABLE。 下方的示例响应展示了 JSON 格式的成功响应结构。
身份验证与安全
组件嵌入令牌(请求头 X-Widget-Token)+ 来源(Origin)许可列表
幂等: 是
参数
widget_code(body, string,必填)— 来自您嵌入代码的小部件代码text(body, string,必填)— 要朗读的文本响应示例
{"ok":false,"error":{"code":"VOICE_UNAVAILABLE","message":"Sprachfunktion aktuell nicht verfügbar."}}错误代码
400 WIDGET_CODE_REQUIRED — `widget_code` 字段缺失。503 VOICE_UNAVAILABLE — 此小部件未启用语音功能,或当前不可用。已验证的行为
缺失 `widget_code` 返回 400 `WIDGET_CODE_REQUIRED`,没有语音功能的小部件返回 503 `VOICE_UNAVAILABLE`。成功情况需要已启用语音功能的小部件。
聊天小部件
GET /api/public/widget/health对小部件服务进行简单的可用性检查。GET /api/public/widget/config/:widget_code返回小部件的公开配置(显示名称、欢迎语、设计、语言、语音功能),供浏览器初始化使用。POST /api/public/widget/message将访客的消息发送给聊天机器人并返回其回复——聊天小部件的核心端点。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如果小部件启用了语音功能,将访客的语音录音转换为文本(语音输入)。