訪客端開發文檔
簡介
微語訪客端用於幫助開發者快速在自己的應用中整合線上客服功能，支援Web、iOS、Android、微信小程序等多平台接入。
訪客端聊天介面
訪客端聊天介面（ChatBox）是使用者與客服互動的核心元件，它提供了豐富的功能以確保良好的溝通體驗。
主要功能
-
訊息展示
- 支援多種訊息類型：文字、圖片、檔案、視訊、商品資訊等
- 訊息氣泡顯示發送狀態：發送中、發送成功、發送失敗等
- 訊息時間戳顯示
- 支援富文字內容渲染
-
訊息輸入
- 文字輸入與發送
- 表情選擇器
- 圖片上傳功能
- 檔案上傳功能
- 輸入預覽（對方可見正在輸入的內容）
-
機器人互動
- 智能機器人應答
- 常見問題推薦
- 相似問題推薦
- 機器人結果評價（有用/無用反饋）
- 機器人對話轉人 工客服
-
留言功能
- 非工作時間或客服不在線時的留言提交
- 支援文字和圖片留言
- 留言狀態追蹤
- 留言回覆展示
-
服務評價
- 客服主動邀請評價
- 使用者主動評價
- 評分與評價內容提交
- 問題是否解決的標記
-
智能提示
- 即時輸入建議
- 輸入關鍵詞相關問題推薦
- 熱門問題展示
-
訊息操作
- 訊息複製
- 圖片預覽
- 檔案下載
- 上下文選單（右鍵選單）
網路通訊
聊天介面使用兩種通訊方式：
-
WebSocket (STOMP) - 用於即時訊息通訊
- 訊息發送與接收
- 狀態更新
- 輸入預覽
- 線上狀態維護
-
HTTP請求 - 用於非即時操作
- 會話初始化
- 歷史訊息取得
- 檔案上傳
- 評價提交
- 留言提交
客戶化配置
訪客端支援多種客戶化配置：
-
主題設定
- 明暗模式切換
- 自訂導航欄顏色
- 自訂背景色和文字顏色
-
多語言支援
- 內建多語言支援
- 可選語言：中文、英文等
-
介面佈局
- 導航欄顯示/隱藏
- 寬窄螢幕自適應
- 右側面板顯示/隱藏
-
功能開關
- 留言功能開關
- 評價功能開關
- 機器人功能開關
- 檔案上傳開關
上下文溝通
為了提供更智能的服務，訪客端會收集並利用以下上下文資訊：
-
訪客資訊
- UID
- 暱稱
- 頭像
- VIP級別
- 自訂欄位
-
瀏覽資訊
- 瀏覽器類型
- 作業系統
- 裝置資訊
- 來源頁面
- 頁面標題
-
會話資訊
- 會話ID
- 會話類型
- 歷史訊息
技術實現細節
-
狀態管理
- 使用Zustand管理全域狀態
- 訊息列表、訪客資訊等狀態集中管理
-
訊息處理
- 訊息發送佇列
- 訊息狀態追蹤
- 訊息重發機制
-
即時預覽
- 使用防抖(debounce)技術優化即時預覽
- 輸入內容智能建議
-
網路容錯
- WebSocket斷線重連
- 訊息發送失敗重試
- 網路錯誤提示
-
安全處理
- 訊息內容安全檢測
- XSS防護
- 敏感資訊過濾
參數配置
ChatBox元件支援多種參數配置：
| 參數名 | 類型 | 說明 | 預設值 |
|---|---|---|---|
| org | string | 企業UID | - |
| t | string | 會話類型(0:一對一; 1:工作組, 2:機器人, 16:歷史) | "1" |
| sid | string | 會話ID(客服UID/工作組UID/機器人UID) | - |
| lang | string | 語言設定("zh-cn"/"zh-tw"/"en") | "zh-cn" |
| mode | string | 主題模式(light/dark/system) | "system" |
| backgroundColor | string | 自訂導航背景色 | - |
| textColor | string | 自訂導航文字顏色 | - |
| referer | string | 來源頁面 | - |
| title | string | 頁面標題 | - |
| url | string | 頁面URL | - |
| navbar | boolean | 是否顯示導航欄，0表示隱藏 | true |
| navbarTheme | string | 導航欄主題 | - |
| visitorUid | string | 自訂訪客唯一ID | 自動產生 |
| nickname | string | 自訂訪客暱稱 | "訪客" |
| avatar | string | 自訂訪客頭像 | 預設頭像 |
| vipLevel | string | 訪客VIP等級 | "0" |
| extra | string | 自訂訪客額外資訊（JSON格式） | - |
| loadHistory | string | 是否自動載入歷史聊天記錄，值為"1"時載入，其他值不載入，詳見歷史訊息 | - |
| goodsInfo | string | 商品資訊（JSON格式），詳見商品資訊對接 | - |
| orderInfo | string | 訂單資訊（JSON格式），詳見訂單資訊對接 | - |
| userInfo | string | 使用者資訊（JSON格式），詳見使用者資訊對接 | - |
常見問題
如何跟已有使用者系統對接？將訪客資訊傳遞給客服端？
可以透過以下方式將已有使用者系統的資訊傳遞給客服端：
-
URL參數傳遞：在初始化聊天視窗時，透過URL參數傳遞使用者資訊
https://chat.example.com?visitorUid=user123&nickname=張三&avatar=https://example.com/avatar.jpg&vipLevel=2