用户数据对接教程

客服系统可用于电商、金融、通讯、公益等多种场景。在这些场景中，客服系统承担着连接用户与平台的重要角色：既帮助平台识别访客、理解诉求，也帮助用户获得一致、可信赖的服务体验，从而提升品牌认知、满意度与粘性。

在实际对接中，常见需求是：业务系统里已经登录的用户，在发起咨询时，客服端要能识别「是谁在咨询」，并展示其用户标识、头像、昵称，必要时还可同步订单等业务信息。为此，系统预留了用户数据对接能力：在网页脚本或访问地址中传入相应参数，即可完成对接。

用户数据对接教程

客服系统支持在网页中通过 kf.js 初始化访客身份、用户属性与咨询上下文。客服人员可在会话详情中查看这些信息，更快了解访客及其当前业务场景。

本文适用于新版 kf.js：使用 KFVisitor.init(config) 初始化，不再使用旧版 window._kefu 配置方式。

一、快速接入

先加载客服脚本，再调用 KFVisitor.init()：

<script src="https://kefu.99kf.com/static/js/kf.js"></script>
<script>
  window.kfVisitor = KFVisitor.init({
    businessId: '您的企业ID',
    groupId: 0,
    baseUrl: 'https://kefu.99kf.com',

    visitor: {
      uid: 'user_10001',
      nickname: '张三',
      avatar: 'https://example.com/avatar.jpg'
    }
  });
</script>

配置项	说明	是否必填
`businessId`	企业 ID（原 `bid`）	是
`groupId`	客服分组 ID，默认 `0`	否
`baseUrl`	客服系统地址；未填写时，自动取 `kf.js` 所在域名	否
`visitor.uid`	业务系统中的用户唯一标识	否
`visitor.nickname`	用户昵称	否
`visitor.avatar`	用户头像完整 URL	否

建议业务系统已登录时始终传入稳定的 visitor.uid。同一个 businessId + uid 会被识别为同一访客。

二、完整初始化示例

以下示例同时传入用户基本资料、长期用户属性和本次咨询的业务上下文：

<script src="https://kefu.99kf.com/static/js/kf.js"></script>
<script>
  window.kfVisitor = KFVisitor.init({
    // 基础配置
    businessId: 'Z3SmMhtO',
    groupId: 0,
    baseUrl: 'https://kefu.99kf.com',
    displayMode: 'floating',

    // 外观与启动行为
    theme: {
      primaryColor: '#1677ff'
    },
    preconnect: true,
    autoOpenDelay: 3,

    // 访客身份与长期属性
    visitor: {
      uid: 'user_10001',
      nickname: '张三',
      avatar: 'https://example.com/avatar.jpg',
      attributes: [
        {
          key: 'member_level',
          label: '会员等级',
          type: 'text',
          value: '黄金会员',
          editable: false
        },
        {
          key: 'mobile',
          label: '手机号',
          type: 'text',
          value: '138****8888',
          editable: false
        }
      ]
    },

    // 本次咨询的业务上下文
    contexts: [
      {
        key: 'order_20260714001',
        type: 'order',
        title: '订单 #20260714001',
        url: 'https://example.com/orders/20260714001',
        fields: [
          {
            key: 'order_status',
            label: '订单状态',
            type: 'text',
            value: '待发货'
          },
          {
            key: 'pay_amount',
            label: '实付金额',
            type: 'text',
            value: '299.00 元'
          }
        ]
      }
    ]
  });
</script>

三、访客基本资料

基本资料放在 visitor 中：

visitor: {
  uid: 'user_10001',
  nickname: '张三',
  avatar: 'https://example.com/avatar.jpg'
}

字段	说明
`uid`	业务系统用户唯一 ID。建议使用用户主键、会员 ID 等稳定值。
`nickname`	客服端展示的访客昵称。
`avatar`	头像地址，建议使用可公开访问的 HTTPS 完整地址。

未传 uid 时，系统会为访客创建临时标识；访客清理浏览器数据、更换设备或浏览器后，可能被识别为新访客。

