JavaScript 开发文档

如何开始？

请先注册团队后在工作台「设置」-「网页接入」完成网页接入后才能够使用下面的扩展功能。

展开聊天窗

如果你需要按自己的需要控制聊天框展开，比如点击网站的某个按钮或者是自定义聊天按钮。
调用 JS 函数 _AIHECONG('showChat') 即可展开聊天窗。

示例：

<!-- 比如点击按钮展开聊天窗 -->
<button onclick="_AIHECONG('showChat')">联系客服</button>

隐藏聊天窗

调用 JS 函数 _AIHECONG('hideChat') 可隐藏聊天窗。

示例：

<button onclick="_AIHECONG('hideChat')">隐藏聊天窗口</button>

指定客服或客服组

你可以利用我们提供的 JS 函数来指定客服或客服组接待对话。

示例：

<script>
  //请在网页接入代码后面编写功能代码

  //指定客服
  _AIHECONG('assign', {
    service : '客服 ID ', //客服 ID 在工作台成员管理可以看到
    grade : 2  //grade 为 2 表示强制指定，被指定客服不在线则留言
  })

  //指定客服组
  _AIHECONG('assign', { group : '客服组名称', grade : 2 }) //客服组名称，可以是中文

  //如果客服和客服组都指定了，则只有指定客服会生效。
  _AIHECONG('assign', {
    service : '客服 ID ', //有效
    group : '客服组名称' //无效
  })
</script>

注意：如果同时设置了对话分流选项，则会跳过分流选项，避免指定失效。

传递顾客资料

客服工作台可以在与顾客对话时为顾客设置资料信息，但都是需要客服手动设置。如果你的网站能够识别顾客资料（比如会员），就可以用这里的方法自动传递，客服与顾客对话时也能够得到。

示例：

<script>
  //请在网页接入代码后面编写功能代码

  //传递顾客资料
  //属性名与顾客名片一致则填充到顾客名片
  //不一致则列入自定义信息
  _AIHECONG('customer',{
    head : '头像绝对路径', //该字段可以将顾客头像同步过来
    '名称' : '张先生',  // '属性名' : '值'
    '邮箱' : 'test@test.com',
    '手机' : '19900000000',
    '会员账号' : 'test',
    '会员等级' : 'VIP',
    //如果需要让显示在对话面板右侧的顾客参数带链接，可以用下面的方式
    //需要注意链接类型的参数 属性名 不能与顾客名片字段一样，只能归类到自定义信息
    '订单号' : JSON.stringify({ url: 'http://www.aaa.com', title: "201804120397" })
  })
</script>

上面示例代码传入的顾客资料将在工作台对话页面右侧呈现。

绑定到网站会员

无论使用什么设备进行访问聊天，都可以识别到登录的会员，并且同步聊天记录。

示例：

<script>
  //网页接入代码
  ....
  ....
  //在初始化的时候传递会员唯一ID
  _AIHECONG('ini',{
    entId : '团队ID',
    uniqueId : '5ccb3020bbf4693783745351' //网站会员唯一ID，请不要超过64个字符
  });
  //如果是Vue或React应用，会员登录前就已经接入代码并初始化
  //那么登录后可以使用update传递会员ID并重置组件
  _AIHECONG('update',{ entId : '团队ID', uniqueId : '会员唯一ID' });
  //设置 - 网页接入 里的代码可以找到 entId
</script>

去除聊天按钮

网页接入后页面右下角会显示默认的圆形聊天按钮，如果你不喜欢默认的聊天按钮，可以去除，然后自定义聊天按钮。

示例：

<script>
  //网页接入代码
  ....
  ....
  //在初始化的时候去除聊天按钮
  _AIHECONG('ini',{
    entId : '团队ID',
    button : false //去除聊天按钮
  });
</script>

注意：去除聊天按钮后，被展开的聊天窗将贴在页面底部，而不是固定在聊天按钮上面（因为没有了默认的聊天按钮）。

单页应用

如果接入的网页是单页应用，比如用 reactJs、VueJS、AngularJS 编写的网页应用程序，页面进行跳转的时候无法同步更新访客当前访问的页面以及访问轨迹，可以通过下面的方法让单页应用正常处理访客页面跳转事件。

示例：

<script>
  //在页面 router 变化时调用下面的方法，要注意避免多次重复调用。
  _AIHECONG('update');
  //支持传递初始化的参数，相当于覆盖初始化重置客服组件
  _AIHECONG('update', { entId, ... });
</script>

显示历史聊天记录

默认情况下，新对话开始的时候顾客需要往上滚动才能获取上一次对话的聊天记录。你也可以设置成新对话开始的时候直接读取上一次的聊天记录。

示例：

<script>
  //网页接入代码
  ....
  ....
  //在初始化的时候
  _AIHECONG('ini',{
    entId : '团队ID',
    history : true //添加该参数实现默认读取上一次聊天记录
  });
