跳到主要内容

访客端订单信息对接

提示

社区版不支持，请升级到企业版或平台版。请替换licenseKey

本页面介绍如何将业务系统中的订单信息传递给客服系统，特别适用于电商、物流等需要提供订单咨询服务的场景，帮助客服快速了解用户咨询的订单详情。

注意：请确保您已经完成了React集成指南中的基本功能对接，才能继续进行订单信息对接。

访客端对接示例​

访客端对接示例

客服端对接示例​

客服端对接示例

为什么需要订单信息对接？​

在客户服务场景中，订单问题是用户咨询最常见的内容之一。订单信息对接可以：

  • 让客服即时了解用户咨询的订单详情，无需用户重复描述
  • 准确显示订单状态、商品信息、配送信息等关键数据
  • 大幅提高客服解决问题的效率和准确性
  • 减少用户等待时间，提升客户满意度
  • 为售后服务提供完整的订单背景信息

订单信息数据结构​

订单信息推荐严格对齐后端 OrderEntity 的平铺结构，便于前后端字段一一对应，也方便客服系统直接展示订单快照数据。当前推荐结构如下：

// 订单信息数据结构
interface OrderInfo {
  navigateToPath: string;    // 点击订单卡片后的跳转路径
  type: string;              // 业务类型，建议固定为 order
  title: string;             // 订单卡片标题
  description: string;       // 订单卡片描述
  state: string;             // 业务状态，可与 status 保持一致
  time: string;              // 下单时间
  status: string;            // 订单状态编码
  statusText: string;        // 订单状态文本
  orderUid: string;          // 订单编号
  orderTitle: string;        // 订单商品标题/摘要
  orderImage: string;        // 订单商品图片
  orderDescription: string;  // 订单商品描述
  orderPrice: number;        // 订单商品单价
  orderUrl: string;          // 订单详情页URL
  orderTagList: string[];    // 订单标签列表
  orderExtra: string;        // 订单商品扩展信息(JSON字符串)
  orderQuantity: number;     // 购买数量
  totalAmount: number;       // 订单总金额
  paymentMethod: string;     // 支付方式
  extra: string;             // 订单扩展信息(JSON字符串)
  visitorUid: string;        // 当前访客ID
  shopUid: string;           // 店铺ID
  shippingAddress: {         // 收货信息
    name: string;          // 收货人
    phone: string;         // 联系电话
    address: string;       // 收货地址
  };
}

点击订单消息气泡时，visitor 会在 onMessageBubbleClick 回调事件的 navigateToPath 末尾自动追加 payload 参数，参数值为当前订单消息的完整原始 JSON。该回调约定同时适用于 h5/web 宿主、visitorSdk 宿主、uniapp Android/iOS 宿主以及微信小程序宿主，宿主可直接解析该地址完成跳转。

回调调试​

当宿主侧需要排查订单消息点击回调时，可开启统一调试开关。该开关同时适用于 h5/web 宿主、visitorSdk 宿主、uniapp Android/iOS 宿主以及微信小程序宿主。

  • URL 方式：在聊天页或宿主加载的聊天链接后追加 bizMessageCallbackDebug=1
  • 存储方式：在对应运行环境中写入 BIZ_MESSAGE_CALLBACK_DEBUG=1
  • 日志前缀：所有桥接日志统一以 [biz-callback] 开头

常见日志节点如下：

  • emit：visitor 聊天页已发出商品/订单气泡点击事件
  • uniapp-send.uni-postMessage：visitor 已通过 uni.postMessage 向 uniapp 宿主发送消息
  • uniapp-send.bridge-postMessage：visitor 已通过 UniAppJSBridge.postMessage 走兜底发送
  • wechat-mini-send.postMessage：visitor 已向微信小程序宿主发送回调数据
  • wechat-mini-send.navigate：微信小程序已执行详情页直跳
  • host-receive.web-sdk：web/h5 宿主通过 visitorSdk 收到回调
  • host-receive.uniapp-webview-message：uniapp 宿主收到 web-view 消息
  • host-receive.uniapp-normalized：uniapp 宿主已完成消息归一化
  • host-navigate.uniapp-resolved-path：uniapp 宿主已拿到带 payload 的最终跳转地址

排查时建议优先确认 navigateToPath 是否存在，以及其中是否已经包含 payload 查询参数。如果 emit 已出现而宿主接收日志未出现，通常说明问题在宿主桥接通道而不是订单卡片数据本身。

字段约定

新接入请直接使用上面的平铺字段，不再推荐使用旧的 goods 嵌套结构。

对接方法​