四、用户属性

用户属性适合传递相对稳定、需要长期展示的信息，例如会员等级、手机号掩码、用户标签、注册时间等。

visitor: {
  uid: 'user_10001',
  nickname: '张三',
  attributes: [
    {
      key: 'member_level',
      label: '会员等级',
      type: 'text',
      value: '黄金会员',
      editable: false
    },
    {
      key: 'registered_at',
      label: '注册时间',
      type: 'text',
      value: '2026-01-01',
      editable: false
    }
  ]
}

每个属性包含以下字段：

字段	说明
`key`	属性唯一键，只能使用小写字母、数字和下划线，且必须以小写字母开头。
`label`	客服端显示名称，例如“会员等级”。
`type`	属性类型，默认 `text`。
`value`	属性值，只能为字符串、数字、布尔值或 `null`。
`editable`	是否允许客服侧编辑，默认 `false`。

限制：

最多 50 个属性。
同一批属性中，key 不可重复。
key 最长 64 个字符。
label 必填。

动态更新用户属性

初始化后，可在用户登录、会员等级变化等场景中更新属性：

window.kfVisitor.updateVisitorAttributes([
  {
    key: 'member_level',
    label: '会员等级',
    type: 'text',
    value: '钻石会员',
    editable: false
  },
  {
    key: 'points',
    label: '积分',
    type: 'number',
    value: 2580,
    editable: false
  }
]);

默认使用 merge 模式：同 key 属性会更新，不存在的属性会新增，其余已有属性保留。

如需用本次数据完全覆盖原有属性，使用 replace 模式：

window.kfVisitor.updateVisitorAttributes([
  {
    key: 'member_level',
    label: '会员等级',
    type: 'text',
    value: '钻石会员'
  }
], {
  mode: 'replace'
});

五、咨询上下文

咨询上下文用于描述“访客这次为什么来咨询”，适合传递订单、商品、售后单、账单、工单等当前业务对象。

contexts: [
  {
    key: 'order_20260714001',
    type: 'order',
    title: '订单 #20260714001',
    url: 'https://example.com/orders/20260714001',
    fields: [
      {
        key: 'order_status',
        label: '订单状态',
        type: 'text',
        value: '待发货'
      },
      {
        key: 'amount',
        label: '订单金额',
        type: 'text',
        value: '299.00 元'
      }
    ]
  }
]

上下文字段说明：

字段	说明
`key`	当前上下文唯一键，例如订单号、工单号。
`type`	上下文类型，例如 `order`、`product`、`ticket`，默认 `custom`。
`title`	客服端显示标题，例如“订单 #20260714001”。
`url`	可选，业务详情页地址。
`fields`	要展示的字段列表。

每个 fields 项包含：

字段	说明
`key`	字段唯一键。
`label`	显示名称。
`type`	字段类型，默认 `text`。
`value`	字段值，只能为字符串、数字、布尔值或 `null`。

限制：

最多 20 个上下文。
每个上下文最多 50 个字段。
contexts 中的 key 不可重复。
同一个上下文内，字段 key 不可重复。

动态更新咨询上下文

例如用户切换订单、进入商品详情或提交售后申请后，可更新上下文：

window.kfVisitor.setContexts([
  {
    key: 'after_sale_20260714001',
    type: 'after_sale',
    title: '售后单 #20260714001',
    url: 'https://example.com/after-sales/20260714001',
    fields: [
      {
        key: 'status',
        label: '售后状态',
        type: 'text',
        value: '审核中'
      }
    ]
  }
]);

setContexts() 会以传入数组替换该访客当前全部咨询上下文：

传入新数组：更新为新上下文；
传入 []：清空全部上下文；
初始化时不传 contexts：不主动清空已有上下文。

// 清空当前访客的咨询上下文
window.kfVisitor.setContexts([]);

六、打开、收起与销毁客服窗口

初始化后返回的实例可用于控制客服窗口：

