GET/api/public/widget/history

載入 Widget 對話之前嘅訊息記錄,例如喺頁面重新載入之後使用。

將`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`,已經停用嘅 Widget 就係404 `WIDGET_DISABLED`。如果`session_id`或者`visitor_id`缺失,伺服器就以400 `PARAMS_REQUIRED`回應。如果工作階段已經唔再可用,請開始一個新對話。

概覽

調用:GET /api/public/widget/history。此端點屬於 Zentor App API 的「聊天 Widget」組別。 此端點須提供有效的 Widget 嵌入權杖。 此調用屬冪等:以相同輸入重複調用,將傳回相同結果。 必填參數:widget_code (查詢), session_id (查詢), visitor_id (查詢)。 已記錄的錯誤情況:400 PARAMS_REQUIRED。 下方的範例回應展示 JSON 格式成功回應的結構。

身份驗證同安全保障

Widget 嵌入權杖(Header X-Widget-Token)+ 來源(Origin)允許清單

冪等: 係

參數

widget_code(query, string,必填)— 嚟自您嵌入代碼嘅 Widget 代碼
session_id(query, string,必填)— 嚟自`message`回應嘅對話工作階段 ID
visitor_id(query, string,必填)— 由 Widget 生成並儲存喺瀏覽器嘅訪客 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`。

聊天 Widget

GET /api/public/widget/health對 Widget 服務進行簡單嘅可用性檢查。GET /api/public/widget/config/:widget_code回傳 Widget 嘅公開設定(顯示名稱、歡迎訊息、設計、語言、語音功能),供瀏覽器初始化使用。POST /api/public/widget/message將訪客嘅訊息傳送畀聊天機械人並回傳佢嘅回應——聊天 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 嘅語音輸出)。

相關文章

← 聊天 Widget