微语客服系统通过配置参数来传递订单信息，在初始化客服组件时，通过chatConfig.orderInfo配置项传入订单数据。

配置示例​

以下是一个完整的配置示例，演示如何将订单信息传递给客服系统：

const config = {
  // 基本配置
  placement: 'bottom-right',
  autoPopup: false,
  marginBottom: 20,
  marginSide: 20,
  buttonConfig: {
    show: false,  // 隐藏默认按钮，使用自定义按钮
  },
  bubbleConfig: {
    show: false,  // 隐藏气泡
    icon: '📦',
    title: '订单有问题？',
    subtitle: '点击咨询客服'
  },
  
  // 聊天配置
  chatConfig: {
    org: 'df_org_uid',    // 替换为您的组织ID
    t: "1",              // 会话类型（0：一对一，1：工作组，2：机器人）
    sid: 'df_wg_uid',     // 替换为您的SID
    
    // 可选：传入用户信息
    visitorUid: 'visitor_001',
    nickname: '访客小明',
    avatar: 'https://example.com/avatar.jpg',
    
    // 订单信息 - 核心部分
    orderInfo: JSON.stringify({
      navigateToPath: '/pages/order/detail/index?orderUid=ORD202505270001',
      type: 'order',
      title: '订单咨询',
      description: '用户正在咨询订单售后与物流进度',
      state: 'paid',
      time: '2025-05-27 14:30:00',
      status: 'paid',
      statusText: '已支付',
      orderUid: 'ORD202505270001',
      orderTitle: '比亚迪 仰望U7 豪华纯电动轿车',
      orderImage: 'https://example.com/yu7.jpg',
      orderDescription: '比亚迪仰望U7是一款豪华纯电动轿车...',
      orderPrice: 299900,
      orderUrl: 'https://example.com/product/yu7',
      orderTagList: ['新能源', '豪华轿车', '智能驾驶', '长续航'],
      orderExtra: JSON.stringify({
        color: '极光蓝',
        configuration: '豪华版'
      }),
      orderQuantity: 1,
      totalAmount: 299900,
      visitorUid: 'visitor_001',
      shopUid: 'shop_001',
      
      // 收货信息
      shippingAddress: {
        name: '张三',
        phone: '13800138000',
        address: '北京市朝阳区建国路88号'
      },
      
      paymentMethod: '微信支付',            // 支付方式
      
      // 额外信息
      extra: JSON.stringify({
        invoiceType: '电子发票',
        expectedDelivery: '2025-05-30',
        remarks: '请工作日送货'
      })
    })
  },
  locale: 'zh-cn',
};

订单信息显示效果​

当您正确配置订单信息后，客服系统会在客服工作台显示用户咨询的订单详情卡片，包括订单编号、状态、商品信息、收货地址等关键信息，方便客服快速了解订单情况并提供针对性服务。

H5链接对接方法​

除了组件集成外，微语客服还支持通过URL参数直接传递订单信息，特别适用于H5页面或者需要快速集成的场景。

H5链接格式​

基本链接格式如下：

// t: 会话类型（0：一对一，1：工作组，2：机器人）
// autoSendBizInfo: 是否自动发送商品/订单卡片，默认 1；传 0 时改为右下角弹窗确认发送
https://www.weiyuai.cn/chat/?org=您的组织ID&t=1&sid=会话ID&orderInfo=订单信息JSON&autoSendBizInfo=0

其中orderInfo参数需要进行URL编码；autoSendBizInfo为可选参数，默认值为1，示例如下：

// 1. 准备订单信息对象
const orderInfo = {
  navigateToPath: '/pages/order/detail/index?orderUid=ORD202505270001',
  type: 'order',
  title: '订单咨询',
  description: '用户正在咨询该订单',
  state: 'paid',
  time: '2025-05-27 14:30:00',
  status: 'paid',
  statusText: '已支付',
  orderUid: 'ORD202505270001',
  orderTitle: '比亚迪 仰望U7',
  orderImage: 'https://www.weiyuai.cn/assets/images/car/yu7.jpg',
  orderPrice: 299900,
  orderQuantity: 1,
  totalAmount: 299900,
  visitorUid: 'visitor_001',
  shopUid: 'shop_001'
};

// 2. 转换为JSON字符串并进行URL编码
const orderInfoStr = encodeURIComponent(JSON.stringify(orderInfo));

// 3. 拼接完整URL
const chatUrl = `https://www.weiyuai.cn/chat/?org=df_org_uid&t=1&sid=df_wg_aftersales&orderInfo=${orderInfoStr}&autoSendBizInfo=0`;