</script>

聊天窗口是否可见

我们提供了一个回调方法让你能够实时捕获到聊天窗口是否可见。

示例：

<script>
//请在网页接入代码后面编写功能代码

//自定义方法
function visibleCallback(visible){
  if(visible == 'show'){
    console.log('聊天窗口展开了')
  }
  if(visible == 'hide'){
    console.log('聊天窗口隐藏了')
  }
}
//聊天窗口是否可见的回调
_AIHECONG('visibleCallback',visibleCallback);
</script>

预设问题

可以自定义一组预设问题，顾客可以快速选择发送，建议配合关键词回复。

示例：

<script>
  //网页接入代码
  ....
  ....
  //在初始化的时候传入预设问题
  _AIHECONG('ini',{
    entId : '团队ID',
    setList : ['你们的价格多少','请问你们能开发票吗','我买的商品什么时候能到货']
  });
  //最多15个预设问题，每个问题不超过20个字符
</script>

通过接口预设的问题会覆盖在客服工作台设置的预设问题。

传递顾客资料 - 对话链接

对话链接同样可以传递顾客资料，在对话链接上添加参数即可。

https://团队ID.ahc.ink/chat.html?customer={"名称":"张先生","邮箱":"test@test.com","手机":"19900000000"}

可以看出 customer 值就是 json 格式转为字符串的结果。

注意：url 上传递的 json 字符串需要严谨，否则容易出错，建议先用 encodeURIComponent 给 customer 值编码，避免传参错误。

如果需要传递顾客参数，通常都会在自己的网址上获取顾客资料后动态生成对话链接，从而给每位顾客设置对应的资料。

JS 动态生成对话链接示例：

<a href="#" id="chatlink" target="_blank">点击打开对话链接</a>
<script>
  //设置顾客资料
  var customer = {
    head : '头像绝对路径', //该字段可以将顾客头像同步过来
    '名称' : '张先生',
    '邮箱' : 'test@test.com',
    '手机' : '19900000000',
    '会员账号' : 'test',
    '会员等级' : 'VIP'
  };
  //将 json 格式转为字符串
  customer = JSON.stringify(customer);
  //用 encodeURIComponent 进行编码
  customer = encodeURIComponent(customer);
  //生成最终的对话链接
  var url = 'https://团队ID.ahc.ink/chat.html?customer=' + customer;
  //设置 A 链接的 href
  document.getElementById("chatlink").href = url;
</script>

绑定到会员

无论使用什么设备进行访问聊天，都可以识别到登录的会员，并且同步聊天记录。

示例：

https://团队ID.ahc.ink/chat.html?uniqueId=会员唯一ID

指定客服或客服组 - 对话链接

可以通过添加 URL 参数，实现对话链接由指定客服或客服组来接待。

指定客服用 service 参数，参数值为客服ID，客服 ID 在工作台成员管理可以看到。

示例：

https://团队ID.ahc.ink/chat.html?service=客服ID&grade=2

指定客服组用 group 参数，参数值为分组名称，建议参数值用 encodeURIComponent 编码，避免出现问题。

示例：

https://团队ID.ahc.ink/chat.html?group=售前咨询&grade=2

如果 URL 参数中客服和客服组都指定了，则只有客服指定会生效。

grade=2 作用是强制分配，客服不在线会给该客服留言，不设置则客服不在线会分配给其他客服。

显示历史聊天记录

默认情况下，新对话开始的时候顾客需要往上滚动才能获取上一次对话的聊天记录。你也可以设置成新对话开始的时候直接读取上一次的聊天记录。

示例：

https://团队ID.ahc.ink/chat.html?history=true

什么是 UTM

UTM (URL tracking mark) 指自定义链接跟踪标识，是用于跟踪链接来源、媒介、关键词、内容、名称等信息的标识。 只需要在对外投放的广告链接中加入 UTM 参数，你就能够在对话时清楚顾客是从哪个广告渠道过来的。

如果我们有两个推广渠道，百度和知乎。

我在百度推广放置以下链接：

https://aihecong.com/?utm_source=百度

知乎回复或发表的问题里放置以下链接：

https://aihecong.com/?utm_source=知乎

上面链接过来的访客与我们对话时，就能分辨出是通过哪个推广渠道找到我们的（工作台对话时客服可以看到）。

UTM 有五个可用参数，可以帮助你更细分的掌握顾客来源情况。

只有 utm_source 是必须的参数，如果用到中文，建议用 JS 的 encodeURI() 函数进行编码。

示例：
比如我们做了百度竞价，投放的关键词为网站客服系统，投放的位置为搜索结果的前三位，按点击次数付费，我们的推广主题为简单好用的在线客服系统，那这个带 UTM 的网址就是：

UTM 网址生成器

如果觉得手动构建 UTM 参数麻烦，那就用我们的快速构建工具吧。