POST/api/public/widget/voice-transcribe
如果 Widget 啟用咗語音功能,就會將訪客嘅語音錄音轉換成文字(語音輸入)。
傳送`widget_code`,以及以`multipart/form-data`形式喺`audio`欄位嘅音訊資料。回應會包含識別到嘅文字,之後您就用`POST /api/public/widget/message`傳送呢段文字。Widget 設定入面嘅`voice_enabled`會顯示語音功能係否活躍。 如果`widget_code`缺失,伺服器就以400 `WIDGET_CODE_REQUIRED`回應;如果語音功能未啟用或者而家唔可以用,就係503 `VOICE_UNAVAILABLE`。語音功能由 Zentor 為您嘅 Widget 設定。
概覽
調用:POST /api/public/widget/voice-transcribe。此端點屬於 Zentor App API 的「聊天 Widget」組別。 此端點須提供有效的 Widget 嵌入權杖。 此調用並非冪等:每次成功調用均會再次觸發有關操作。 必填參數:widget_code (請求主體), audio (請求主體)。 已記錄的錯誤情況:400 WIDGET_CODE_REQUIRED, 503 VOICE_UNAVAILABLE。 下方的範例回應展示 JSON 格式成功回應的結構。
身份驗證同安全保障
Widget 嵌入權杖(Header X-Widget-Token)+ 來源(Origin)允許清單
冪等: 唔係
參數
widget_code(body, string,必填)— 嚟自您嵌入代碼嘅 Widget 代碼audio(body, binary,必填)— 作為檔案嘅音訊錄音(`multipart/form-data`)回應範例
{"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-speak如果語音功能已啟用,就會將文字轉換成語音(Widget 嘅語音輸出)。