// 4. 使用该链接进行跳转
window.location.href = chatUrl;
  • autoSendBizInfo=1: 聊天初始化后自动发送订单卡片
  • autoSendBizInfo=0: 在右下角弹出订单预览卡片，用户点击发送后才真正下发消息

使用场景​

H5链接对接特别适用于以下场景：

  1. 移动端H5订单详情页中的"联系客服"按钮
  2. 订单通知邮件或短信中的客服链接
  3. 无法进行复杂集成的第三方平台
  4. 需要从外部系统快速跳转到客服系统的场景

注意事项​

  • URL有长度限制，请确保编码后的订单信息不会过长
  • 敏感信息应脱敏处理或省略
  • 确保JSON格式正确，避免解析错误

完整示例代码​

订单信息对接示例

最佳实践​

1. 订单数据处理​

  • 敏感信息处理: 避免传递完整的手机号码、详细地址等敏感信息，可以进行适当脱敏
  • 状态规范化: 统一订单状态编码，便于客服系统理解和处理
  • 金额显示: 确保金额数据类型正确，单位统一（如"元"）
  • 图片优化: 商品图片应经过优化，确保加载速度和显示效果

2. 实现技巧​

  • 按需传递: 仅在用户点击"咨询客服"按钮时才传递订单信息
  • 订单列表: 如果用户有多个订单，可以设计订单选择机制，让用户指定要咨询的订单
  • 状态更新: 订单状态变更时，更新传递给客服的信息
  • 物流跟踪: 对于已发货订单，可额外传递物流信息

3. 用户体验优化​

  • 问题分类: 设计常见的订单问题类型，帮助用户快速选择问题
  • 服务评分: 咨询结束后收集用户对解决方案的评价
  • 自助选项: 提供部分常见问题的自助解决方案
  • 智能推荐: 基于订单状态和历史咨询推荐可能的问题解决方案

常见问题​

Q1: 如何处理包含多个商品的订单？​

A: 对于包含多个商品的订单，可以采用以下方法：

  1. 使用orderTitle、orderImage、orderDescription展示主商品或订单摘要信息，把完整商品列表放入orderExtra或extra中：
orderTitle: '订单共 3 件商品',
orderDescription: '主商品：商品1，另含商品2、商品3',
orderExtra: JSON.stringify({
  items: [
    { uid: 'goods_001', title: '商品1', quantity: 1 },
    { uid: 'goods_002', title: '商品2', quantity: 1 },
    { uid: 'goods_003', title: '商品3', quantity: 2 }
  ]
})
  1. 如果客服侧需要读取更多结构化数据，建议统一放在orderExtra或extra里，由宿主系统和客服流程自行解析。

Q2: 订单状态发生变化时如何更新？​

A: 当订单状态变化时，您可以：

  1. 监听订单状态变化事件
  2. 更新本地订单数据
  3. 如果客服会话已经开启，可以通过再次调用showChat方法并传递更新后的订单信息：
// 订单状态更新后
window.bytedesk?.showChat({
  chatConfig: {
    orderInfo: JSON.stringify(updatedOrderInfo)
  }
});

Q3: 如何处理大量历史订单？​

A: 对于用户有多个历史订单的情况：

  1. 设计一个订单选择界面，让用户从中选择需要咨询的订单
  2. 只传递最近的几个订单信息，避免数据过大
  3. 提供订单搜索功能，让用户快速找到需要咨询的订单

Q4: 订单信息中可以包含哪些自定义字段？​

A: 在extra字段中，您可以根据业务需要添加各种自定义信息，例如：

  • 发票信息
  • 预计送达时间
  • 订单备注
  • 优惠券使用情况
  • 积分使用和获取情况
  • 售后服务信息
  • 其他定制化需求

进阶功能​

除了基本的订单信息传递，您还可以考虑实现以下进阶功能：

  1. 订单变更提醒: 当订单状态变化时主动通知用户
  2. 退款/售后处理: 针对退款、换货等售后场景的专门处理
  3. 物流追踪集成: 实时显示物流信息
  4. 自定义操作按钮: 在客服界面提供直接操作选项，如"申请退款"、"修改地址"等
  5. 满意度评价: 问题解决后的满意度评价系统

小结​

订单信息对接是提升客服体验的重要环节，通过将完整的订单信息传递给客服系统，可以大大提高咨询效率和服务质量。合理设计订单数据结构，确保关键信息准确传递，同时注意保护用户隐私，将帮助您构建更高效的客户服务体系。

编辑此页
最后由 jack ning 于 更新

这页文档对您有帮助吗？