# 接入说明

智齿客服网页端接入提供两种方式部署对接 1、链接部署方式 2、JS-SDK部署方式

两种部署方式功能上的差异可以点击此处查看文档

# 链接部署方式

1、管理员获取接入代码

智齿控制台-设置-支持渠道-移动网站-部署设置

2、对接示例

<!DOCTYPE html>
<html>
  <head>
    <title>聊天客户端</title>
  </head>
  <body>
    <!--html标签-->
    <a href="https://chat.sobot.com/chat/h5/v2/index.html?sysnum=4c349791a07b46c1a70b8ac88aa23257" target="_blank">欢迎咨询</a>
    <!--html标签-->
  </body>
</html>

聊天链接提供和网页组件相同的客服功能,它是通过链接的形式打开一个新页面进行咨询访问,企业可通过在URL后追加特定参数,实现个性化的客服方案配置,详细请参考章节<附件-参数一览>。

# JS-SDK部署方式

1、管理员获取接入代码

智齿控制台-设置-支持渠道-移动网站-部署设置

2、完整代码接入示例

<!DOCTYPE html>
<html>
  <head>
    <title>聊天客户端</title>
  </head>
  <body>
  <!--html标签-->
    <script>
      (function (w, d, e, x) {
        w[e] = function () {
          w.cbk = w.cbk || []
          w.cbk.push(arguments);
        }
        x = d.createElement("script");
        x.async = true;
        x.id = "zhichiScript";
        x.src = "https://chat.sobot.com/chat/frame/v2/entrance.js?sysnum=3542411be2184c8cb6b48d66ca1b2730";
        d.body.appendChild(x);
      })(window, document, "zc");
    </script>
  <!--html标签-->
  </body>
</html>

该示例为最简单的智齿接入,通过组件接入智齿客服咨询组件,企业的用户可快捷联系到企业客服获取帮助。智齿客服网页组件提供强大的用户行为采集能力和系统对接能力。当对接成功以后,访客访问页面时会在页面右下角自动出现访问客服的入口,按钮可自定义,当点击按钮后会进入到聊天页面。详细请参考章节<附件-参数一览>。

# 部署约定

1、所有在 data-args 中添加的参数均可使用代码方式添加,反之一样。

示例:

//方式一:属性方式添加

...
x.setAttribute("data-args", "color=04babc&uname=智齿客服");
...

//方式二:代码方式添加

zc("config",{
  "color":"04babc",
  "uname":"智齿客服"
})

2、所支持的参数可能不会逐一介绍到,但您可以在文末的参数一览表中找到,并会附有所有参数的功能介绍。

3、请您知晓,我们所有的参数均支持两种方式对接——属性对接和代码对接。此文档在介绍各个参数时,同一参数只会介绍一种对接方式,但是另一种对接方式也能实现。

# 组件对接

# 自动初始化

直接把智齿后台生成的组件链接放到您的网站的标签之前,即完成自动初始化。

示例如下:

<!DOCTYPE html>
<html>
  <head>
    <title>聊天客户端</title>
  </head>
  <body>
  <!--html标签-->
    <script>
      (function (w, d, e, x) {
        w[e] = function () {
          w.cbk = w.cbk || []
          w.cbk.push(arguments);
        }
        x = d.createElement("script");
        x.async = true;
        x.id = "zhichiScript";
        x.src = "https://chat.sobot.com/chat/frame/v2/entrance.js?sysnum=3542411be2184c8cb6b48d66ca1b2730";
        d.body.appendChild(x);
      })(window, document, "zc");
    </script>
  <!--html标签-->
  </body>
</html>

# 手动初始化咨询组件

示例如下:

//第一步
zc("config", {
  "manual": true, //设置成手动初始化
})

