Zentor App Logo
幫助中心整合產品配置器個人諮詢行業所有解決方案關於我哋
Zentor App›幫助›API 參考›聊天 Widget›/api/public/widget/message

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 生成並儲存喺瀏覽器嘅訪客 ID
session_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 嘅語音輸出)。

相關文章

將聊天小工具嵌入您的網站點樣攞到聊天 Widget 嘅嵌入代碼,並將佢加入您嘅網站。邊啲網域可以載入你個小工具?網域授權點樣保護您嘅聊天 Widget,以及點樣申請新增或者更改網域。
← 聊天 Widget
🇩🇪DE🇬🇧EN🇹🇷TR🇫🇷FR🇸🇦AR🇪🇸ES🇵🇹PT🇮🇹IT🇿🇦AF🇦🇿AZ🇧🇩BN🇨🇿CS🇩🇰DA🇮🇷FA🇫🇮FI🇵🇭FIL🇮🇪GA🇵🇾GN🇮🇱HE🇮🇳HI🇭🇷HR🇭🇺HU🇮🇩ID🇯🇵JA🇰🇿KK🇰🇷KO🌐KU🇱🇺LB🇲🇾MS🇳🇵NE🇳🇱NL🇷🇴RO🇷🇺RU🇺🇦UK🇵🇱PL🇵🇰UR🇻🇳VI🇨🇳ZH🇭🇰YUE🇮🇳TA🇰🇪SW🇳🇴NO🇸🇪SV🇸🇰SK🇸🇮SL🇦🇱SQ🇹🇭TH🇿🇦ZU🇿🇦XH🇿🇼SN🇿🇼ND