访客信息对接

本页说明微语系统中的访客概念，以及访客与注册用户的区别。

访客是什么

访客对应后端 VisitorEntity，主要用于承载客服会话中的访客身份。

典型特点：

• 默认无需登录
• 主要用于网站、H5、App、小程序等前端会话场景
• 不参与后台 RBAC 权限体系
• 不会被赋予管理员、客服、主管等角色
• 更关注会话身份、来源渠道、联系方式和扩展字段

常见字段包括：

• visitorUid：外部业务系统传入的访客标识
• nickname：昵称
• avatar：头像
• mobile：手机号
• email：邮箱
• note：备注
• channel：来源渠道
• status：在线状态
• tagList：标签列表
• customFieldList：自定义字段
• extra：扩展 JSON
• ip：访客 IP
• ipLocation：IP 归属地
• vipLevel：会员等级

注册用户与访客的区别

注册用户 User

注册用户对应后端 UserEntity。

特点：

• 需要登录
• 可加入组织
• 可分配角色
• 可拥有权限
• 可作为管理员、客服、主管、运营账号使用

访客 Visitor

访客对应后端 VisitorEntity。

特点：

• 默认无需登录
• 只用于会话身份识别
• 不参与后台权限控制
• 不具备管理员、客服等角色设置

一个常见误区

很多业务系统已经有自己的“注册会员”或“已登录用户”。接入微语客服时，这类业务用户通常会被映射为访客，而不是直接成为微语后台注册用户。

也就是说：

• 您的商城会员 id 可以传给 visitorUid
• 您的商城会员昵称可以传给 nickname
• 您的商城会员头像可以传给 avatar
• 这只是把会员映射为会话访客身份
• 这不会自动创建微语后台 UserEntity
• 这不会自动赋予任何后台权限

典型接入场景

场景一：匿名访客咨询

未登录用户访问商品详情页，点击“咨询客服”：

• 前端生成或获取一个稳定的 visitorUid
• 传入 nickname、avatar 等可选字段
• 打开客服会话

场景二：已登录会员咨询

业务系统中的登录会员进入会话：

• 使用会员 id 作为 visitorUid
• 使用会员昵称、头像填充访客资料
• 仍然按访客身份进入会话

场景三：后台客服接待

客服本人不是访客，而是后台注册用户：

• 客服账号属于 UserEntity
• 需要登录后台
• 需要被赋予客服角色与权限

字段建议

推荐至少传入以下字段：

• visitorUid：必传，且应稳定唯一
• nickname：建议传
• avatar：建议传

按业务需要可继续传入：

• mobile
• email
• note
• tagList
• extra

建议：

• visitorUid 使用业务系统中的用户 id、设备 id 或会员 id
• extra 中放扩展资料，例如会员等级、渠道来源、来源页面、设备信息
• 敏感信息如手机号、邮箱在展示给客服前可按业务要求脱敏

对接建议

• 如果您的目标是“让业务用户进入客服会话”，请优先使用访客体系
• 如果您的目标是“创建客服、管理员、运营账号”，请使用注册用户与角色权限体系
• 不要把 visitorUid 和后台 UserEntity.uid 混为一谈
• 不要默认认为业务会员登录后，就自动拥有微语后台权限