访客端开发文档
简介
微语访客端用于帮助开发者快速在自己的应用中集成在线客服功能，支持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