POST/api/public/widget/voice-speak
如果語音功能已啟用,就會將文字轉換成語音(Widget 嘅語音輸出)。
傳送`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 嵌入權杖。 此調用屬冪等:以相同輸入重複調用,將傳回相同結果。 必填參數:widget_code (請求主體), text (請求主體)。 已記錄的錯誤情況:400 WIDGET_CODE_REQUIRED, 503 VOICE_UNAVAILABLE。 下方的範例回應展示 JSON 格式成功回應的結構。
身份驗證同安全保障
Widget 嵌入權杖(Header X-Widget-Token)+ 來源(Origin)允許清單
冪等: 係
參數
widget_code(body, string,必填)— 嚟自您嵌入代碼嘅 Widget 代碼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 未啟用語音功能,或者而家唔可以用。已驗證嘅行為
缺失`widget_code`會回傳400 `WIDGET_CODE_REQUIRED`,冇語音功能嘅 Widget 會回傳503 `VOICE_UNAVAILABLE`。成功情況需要已啟用語音功能嘅 Widget。
聊天 Widget
GET /api/public/widget/health對 Widget 服務進行簡單嘅可用性檢查。GET /api/public/widget/config/:widget_code回傳 Widget 嘅公開設定(顯示名稱、歡迎訊息、設計、語言、語音功能),供瀏覽器初始化使用。POST /api/public/widget/message將訪客嘅訊息傳送畀聊天機械人並回傳佢嘅回應——聊天 Widget 嘅核心端點。GET /api/public/widget/history載入 Widget 對話之前嘅訊息記錄,例如喺頁面重新載入之後使用。POST /api/public/widget/poll取得某個時間點之後收到嘅訊息——例如接手對話嘅職員所發嘅回應。POST /api/public/widget/rating儲存訪客對某次對話嘅評分(有幫助或者冇幫助)。POST /api/public/widget/track記錄 Widget 嘅匿名使用事件(例如「Widget 已開啟」),用於儀表板嘅分析。POST /api/public/widget/voice-transcribe如果 Widget 啟用咗語音功能,就會將訪客嘅語音錄音轉換成文字(語音輸入)。