用户信息对接
本页面介绍如何将业务系统中的用户信息对接到微语客服系统，以实现用户身份识别和个性化服务。
- 演示链接：用户信息对接演示
- 演示代码：
- 用户信息对接示例-React
- 用户信息对接示例-Vue
为什么需要用户信息对接？
在实际业务场景中，您可能希望：
- 在客服系统中识别已登录的用户身份
- 展示用户的真实头像和昵称
- 记录用户的聊天历史
- 关联业务系统中的用户数据
- 为不同用户提供个性化的客服体验
通过用户信息对接，可以帮助客服人员更好地了解用户情况，提供更精准的服务。
对接方法
微语客服系统支持通过配置参数传入用户信息。在初始化客服组件时，通过chatConfig配置项传入用户相关信息。
核心参数
以下是用户信息对接的核心参数：
chatConfig: {
// 必填参数
org: 'df_org_uid', // 您的组织ID
t: "1", // 会话类型
sid: 'df_wg_uid', // 会话ID
// 用户信息参数 - 这些是用户信息对接的关键
visitorUid: 'visitor_001', // 用户唯一ID，建议使用您业务系统中的用户ID
nickname: '访客小明', // 用户昵称
avatar: 'https://example.com/avatar.jpg', // 用户头像URL
mobile: '13800000000', // 用户手机号
email: 'user@example.com', // 用户邮箱
note: '备注信息', // 用户备注
// 自定义字段，可以传递任何附加信息（JSON字符串）
extra: JSON.stringify({
userType: 'vip', // 例如：用户类型
registerTime: '2025-01-01', // 例如：注册时间
// 任何其他您希望传递的信息
})
}
完整示例代码
下面是一个完整的用户信息对接示例，演示了如何根据不同用户切换身份信息：
import { useState } from 'react';
import { Button, Card, Typography, Space, Avatar } from 'antd';
import { BytedeskReact } from 'bytedesk-web/react';
import type { BytedeskConfig } from 'bytedesk-web';
const { Title, Paragraph } = Typography;
// 定义用户信息接口
interface UserInfo {
visitorUid: string;
nickname: string;
avatar: string;
mobile?: string; // 可选字段，根据需要添加
email?: string; // 可选字段，根据需要添加
note?: string; // 可选字段，根据需要添加
}
// 定义两个测试用户
const TEST_USERS = [
{
visitorUid: 'visitor_001',
nickname: '访客小明',
avatar: 'https://weiyuai.cn/assets/images/avatar/02.jpg',
mobile: '13800000000',
email: 'user@example.com'
note: '备注信息'
},
{
visitorUid: 'visitor_002',
nickname: '访客小红',
avatar: 'https://weiyuai.cn/assets/images/avatar/01.jpg',
mobile: '13800000001',
email: 'user2@example.com'
note: '备注信息'
}
];
const UserInfoDemo = () => {
// 当前选中的用户信息
const [currentUser, setCurrentUser] = useState(TEST_USERS[0]);
// 配置客服组件
const config = {
placement: 'bottom-right',
autoPopup: false,
marginBottom: 20,
marginSide: 20,
buttonConfig: {
show: false, // 隐藏默认按钮
},
bubbleConfig: {
show: false, // 隐藏气泡消息
},
chatConfig: {
org: 'df_org_uid', // 替换为您的组织ID
t: "1",
sid: 'df_wg_uid', // 替换为您的SID
// 传入当前用户信息 - 核心部分
visitorUid: currentUser.visitorUid,
nickname: currentUser.nickname,
avatar: currentUser.avatar,
mobile: currentUser.mobile,
email: currentUser.email,
note: currentUser.note,
// 自定义字段，可以传递任何字段
extra: JSON.stringify({
userType: 'normal',
registerDate: '2025-05-01'
})
},
locale: 'zh-cn',
};
// 切换用户信息
const handleSwitchUser = (user) => {
setCurrentUser(user);
};
// 打开聊天窗口
const handleShowChat = () => {
console.log("打开聊天 窗口");
(window).bytedesk?.showChat();
};
return (
<div style={{ padding: '24px' }}>
<Title level={2}>用户信息对接演示</Title>
<Paragraph>
本示例演示如何通过配置参数传入用户信息（visitorUid、nickname、avatar）到客服组件中。
点击下方按钮可以切换不同的用户信息。
</Paragraph>
<Card style={{ marginTop: '20px' }}>
<Space direction="vertical" size="large" style={{ width: '100%' }}>
<div>
<Title level={4}>当前用户信息：</Title>
<Space>
<Avatar src={currentUser.avatar} size={64} />
<div>
<Paragraph>用户ID: {currentUser.visitorUid}</Paragraph>
<Paragraph>昵称: {currentUser.nickname}</Paragraph>
</div>
</Space>
</div>
<Space>
<Button
type="primary"
onClick={() => handleSwitchUser(TEST_USERS[0])}
disabled={currentUser.visitorUid === TEST_USERS[0].visitorUid}
>
切换到访客小明
</Button>
<Button
type="primary"
onClick={() => handleSwitchUser(TEST_USERS[1])}
disabled={currentUser.visitorUid === TEST_USERS[1].visitorUid}
>
切换到访客小红
</Button>
</Space>
<div style={{ textAlign: 'center', marginTop: '16px' }}>
<Button type="primary" size="large" onClick={handleShowChat}>
咨询客服
</Button>
</div>
</Space>
</Card>
{/* 引入微语客服组件 */}
<BytedeskReact {...config} />
</div>
);
};
export default UserInfoDemo;
H5链接对接方法
除了组件集成方式外，微语客服系统还支持通过URL参数直接传递用户信息，适用于H5页面或快速集成场景。
H5链接格式
基本链接格式如下：
https://www.weiyuai.cn/chat/?org=您的组织ID&t=1&sid=会话ID&visitorUid=用户ID&nickname=用户昵称&avatar=头像URL&extra=附加信息JSON
各参数说明：
org: 您的组织IDt: 会话类型，通常为1sid: 会话IDvisitorUid: 用户唯一标识符nickname: 用户昵称(需URL编码)avatar: 用户头像URL(需URL编码)mobile: 用户手机号(可选，需URL编码)email: 用户邮箱(可选，需URL编码)note: 备注信息(可选，需URL编码)extra: 额外信息(JSON字符串，需URL编码)
示例代码
// 1. 准备用户基本信息
const userId = 'user12345';
const userNickname = '张三';
const userAvatar = 'https://example.com/avatar.jpg';
const userMobile = '13800000000'; // 可选
const userEmail = 'zhangsan@example.com'; // 可选
const userNote = '备注信息'; // 可选
// 2. 准备额外信息(可选)
const extraInfo = {
userType: 'vip',
registerTime: '2025-01-01',
memberLevel: '黄金会员',
};
// 3. URL编码处理
const encodedNickname = encodeURIComponent(userNickname);
const encodedAvatar = encodeURIComponent(userAvatar);
const encodedMobile = encodeURIComponent(userMobile);
const encodedEmail = encodeURIComponent(userEmail);
const encodedNote = encodeURIComponent(userNote);
const encodedExtra = encodeURIComponent(JSON.stringify(extraInfo));
// 4. 拼接完整URL
const chatUrl = `https://www.weiyuai.cn/chat/?org=df_org_uid&t=1&sid=df_wg_uid&visitorUid=${userId}&nickname=${encodedNickname}&avatar=${encodedAvatar}&mobile=${encodeMobile}&email=${ecodedEmail}¬e=${ecodedNote}&extra=${encodedExtra}`;
// 5. 使用该链接进行跳转或生成按钮
window.location.href = chatUrl;
// 或者创建一个链接
// <a href="${chatUrl}">联系客服</a>
使用场景
H5链接对接特别适用于：
- 移动端H5页面中"联系客服"按钮
- 用户个人中心或订单页面中的客服入口
- 邮件、短信或社交媒体中的客服链接
- 无法实现复杂JavaScript集成的场景
注意事项
- 所有URL参数都应进行正确编码，特别是中文字符
- 头像URL应使用HTTPS协议以确保安全
- 考虑在不同场景下添加不同的跟踪参数
- 尽量避免在URL中传递敏感用户信息
- 超长参数可能会导致某些浏览器截断URL，请适当控制参数长度
用户信息处理流程
- 登录状态检测：在应用中检测用户是否已登录
- 获取用户信息：从您的业务系统中获取当前登录用户的信息
- 配置参数：将用户信息配置到微语客服组件的
chatConfig中 - 实时更新：当用户登录状态或信息变化时，更新客服组件配置
最佳实践
- 唯一标识：确保每个用户的
visitorUid在您的系统中是唯一的，建议使用业务系统中的用户ID - 实时同步：当用户登录状态变化时，及时更新微语客服组件的用户信息
- 合理传参：在
extra字段中只传递必要的用户信息，避免传递敏感信息 - 头像优化：确保提供的 头像URL可以正常访问，考虑使用CDN加速
- 错误处理：添加适当的错误处理机制，确保即使用户信息获取失败也不会影响客服功能
高级功能
除了基本的用户信息对接外，您还可以：
- 动态切换用户：实现多账号切换功能，如示例中的不同用户切换
- 用户分组：通过
extra字段传递用户分组信息，实现不同分组用户的差异化服务 - 自定义字段：传递业务相关的自定义字段，为客服提供更多用户背景信息
- 会话控制：根据用户类型控制是否显示客服入口，例如对VIP用户显示特殊的客服入口
注意事项2
- 数据安全：避免在客户端传递用户敏感信息
- 兼容处理：对于未登录用户，可以使用临时ID作为
visitorUid，确保体验一致性 - 参数验证：确保传入的用户信息格式正确，特别是头像URL
- 更新机制：当用户信息变更时，需要重新初始化客服组件以应用新的用户信息