客服系统传递商品、订单和自定义信息

商品、订单、活动页、报价方案等信息，统一通过“咨询上下文”传给客服。上下文显示在客服工作台右侧，不会作为一条聊天消息插入会话记录。

例如，用户从商品详情页发起咨询时，客服可以马上看到商品名称、图片、价格和规格；从订单页进入时，也可以同时带上订单号、状态和售后入口。

在网页中传递上下文

先加载 kf.js，再调用 KFVisitor.init()。contexts 是一个数组，页面上有几项需要展示的信息，就传几项。

<script src="https://live.99kf.com/static/js/kf.js"></script>
<script>
window.kfVisitor = KFVisitor.init({
  baseUrl: 'https://live.99kf.com',
  businessId: 'X6uAFOVR',
  groupId: 0,
  displayMode: 'floating',

  visitor: {
    uid: '1666',
    nickname: '用户名称',
    avatar: 'https://example.com/avatar.png'
  },

  contexts: [{
    key: 'product:P40-5G',
    type: 'product',
    title: '正在咨询的商品',
    url: 'https://shop.example.com/products/P40-5G',
    fields: [
      { key: 'name', label: '商品名称', value: 'Huawei/华为 P40 5G 新款手机' },
      { key: 'description', label: '商品描述', value: '官方旗舰店正品，支持 24 期分期' },
      {
        key: 'image',
        label: '商品图片',
        type: 'image',
        value: 'https://example.com/images/p40.jpg'
      },
      { key: 'price', label: '价格', type: 'money', value: '¥5,000' },
      { key: 'sku', label: '规格', value: '8GB + 256GB，亮黑色' }
    ]
  }]
});
</script>

businessId 是商户 ID，可在客服后台的部署代码页面获取。visitor.uid 建议使用业务系统中稳定的用户 ID；未传时系统会为访客生成匿名 ID。

同时传递订单和来源页面

一个访客可以有多个上下文。下面的例子同时展示订单和活动页信息：

window.kfVisitor.setContexts([
  {
    key: 'order:202506291268',
    type: 'order',
    title: '当前订单',
    url: 'https://shop.example.com/orders/202506291268',
    fields: [
      { key: 'order_no', label: '订单号', value: '202506291268' },
      { key: 'status', label: '订单状态', type: 'status', value: '未支付' },
      { key: 'amount', label: '订单金额', type: 'money', value: '¥3,600' }
    ]
  },
  {
    key: 'page:summer-sale',
    type: 'page',
    title: '活动来源页面',
    url: 'https://shop.example.com/summer-sale',
    fields: [
      { key: 'campaign', label: '活动', value: '满 300 减 30' }
    ]
  }
]);

单页应用切换路由、用户选择其他商品或订单状态变化后，直接再次调用 setContexts() 即可。也可以在打开客服时传入最新上下文：

window.kfVisitor.open({
  contexts: nextContexts
});

字段说明

key：上下文唯一键。建议使用 product:商品ID、order:订单号 这类稳定格式。
title：客服侧卡片标题。
type：上下文分类，如 product、order、page、custom，用于业务识别。
url：卡片关联页面地址，可不传。
fields：需要展示的有序字段。
字段的 type 为 image 时显示缩略图并支持预览；url 显示为链接；其他类型按文本展示。money、status、datetime 这类类型可用于表达业务含义。

每次调用传递的是当前完整上下文集合：相同 key 会更新，未再传递的旧 key 会被移除；传空数组可清空当前上下文。单次最多 20 个上下文，每个上下文最多 50 个字段。

原生 SDK 与服务端同步

如果业务需要由服务端主动更新上下文，请使用 POST /sdk/contexts，并携带该访客的 SDK access token：

curl -X POST 'https://live.99kf.com/sdk/contexts' \
  -H 'Authorization: Bearer <visitor_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contexts": [
      {
        "key": "order:202506291268",
        "type": "order",
        "title": "当前订单",
        "fields": [
          {"key": "status", "label": "订单状态", "type": "status", "value": "已发货"}
        ]
      }
    ]
  }'

不要在网页前端保存商户 API 密钥或生成 SDK token。网页挂件使用 KFVisitor.init() 和 setContexts() 即可；服务端接口仅应由自己的业务服务调用。