//第二步 通过事件手动初始化
document.getElementById("customBtn").addEventListener("click",function(){
   zc("frame_manual", function (res) {
    console.log("初始化成功")
  }
})

# 自定义客户端

示例如下:

zc("config",{
  "color":"04babc", //客户端主题色 (格式为 0-9 a-f 之间的六位有效字符 不用加#)
  "location":1, //咨询入口位置 1-右下角 2-左下角 (默认右下角)
})

# 不使用默认咨询入口

智齿聊天组件默认会生成一个咨询按钮,若想自定义咨询按钮。需设置 custom=true ,同时在自定义按钮标签上添加组件对应的 class 即可。

示例如下:

<!DOCTYPE html>
<html>
  <head>
    <title>聊天客户端</title>
  </head>
  <body>
    <!--自定义按钮 第三步-->
    <button class="zhiCustomBtn">欢迎咨询</button>
    <!--html标签-->
    <script>
      (function (w, d, e, x) {
        w[e] = function () {
        w.cbk = w.cbk || []
        w.cbk.push(arguments);
        }
        x = d.createElement("script");
        x.async = true;
        x.id = "zhichiScript";
        x.className="zhiCustomBtn"; //该class绑定到自定义按钮上 第一步
        x.src = "https://chat.sobot.com/chat/frame/v2/entrance.js?sysnum=3542411be2184c8cb6b48d66ca1b2730";
        d.body.appendChild(x);
      })(window, document, "zc");
      zc("config",{
        custom:true, //设置自定义生效 第二步
      })
    </script>
    <!--html标签-->
  </body>
</html>

# 创建动态自定义咨询入口

有时候使用自定义按钮时,很多页面元素都是动态生成的,此时要使用动态绑定自定义事件,才能让自定义咨询入口生效

示例如下:

<script>
  document.getElementById("dynBtn").addEventListener("click",function(){
    //模拟动态插入数据
    document.getElementById("root").innerHTML = '<button class="zhiCustomBtn">咨询</button>';
    //动态创建自定义按钮
    zc("dynamic_ready")
  })
</script>

# 未读消息、离线消息

# 获取未读消息

示例如下:

注意:只有在用户将聊天窗口收起且客服给用户发送消息时,这个事件才会触发。也可监听zhichiReceive,功能与receive_message一致。

zc('receive_message',function(res){
  //返回格式:{ img:"客服头像", name:"客服名称", msg:"客服发送的内容",t:"发送消息时间"}
})

# 获取离线消息

获取离线客服发的消息数,当用户与客服聊天的会话结束之后。用户离开页面,客服可以给用户发送离线消息。当用户再次进入页面时,我们会通过这个事件,推送用户未读的离线消息数值。

示例如下:

zc("offline_message_count",function(res){
  console.log(res)
})

# 适配多语言

英文版/中文版

//en-英文, cn-简体中文,tw-繁体中文(默认简体中文) 后续会支持更多语种
zc("config",{
  locale:"en",
})

# 商品卡片链接(仅H5支持)

通过网页组件可设置需要展示的商品信息展示到用户端

参数 类型 参数描述 适用范围
card_title String 商品标题(必传) 组件、链接
card_url String 商品信息的商品链接地址(必传) 组件、链接
card_desc String 商品信息的简述内容(选传) 组件、链接
card_note String 2000元 商品标签例:价格(选传) 组件、链接
card_picture String 商品的缩略图(选传) 组件、链接

示例如下:

zc("config",{
  card_title:"云客服_智齿客服",
  card_url:"http://www.sobot.com",
  card_desc:"云客服,在线客服系统,云呼叫中心,机器人客服,工单客服,智能客服",
  card_note:"1500,2000",
  card_picture:"https://img.sobot.com/console/common/face/admin.png"
})

例图:

图片

# 订单卡片链接

通过IFrame对接的客户订单系统页面发送postMessage到客服工作台的方式将订单卡片发送给客户,示例如下:

...
<button id="send">发送订单信息</button>
...
/**
*orderStatus 订单状态枚举值(前端传对应的数字):
*待付款: 1,
*待发货: 2,
*运输中: 3,
*派送中: 4,
*已完成: 5,
*待评价: 6,
*已取消: 7
**/
/**
*  goods 数据结构
*[{
*  "name":"商品名称1",					
* "pictureUrl":"http://goodsPicture1"   			
*  },{
*  "name":"商品名称2",					
*  "pictureUrl":"http://goodsPicture2"   			
*  }]
**/
document.getElementById("send").addEventListener("click",function () {
    var data = {
        orderStatus:1,//订单状态
        createTime:+new Date(),//下单时间  时间戳
        orderCode:'88888888',//订单编号
        orderUrl:'http://order.com/1',//订单链接
        totalFee:'100',//订单金额
        goodsCount:2,//商品数量
        goods:JSON.parse(getValue('goods'))
    };
    window.parent.postMessage({
        cid: '111111',
        uid: '222222',
        msgType: 25,  //固定值
        miniPage:JSON.stringify(data)
    }, '*');
},false);

例图: 图片

# CRM对接

# 基本信息对接

企业可以通过调用config接口配置企业客户信息,以便在客服系统中将会话与企业CRM系统中的客户关联起来。

示例如下:

zc("config",{
  uname:"小丁哥", //客户名称
  realname:"丁丁猫", //客户真实姓名
  tel:"18888888888", //客户电话,
  email:"dingmao@163.com", //客户邮箱
  qq:"2345678", //客户qq号
  remark:"vip客户,每次响应不能超过5秒钟" //客户备注信息
})

# 客户自定义字段对接

# params

params 是自定义字段,通过该字段客户可传入任何想传到工作台进行展示的属性,它接收的值是一个json格式的字符串。展示在客服工作台的客户咨询模块中最下方的自定义字段区域,该自定义字段可在后台会话统计中通过关键字查询检索到,并且可以通过导出会话信息导出。

示例如下:

var args = {
  等级:"Boss",
  惯称:"智齿sobot",
  来自:"北京"
};
zc("config",{
  params:JSON.stringify(args)
})

# customer_fields

customer_fields 是自定义字段,区别于 params 的是它需要在客服后台进行配置后才能使用,它也是接收一个json格式的字符串。展示在客服工作台的客户咨询模块中

示例如下:

var args= {
  customField4:"北京智齿科技",
  customField5:"小智呀"
};
zc("config",{
  customer_fields:JSON.stringify(args)
})

# 接待模式

示例如下:

zc("config",{
  // 1 : 仅机器人客服模式
  // 2 : 仅人工客服模式
  // 3 : 机器人客服优先模式
  // 4 : 人工客服优先模式
  type:3,
  //机器人id 多机器人模式下,可配置不同场景下不同机器人客服接待
  //请到后台【设置】->【机器人信息】查看
  robotid:2,
  agentid:'1q2w3e4r', //人工客服id 指定客服接待
  groupid:'4r3e2w1q', //配置技能组 当客户咨询人工客服时,会先选择需要咨询的业务
})

# VIP智能路由接待

参数说明

  • actionType 执行动作类型:
    • to_group 指定技能组;
    • to_service 指定客服。
  • deciId 指定技能组或客服id
  • optionId 溢出标记
    • 1:溢出;指定客服时
    • 2:不溢出;指定客服时
    • 3:溢出;指定技能组时
    • 4:不溢出;指定技能组时
  • spillId 溢出条件
    • 1:客服不在线;指定客服时
    • 2:客服忙碌;指定客服时
    • 3:智能判断;指定客服时
    • 4:技能组无客服在线;指定客服组时
    • 5:技能组所有客服忙碌;指定客服组时
    • 6:技能组不上班;指定客服组时
    • 7:智能判断;指定客服组时

示例如下:

var action = [{
  "actionType":"to_group",
  "optionId":"3",
  "deciId":"162bb6bb038d4a9ea018241a30694064",
  "spillId":"4"}];
  var payload = JSON.stringify(action);
  zc("config",{
    transfer_action:payload,
  })

# 多种邀请方式

通过邀请用户功能,企业可直接增加和用户沟通的机会,增加获取营销线索的可能。需要注意的是,此功能通常需要和“五、调整接待方式”配合使用,以实现不同特征的访客接受邀请由特定客服模式、指定机器人、指定客服组接待。

设置自动邀请访客

# 主动弹屏邀请用户

示例如下:

zc("config",{
  invite:1, //是否开启自动邀请 1开启 0关闭 默认不开启
  tip_title:'欢迎咨询', //主动邀请文案
  submit_title:'开始聊天吧', //接受邀请按钮
  first_timeout:2, //第一次加载延迟邀请时间 时间:s
  over_timeout:10, //拒绝后再次邀请时间 时间:s
  invite_count:5, //一天之内共邀请多少次
})

# 设置自动强制弹窗

企业可以通过在关键页面开启自动强制弹窗功能,当用户进入该页面后,会话窗口会自动展开并完成初始化。

示例如下:

zc("config",{
  auto_expand:true, //true 自动打开,默认不开启
})

# 允许客服主动邀请会话

企业需要添加此API或在“管理后台-设置-支持渠道-桌面网站”中开启“主动邀请会话”功能,客服在工作台才能手动邀请浏览网站中的用户。企业可根据自己的需要,在部分关键页面开启此项功能,以避免所有网站访客都进入邀请列表导致客服的工作难度增大。

示例如下:

zc("config",{
  invite_flag:true, //true关闭,默认开启
})

# 网站访问统计

管理员可在“设置-客服工作台”中开启客服工作台显示用户浏览轨迹的功能

# 开启浏览轨迹采集

智齿默认不采集用户浏览轨迹,企业可通过此API实现在特定页面下,对特定用户群体开启浏览轨迹采集功能。在调用以下方法开启用户浏览轨迹采集后,当用户浏览网页时,智齿将自动采集浏览网站的信息,包括当前访问页和当前访问页的来源页(当前访问页的上一页)。

需要注意的是,智齿会采集三类用户浏览:着陆行为(用户从哪儿进入网站)、浏览行为(用户进入网站后浏览了哪些页面)、发起咨询行为(用户从哪个页面发起咨询)。用户每次访问网站,智齿都会记录这三类行为,如果用户发起了咨询,这些行为将自动关联到此次咨询会话。

接下来智齿会逐步上线浏览轨迹数据查看、统计分析和原始数据导出功能,以便企业充分利用用户行为数据进行推广策略的结果评估、分析和调优。

zc("config",{
  man_trace:true, //开启收集用户方访问轨迹 默认不收集 也可在后台直接开启
})

# 自定义采集内容

企业可自定义浏览轨迹采集内容,保证客服看到的浏览轨迹消息能体现关键业务信息,如电商场景下的商品ID、商品分类、商品价格等。 若不自定义浏览轨迹参数,则系统自动收集访问页面的 URL链接和网页标题信息。

示例如下:

zc("config",{
  //上一页信息
  pre_visit_args:{
    'pre_abstract':'来源页的摘要 没有 则不传',
    'pre_visit_url': '来源页的url 没有 则不传',
    'pre_visit_title':'来源来的标题 没有 则不传',
    'pre_thumbnail': '来源页的缩略图 没有 则不传',
    'pre_tags':'来源页的标签 没有 则不传'
  },
  //当前页信息
  cur_visit_args:{
    'cur_abstract':'当前页的摘要 没有 则不传',
    'cur_visit_url': '当前页的url 没有 则不传',
    'cur_visit_title':'当前页的标题 没有 则不传',
    'pcur_thumbnail': '当前页的缩略图 没有 则不传',
    'cur_tags':'当前页的标签 没有 则不传'
  }
})

# 手动发送浏览轨迹

有些时候可能需要在特定的页面多次传送用户浏览轨迹。比如在单页应用中用户在浏览商品时,希望滚动到页面指定商品位置时触发该事件,从而发送浏览轨迹。

示例如下:

document.getElementById("traceBtn").addEventListener("click",function(){
  zc("trace",{
    //上一页信息
    pre_visit_args:{
      'pre_abstract':'来源页的摘要 没有 则不传',
      'pre_visit_url': '来源页的url 没有 则不传',
      'pre_visit_title':'来源来的标题 没有 则不传',
      'pre_thumbnail': '来源页的缩略图 没有 则不传',
      'pre_tags':'来源页的标签 没有 则不传'
    },
    //当前页信息
    cur_visit_args:{
      'cur_abstract':'当前页的摘要 没有 则不传',
      'cur_visit_url': '当前页的url 没有 则不传',
      'cur_visit_title':'当前页的标题 没有 则不传',
      'pcur_thumbnail': '当前页的缩略图 没有 则不传',
      'cur_tags':'当前页的标签 没有 则不传'
    }
  })
})

# 留言、评价、附件等功能

示例如下:

zc("config",{
  leave_msg_flag:true //输入框菜单区域的留言按钮 true开启 false关闭
  msg_flag:false, //系统提示的留言引导和会话结束后的留言入口 false开启 true关闭
  feedback_flag: //建立会话后的评价按钮 true开启 false关闭
  photo_flag: //建立人工会话后是否允许上传附件 true开启 false关闭
})

# 多机器人客服接入

示例如下:

zc("config",{
  robotid:1, //机器人id
})

# 常用功能配置

# 控制显示历史聊天记录的时间范围

通过该接口可控制显示历史聊天记录的时间范围,超过时间范围的聊天记录将不对用户显示。

示例如下:

// time 显示历史聊天记录的时间范围,需传入分钟数,有效值10-2880(10分钟-48小时)
zc("config",{
  time:15
})

# 转人工时跳转指定URL

支持通过该接口设置用户点击转人工时跳转指定URL,实现在机器人优先模式下,特定用户从特定网站的特定入口发起咨询时,用户点击转人工时可跳转到指定的URL页面。建议将URL进行encode编码,尽量使用HTTPS地址。

示例如下:

zc("config",{
  to_customsys_flag:true,
  to_customsys_url:'https://www.sobot.com'
})

# 新窗口打开咨询页

支持通过JS-API配置特定场景的特定用户点击咨询入口时是打开悬浮窗咨询页还是新窗口打开咨询页。 示例如下:

// true 新窗口打开咨询页 false 打开悬浮窗咨询页(默认值)
zc("config",{
  anchor:true
})

# 手动控制展开和收起聊天页面

示例如下:

document.getElementById("btn").addEventListener("click",function(){
//可以拿到当前聊天窗体的状态 expand展开 collapse收起
  zc('frame_status', function(data) {
    console.log(data)
  })
})

# 获取聊天页面加载完成后的回调

示例如下:

//获取iframe加载完成的回调函数
zc("frame_ready", function() {
  console.log('iframe加载完成')
})

# 关闭聊天页面时的回调

关闭聊天页面时,会向外发送 postmessage 请求,监听该postmessage即可获取当前聊天页的状态。

示例如下:

window.onmessage = function(e){
  if(e&&e.data){
    const {name,data} = JSON.parse(e.data);
    if(name==='zc_post_message'){
      const {action,} = data;
      //监听 action 为 chat_collapse_window 的postmessage
      switch(data.action){
        case 'chat_collapse_window':
        // your code here...
        break;
      }
    }
  }
}

# 每次展开聊天页面是否重新加载

zc('config', {
    'reload': true  //默认false不设置  建议不开启该功能
})

# pc/h5安全效验

1、开启“安全密钥”功能后,桌面网站或移动网站必须传partnerId参数。且桌面网站或移动网站对接时传参增加参数“sign”,sign=“MD5(sysnum+密钥+partnerid)”;
2、传入参数后智齿会对sign进行解密,验证传入的partnerid与sign中传入的partnerid是否一致,若一致则正常接入智齿系统,若不一致则弹出提示框“经验证当前用户为非法用户,不予接入客户服务中心”。若客户没有传partnerid或sign,则视同非法用户,也弹出提示框“经验证当前用户为非法用户,不予接入客户服务中心”;
3、“安全密钥”的功能开启和关闭,生效范围的设置是实时生效的;

# 独立接入留言页

公众号对接、小程序对接、IM原生对接等接入方式可以支持客户选择模板后进行留言

  https://www.sobot.com/chat/h5/v2/leavemessage.html?sysnum=ed22902866fb4f6e9bc7f0fa259aaa74&uid=xxx&source=9&uname=xxx&templateid=xxx&groupid=xx&locale=cn&t=xxx

source:值固定为9,其它参数根据实际情况拼写。
uid:通过客户中心查询客户信息接口获得,接口返回对应的参数为userid。
templateid:留言模板id需要在智齿后台的设置-留言模板设置模块,通过接口查看。

# 参数一览表

# 用户身份和资料字段

参数 类型 参数描述 适用范围
partnerid String 用户id 链接、组件
uname String 昵称 链接、组件
realname String 真实姓名 链接、组件
email String 邮箱账号 链接、组件
tel String 手机或电话 链接、组件
qq String qq号 链接、组件
remark String 备注 链接、组件
params String 自定义字段 链接、组件
customer_fields String 自定义字段(后台控制) 链接、组件

# 系统字段

参数 类型 参数描述 适用范围
color String 聊天页主题色 链接、组件
locale String 多语言 en英文 cn简体中文 tw繁体中文 链接、组件
show_manual String 机器人遇未知问题延迟显示转人工按钮,延迟的次数在后台设置,开关可在url上配置 1开启 0关闭 链接、组件
type String 客服接待模式 1仅机器人客服 2仅人工客服 3机器人客服优先 4人工客服优先 链接、组件
agentid String 客服id 链接、组件
groupid String 技能组id 链接、组件
robotid String 机器人客服id 链接、组件
msg_flag String 结束会话后是否显示留言入口 1关闭 0开启 链接、组件
leave_msg_flag String 控制面板中的留言按钮 1开启 0关闭 链接、组件
feedback_flag String 评价按钮 1开启 0关闭 链接、组件
photo_flag String 上传附件按钮 仅H5 1开启 0关闭 链接、组件
to_customsys_flag String 转人工时跳转第三方页面的开关 1开启 0关闭 链接、组件
to_customsys_url String 转人工时跳转第三方页面的地址 链接、组件
to_customsys_open_style String 转人工时跳转第三方是新窗口打开还是当前页打开 1新页打开 0当前页打开 链接
leave_customsys_flag String 是否开启留言转第三方系统 仅H5 1开启 0关闭 链接、组件
leave_customsys_url String 留言转第三方系统的地址 仅H5 链接、组件
agent_mode_flag String 指定客服接待模式 1客服不在线则正常提示 0客服不在线则接到其他在线客服 链接、组件
top_bar_flag String 是否显示聊天页面顶部返回栏 仅H5 1开启 0关闭 链接
title_flag String 控制title内容的三种显示方式:
1:显示管理后台设置的企业名称。
2:显示1到30字符的固定文案。
3:显示当前客服昵称。
(配合现有参数(top_bar_flag)一起使用的,top_bar_flag=1的时候才生效)仅H5
链接、组件
custom_title String title显示的自定义文案,结合title_flag使用,当title_flag=2时,顶部将显示该值。
top_bar_flag=1的时候才生效 仅H5
链接、组件
guide_flag String 是否开启机器人引导问题 1开启 0关闭 链接、组件
time String 用户可查看聊天记录的时间段 单位:分钟 链接、组件
transfer_action String 智能路由策略 链接、组件
summaryparams String 服务总结字段 链接、组件
anchor String 新窗口打开咨询页 组件
async String 页面进入时自动加载JS组件 默认0 1开启 0关闭 组件
invite String 是否开启自动邀请 1开启 0关闭 组件
tip_title String 邀请文案 组件
submit_title String 接受邀请按钮 组件
first_timeout String 第一次加载延迟邀请时间 时间:秒 组件
over_timeout String 拒绝后再次邀请时间 时间:秒 组件
invite_count String 一天之内共邀请多少次 组件
invite_imgsrc String 邀请弹屏的logo图片 组件
container_style String PC组件聊天窗体自定义样式(不支持设置height,width) 组件
height String PC组件聊天窗体自定义高度 组件
width String PC组件聊天窗体自定义宽度 组件
source String 来源 0:桌面网站,1:微信,2:APP,3:微博,4:移动网站 组件

# 消息字段

参数 类型 参数描述 适用范围
card_title String 消息卡片名称 链接、组件
card_url String 消息卡片地址 链接、组件
card_note String 消息卡片描述 链接、组件
card_desc String 消息卡片详情 链接、组件
card_picture String\ 消息卡片图标 链接、组件
robot_hello_word String 机器人欢迎语 链接、组件
agent_hello_word String 人工客服欢迎语 链接、组件
agent_offline_title String 人工客服不在线提示语 链接、组件
pre_abstract String 来源页摘要 组件
pre_visit_url String 来源页url 组件
pre_visit_title String 来源页标题 组件
pre_thumbnail String 来源页缩略图 组件
pre_tags String 来源页标签 组件
cur_abstract String 当前页摘要 组件
cur_visit_url String 当前页url 组件
cur_visit_title String 当前页标题 组件
cur_thumbnail String 当前页缩略图 组件
cur_tags String 当前页标签 组件