POST/api/public/widget/message
將訪客嘅訊息傳送畀聊天機械人並回傳佢嘅回應——聊天 Widget 嘅核心端點。
傳送`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`,已經停用嘅 Widget 就係404 `WIDGET_DISABLED`。如果`visitor_id`缺失,伺服器就以400 `VISITOR_ID_REQUIRED`回應。 呢個呼叫唔係冪等嘅:每次傳送都會產生另一條訪客訊息同另一個回應。請求進行期間請鎖定輸入,唔好自動重試。
概覽
調用:POST /api/public/widget/message。此端點屬於 Zentor App API 的「聊天 Widget」組別。 此端點須提供有效的 Widget 嵌入權杖。 此調用並非冪等:每次成功調用均會再次觸發有關操作。 必填參數:widget_code (請求主體), message (請求主體), visitor_id (請求主體)。 選填參數:session_id (請求主體)。 已記錄的錯誤情況:401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED。 下方的範例回應展示 JSON 格式成功回應的結構。
身份驗證同安全保障
Widget 嵌入權杖(Header X-Widget-Token)+ 來源(Origin)允許清單
冪等: 唔係
參數
widget_code(body, string,必填)— 嚟自您嵌入代碼嘅 Widget 代碼message(body, string,必填)— 訪客訊息嘅文字visitor_id(body, string,必填)— 由 Widget 生成並儲存喺瀏覽器嘅訪客 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 — 嵌入權杖同 Widget 代碼唔相符。400 VISITOR_ID_REQUIRED — `visitor_id`欄位缺失。已驗證嘅行為
有效訊息會回傳200,並附帶聊天機械人嘅回應;缺失或者無效嘅權杖,以及缺失嘅`visitor_id`就會回傳文件列出嘅錯誤代碼。
聊天 Widget
GET /api/public/widget/health對 Widget 服務進行簡單嘅可用性檢查。GET /api/public/widget/config/:widget_code回傳 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 啟用咗語音功能,就會將訪客嘅語音錄音轉換成文字(語音輸入)。POST /api/public/widget/voice-speak如果語音功能已啟用,就會將文字轉換成語音(Widget 嘅語音輸出)。