// 打开客服窗口
window.kfVisitor.open();

// 收起浮层客服窗口
window.kfVisitor.hide();

// 切换打开/收起状态
window.kfVisitor.toggle();

// 页面卸载或单页应用切换时销毁实例
window.kfVisitor.destroy();

也可以在打开客服窗口时同时更新数据：

window.kfVisitor.open({
  contexts: [
    {
      key: 'product_10001',
      type: 'product',
      title: '商品：无线耳机',
      fields: [
        {
          key: 'price',
          label: '售价',
          type: 'text',
          value: '299 元'
        }
      ]
    }
  ],
  visitorAttributes: [
    {
      key: 'member_level',
      label: '会员等级',
      type: 'text',
      value: '黄金会员'
    }
  ]
});

七、显示与启动配置

{
  displayMode: 'floating',
  autoOpenDelay: 3,
  preconnect: true,
  icon: 'https://example.com/kefu-icon.png',
  theme: {
    primaryColor: '#1677ff'
  },
  launcher: {
    target: '#custom-kefu-button',
    unreadBadge: true,
    messagePreview: true
  }
}

配置项	说明
`displayMode`	显示方式：`floating` 为页面浮层，`window` 为新窗口打开。默认 `floating`。
`autoOpenDelay`	自动打开延迟时间，单位为秒；`0` 表示立即打开；不传则不自动打开。
`preconnect`	是否预连接客服会话。设为 `true` 可让客服更早收到访客进入信息。
`icon`	自定义悬浮客服图标 URL。
`theme.primaryColor`	主题色，可传 `#1677ff` 等颜色值。
`launcher.target`	使用页面已有元素作为客服入口，传 CSS 选择器或 HTMLElement。
`launcher.unreadBadge`	是否在入口上显示未读数，默认 `true`。
`launcher.messagePreview`	是否显示消息预览，默认 `true`。

使用自定义入口示例：

<button id="custom-kefu-button">联系在线客服</button>

<script src="https://kefu.99kf.com/static/js/kf.js"></script>
<script>
  window.kfVisitor = KFVisitor.init({
    businessId: '您的企业ID',
    baseUrl: 'https://kefu.99kf.com',
    launcher: {
      target: '#custom-kefu-button'
    },
    visitor: {
      uid: 'user_10001',
      nickname: '张三'
    }
  });
</script>

八、安全建议

visitor.uid、昵称、头像、用户属性与上下文均运行在浏览器中，访客可通过浏览器开发者工具查看或修改这些数据。

如业务对身份真实性有严格要求，请不要仅依赖前端传入的 uid 作为鉴权依据；应使用服务端生成的访客身份凭证：

window.kfVisitor = KFVisitor.init({
  businessId: '您的企业ID',
  baseUrl: 'https://kefu.99kf.com',

  // 由您的服务端安全生成
  visitorCode: '服务端生成的访客身份凭证'
});

使用 visitorCode 时，客服脚本会优先使用该凭证，不会再将 visitor.uid、visitor.nickname、visitor.avatar 作为访问参数传递。

接口密钥、加密逻辑、签名或身份凭证只能保存在服务端，不能写入网页 JavaScript、App 前端代码或公开仓库。

七、常见问题

问：接口密钥泄露怎么办？
答：在后台重新生成密钥，并更新所有服务端生成 code 的逻辑。旧密钥产生的 code 将失效。

问：明文和加密可以同时用吗？
答：若配置了 code，接入脚本会优先走加密参数，不再附带明文 uid/name/avatar 查询串。

问：关闭「允许明文」后，旧链接还能用吗？
答：带明文用户参数的链接将被拒绝，请改为使用 code 方式。

客服系统源码对接用户数据

用户数据对接教程

用户数据对接教程

一、快速接入

二、完整初始化示例

三、访客基本资料

四、用户属性

动态更新用户属性

五、咨询上下文

动态更新咨询上下文

六、打开、收起与销毁客服窗口

七、显示与启动配置

八、安全建议

七、常见问题