访客端开发文档
简介
微语访客端用于帮助开发者快速在自己的应用中集成在线客服功能，支持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" |
| channel | string | 接入渠道。优先使用后端 ChannelEnum 常量（如 WEB_VISITOR、WEB_FLOAT、WECHAT 等），也支持按业务扩展自定义渠道值 | 默认 HTTP_CHANNEL（通常为 WEB_VISITOR） |
| 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
进阶使用
相关功能
- 历史消息 - 了解如何加载和展 示历史聊天记录
- 商品信息对接 - 了解如何传递商品信息给客服
- 订单信息对接 - 了解如何传递订单信息给客服
- 用户信息对接 - 了解如何传递用户信息给客服
- 千人千面 - 了解如何根据用户等级提供差异化服务
- 国际化 - 了解如何支持多语言
channel 参数完整说明
channel 用于标识访客来源渠道，建议优先使用后端 ChannelEnum 中的标准常量。
使用规则
- 推荐使用大写下划线风格，如
WEB_VISITOR、WECHAT。 - 后端按不区分大小写方式解析（
equalsIgnoreCase），但仍建议统一大写，便于排查问题。 - 未传值时通常使用默认
HTTP_CHANNEL（一般映射为WEB_VISITOR）。 - 如需业务自定义，可使用
CUSTOM，并在业务侧约定扩展含义。
推荐值（访客端常见）
WEB_VISITOR: Web 访客页WEB_FLOAT: Web 悬浮窗WEB_H5: H5 页面WECHAT: 微信渠道WECHAT_MINI: 微信小程序IOS: iOS AppANDROID: Android AppFLUTTER_WEB/FLUTTER_IOS/FLUTTER_ANDROID: Flutter 多端
ChannelEnum 全量可选值
以下取值与后端 ChannelEnum 保持一致：
- 系统与Web:
SYSTEM,WEB,WEB_PC,WEB_H5,WEB_VISITOR,WEB_FLOAT,WEB_ADMIN - 移动与桌面:
IOS,ANDROID,ELECTRON,LINUX,MACOS,WINDOWS - Flutter:
FLUTTER,FLUTTER_WEB,FLUTTER_ANDROID,FLUTTER_IOS,FLUTTER_MACOS,FLUTTER_WINDOWS,FLUTTER_LINUX - UniApp:
UNIAPP,UNIAPP_WEB,UNIAPP_ANDROID,UNIAPP_IOS - 微信生态:
WECHAT,WECHAT_MINI,WECHAT_MP,WECHAT_WORK,WECHAT_KEFU,WECHAT_CHANNEL - 国内社媒:
XIAOHONGSHU,DOUYIN,KUAISHOU,BILIBILI,WEIBO,ZHIHU,TOUTIAO,DOUBAN - 国内电商:
TAOBAO,TMALL,JD,PINDUODUO,MEITUAN,ELEME,DIANPING - 企业办公:
DINGTALK,FEISHU,LARK,CUSTOM - 其他渠道:
EMAIL,SMS,PHONE - 海外Meta:
MESSENGER,INSTAGRAM,WHATSAPP - 海外社媒:
TWITTER,FACEBOOK,LINKEDIN,YOUTUBE,TIKTOK,PINTEREST,REDDIT,SNAPCHAT - 海外IM:
TELEGRAM,LINE,KAKAO,VIBER,SIGNAL,DISCORD,SLACK - 海外电商:
AMAZON,EBAY,SHOPIFY,LAZADA,SHOPEE - 测试:
TEST
示例
https://chat.example.com?org=df_org_uid&t=1&sid=df_wg_uid&channel=WEB_VISITOR