全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件

访客名片文档

更新时间:2018-03-23 10:42:28

1. 概述

我们在云客服在线/热线工作台中有一部分区域,通过iframe嵌入或接口调用的方式来展示租户的个性化数据,用于辅助客服人员在服务客户时的相关信息查询过程。在iframe场景中,客服有客户进入时,父页面会在用户配置的iframe域名后拼接请求参数,租户的子页面解析请求参数进行业务逻辑处理。租户的技术人员可以根据我们的对接规则,在iframe子页面中编写js脚本与父页面传递信息,父页面根据这些信息作出对应动作。如重置iframe区域的宽、高,将来访客户的客户ID与云客服平台的服务记录关联,关联后可以在云客服平台的服务记录页面使用租户业务相关的用户ID进行查询,其他信息及对应规则不多赘述。此外,云客服页面也提供了数据展示组件,租户可以直接提供HTTP-POST服务处理查询请求,按照云客服规定的解析规则返回数据,页面的数据展示组件解析返回的数据进行展示。

2. 名词解释

名词 说明
租户 购买云客服产品的公司
访客名片 用户展示租户客户信息等业务逻辑的区域,默认提供的是云客服平台自带的CRM访客名片,同时也支持iframe嵌入租户自己的页面进行定制化展示
聊天窗 在线服务的入口,客户发送信息、查收坐席回复信息的页面
弹屏 热线工作台来电时页面对应的动作,一般为生成一条对应的服务记录,客服根据电话沟通来操作服务记录
CRM系统 客户关系管理系统(CRM)是以客户数据的管理为核心,利用信息科学技术,实现市场营销、销售、服务等活动自动化,并建立一个客户信息的收集、管理、分析、利用的系统,帮助企业实现以客户为中心的管理模式。
AES对称性加密 采用AES128位密钥进行对称性加密算法,在云客服对接用户访客名片时,作为加密查询用户参数的加密方式。采用对称性加密的原因为RSA加密算法加密信息长度有限,最长不可超过111字节,由于查询用户信息参数过长,故采用AES对称性加密算法
RSA非对称性加密 采用RSA2048非对称性加密算法,云客服保存私钥(采用蚂蚁金融云KMS加解密管理平台,采用国家信息安全局认可密码机进行密钥保管),用户系统保存公钥,在每次信息传递时,采用RSA算法对随机生成的AES非对称性加密算法的密钥进行加密

3. 接入详述

3.1 配置方式

进入云客服平台侧边菜单栏中的“配置管理”下的“组件配置”菜单。在第一栏“访客名片”标签页进行配置。访客名片URL可以配置对应租户的页面/请求的URL,为空会默认使用云客服平台自带的用户管理页面。在输入正确的URL后,选择租户期望的对接方式(页面嵌入or外部请求),点选保存即可。

3.2 iframe嵌入

3.2.1 整体流程

用户首先需要按照配置方式进行正确的配置,配置好后,进入在线/热线工作台会发现对应的嵌入效果。访客名片满足如下特点:

1.云客服平台的相关信息(如热线电话的主叫号码、在线聊天窗埋点信息等)由云客服平台加密后作为参数拼装在URL中,对应为HTTP-GET请求;

2.请求参数固定为三项,分别为:paramskeyiframeKey,如下面例子所示:

  1. 假设在“组件配置”页面配置的“访客名片URL”为:
  2. https://www.alipay.com/iframe.htm
  3. 且“名片嵌入方式”选择为“页面嵌入”,那么在客服在使用云客服平台时iframe区域嵌入的URL如下所示:
  4. https://www.alipay.com/iframe.htm?params=***&key=***&iframeKey=***
  5. 其中各参数属性对应含义:
  6. params AES对称性加密后的业务参数JSON字符串
  7. key RSA非对称性加密后的AES密钥
  8. iframeKey 服务记录TAB-ID

3.用户的访客名片页面按需满足下列三种场景的使用方式,分别为热线工作台弹屏使用、在线聊天工作台使用、服务记录详情页面使用。由于这三种场景不同,页面URL拼装参数params中加密前的JSON串内的参数也对应不同,对应参数的解密方法在第4部分详述;

4.云客服平台客服服务产生的服务记录预留userId字段用户关联租户CRM系统中客户的唯一ID,租户在解析ifame请求后可以定位用户,并通过页面javaScript脚本按照固定规则将用户ID传递到父页面,将用户ID关联到服务记录中。对应的javaScript脚本编写规则在第5部分详述;

5.iframeKey为云客服用于区分服务记录TAP页使用,用户应将iframeKey不做任何更改在iframe子页面JS中回传至云客服工作台中。

6.参数params的解密方式在第4部分解密详细描述,解密后为JSON字符串。参数key为解密时的密钥。params解密后的样例如下:

  1. {"tel":"18910561093","agentId":"00001","sourceType":"hotline","contactId":"201801041113010100000000379088","timestamp":"1514736000000"}

下面的条例会根据不同的客服工作场景,详细介绍对应场景的页面动作和params加密前JSON串内的详细参数,帮助租户研发人员理解。

3.2.2 热线弹屏

此场景为热线工作台嵌入场景,一般为客服接打电话时使用。

3.2.2.1 流程步骤

客服在电话接通后,热线工作台生成服务记录,加载租户的访客名片,其中参数包括来电号码、服务来源等重要信息,访客名片定位到用户后通过JS脚本将userId返回给父页面,此时服务记录会关联iframe子页面回传的userId,如果用户访客名片没有根据来电号码等信息定位到用户,也可通过客服点选进行手动关联,同样的,访客名片只需要用过JS脚本回传userId即可,且同一条服务记录可以进行多次关联,以最后一次为准。

3.2.2.2 JSON参数说明
名称 类型 可空 字段限制 描述
agentId String 64 热线座席的工号
sourceType String 32 online 在线、hotline热线 页面嵌入时需要根据此参数判断展示类型,在线为纵向展示,热线为横向展示
tel String 32 用户的电话号码
contactId String 64 服务记录ID,供接入方处理个性化业务与服务记录之间的关联关系 例如:业务自有工单需要与云客服平台服务记录做关联的场景中
timestamp String 32 生成事件Unix时间戳

3.2.3 在线聊天

此场景为在线工作台嵌入场景,一般为客服在线聊天时使用。

3.2.3.1 流程步骤

客服在接入访客后,在线工作台生成服务记录,加载租户的访客名片,其中参数聊天窗埋点信息、服务来源等重要信息,访客名片定位到用户后通过JS脚本将userId返回给父页面,此时服务记录会关联iframe子页面回传的userId,如果用户访客名片没有根据埋点参数等信息定位到用户,也可通过客服点选进行手动关联,同样的,访客名片只需要用过JS脚本回传userId即可,且同一条服务记录可以进行多次关联,以最后一次为准。

3.2.3.2 JSON参数说明
名称 类型 可空 字段限制 描述
extInfo String 2048 业务个性化信息,由埋点接入端写入,云客服平台透传给第三方接入组件示例:”extInfo”:{“uid”:”123245”,” customerInfo”:”5” },其中”uid”、”customerInfo”的key值,接入组件可自行定义(详情见在线聊天窗埋点接入
)sourceType String 32 online 在线、hotline热线 页面嵌入时需要根据此参数判断展示类型,在线为纵向展示,热线为横向展示
contactId String 64 服务记录ID,供接入方处理个性化业务与服务记录之间的关联关系 例如:业务自有工单需要与云客服平台服务记录做关联的场景中
timestamp String 32 生成事件Unix时间戳

3.2.4 服务记录历史页面

服务记录详情页面嵌入,用于回显当时服务的用户的相关信息。

3.2.4.1 流程步骤

服务记录在关联userId后,可以在“服务记录”页面针对关联的userId进行查询对应客户的历史服务情况,点击“详情”进入服务记录详情页面,该页面也会嵌入租户的访客名片,此时JSON参数中包含服务时访客名片回传的userId,嵌入页面会根据回传参数中的userId进行回显租户业务信息。

3.2.4.2 参数说明
名称 类型 可空 字段限制 描述
userId String 32 回传参数中的userId
sourceType String 32 online 在线、hotline热线 页面嵌入时需要根据此参数判断展示类型,在线为纵向展示,热线为横向展示
contactId String 64 服务记录ID,供接入方处理个性化业务与服务记录之间的关联关系 例如:业务自有工单需要与云客服平台服务记录做关联的场景中
timestamp String 32 生成事件Unix时间戳

3.3 接口调用

除iframe嵌入方式外,云客服平台还会提供默认的访客名片,租户方只需要提供HTTP-POST接口,默认的访客名片固定只提供三个查询条件,分别为“客户ID”、“电话号码”、“客户证件号码”。客服在服务客户时可以根据默认的三个查询条件进行查询,如输入客户证件号码进行查询。接口返回满足业务需求的JSON字符串,云客服默认访客名片会解析JSON字符串进行展示,前提是JSON字符串满足规定的解析规则。如果返回数据中存在userId,那么当前客服服务的服务记录中会关联该userId。此外,在服务开始时,在热线/在线/服务记录详情三种场景中,针对不同的场景加密前的JSON串中不同的默认参数进行“预查询”操作,这种操作针对客户接入客服后,云客服平台根据能获得到的信息进行“预查询”,如电话号码、在线聊天窗埋点字段、服务记录详情回显时关联服务记录的userId。

3.3.1 整体流程

1.云客服平台的相关信息(如热线电话的号码、在线聊天窗埋点信息等)由云客服平台加密后作为参数拼装在URL中,对应为HTTP-POST请求;

2.请求参数固定为两项,分别为:paramskey,如下面例子所示:

  1. 假设在“组件配置”页面配置的“访客名片URL”为:
  2. https://www.alipay.com/data.json
  3. 且“名片嵌入方式”选择为“外部请求”,那么在客服在使用云客服平台时,平台默认提供展示数据的组件会通过HTTP-POST请求调用接口:
  4. https://www.alipay.com/data.json?params=***&key=***
  5. 其中各参数属性对应含义:
  6. params AES对称性加密后的业务参数JSON字符串
  7. key RSA非对称性加密后的AES密钥

3.针对返回的数据,云客服工作台页面自带的数据展示组件会按照特定规则进行对返回数据的解析(参照3.3.4解析规则),解析成功后展示对应的数据;

4.参数params的解密方式在第4部分解密详细描述,解密后为JSON字符串。参数key为解密时的密钥。params解密后的样例如下:

  1. {"tel":"18910561093","timestamp":"1514736000000"}

3.3.2 JSON参数说明

名称 类型 可空 字段限制 描述
tel String 32 电话号码
extInfo String 2048 聊天窗埋点信息(详情见在线聊天窗埋点文档
userId String 64 租户CRM中的用户ID
cardId String 32 用户证件号码
timestamp String 32 Unix时间戳

3.3.3 关于“预查询”场景

热线工作台:在客户电话接通的时刻,使用客户来电号码(tel)作为预查询条件,进行预查询。在线工作台:客户与在线人工客服建立连接时,使用用户的聊天窗埋点信息(extInfo)作为预查询条件。服务记录详情:使用服务记录关联的用户ID(userId)作为请求参数进行回显。

3.3.4 返回数据格式

返回的JSON数据中,userId为必填字段,云客服平台会以此数据作为客户的唯一标识,并保存在云客服平台服务记录中。该字段不用再schema中做字段信息的描述。示例:关键字段说明如下:success: 接口请求状态是否成功:成功true,失败falsemessage: 接口消息,自定义,会在云客服平台展示result: 业务数据和格式,字段的展示顺序根据schema中的描述顺序进行展示

  1. {
  2. "message": "查询成功",
  3. "success": true,
  4. "result": {
  5. "telePhone": "11111111111",
  6. "customerName": "招商银行苏州分行",
  7. "userName": "test",
  8. "email": "wangqy1@hundsun.com",
  9. "userId": "0CE0540B-E351-4B83-B47F-72A2E8D2479E",
  10. "customerNo": "77777",
  11. "account": "77777",
  12. "mobile": "",
  13. "schema": {
  14. "properties": {
  15. "customerName": {
  16. "name": "客户名",
  17. "type": "text"
  18. },
  19. "account": {
  20. "name": "客户帐号",
  21. "type": "text"
  22. },
  23. "userName": {
  24. "name": "联系人",
  25. "type": "text"
  26. },
  27. "telePhone": {
  28. "name": "电话",
  29. "type": "text"
  30. },
  31. "email": {
  32. "name": "邮箱",
  33. "type": "text"
  34. }
  35. }
  36. }
  37. }
  38. }

3.3.5 注意事项

  1. 1.接入方提供的web接口的服务端必须支持跨域,因为请求是从云客服网站发出的,如果web接口的服务端不支持跨域,会被浏览器拦截。跨域解决方案可自行搜索CORS获取
  2. 2.接入方提供的web接口协议必须是https
  3. 3.接入方提供的web接口响应头中的Content-Type必须为application/json; charset=utf-8

4. 解密

4.1 解密步骤

  1. 从http请求中获取对应参数,分别是params,key
  2. 将用户公钥还原成PublicKey类型
  3. 调用CustomerInfoCryptoUtil.decryptByPublicKey(params, key, publicKey)方法进行解密

4.2 maven依赖

  1. <repository>
  2. <id>central</id>
  3. <url>http://mvn.cloud.alipay.com/nexus/content/groups/public</url>
  4. <snapshots><enabled>true</enabled></snapshots>
  5. </repository>
  6. <dependency>
  7. <groupId>com.alipay.fc.csplatform</groupId>
  8. <artifactId>fccsplatform-common-crypto</artifactId>
  9. <version>1.0.0.20161108</version>
  10. </dependency>

jar包也可以联系技术支持获取。

4.3 Java-Demo

  1. public class Test {
  2. //注意:该公钥仅供demo示范使用,用户公钥请联系技术支持获取。
  3. private static String pub_key = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp5khaVZIP+x+n+ari3c1dcYRuNG7BUL0VVt1X2+KDcOpTHtfdHUQIzrHdbikZSyaCKyHLbAuLsU24gulCKmMGtjFGS6OiavUFFikVnVnOyEzcnhSPBiJNdlUo5TNYOVN1SUCutJUxvibQ1za6IcnHf4okgPTgcrXVHyG5ntCbE9ippKLe7q0z0TUIkRxesbKZiQPBDOgBukJUiFMk95zqCdESCe6kCSp2GdIojyVAelU11JIcAm/4OjCCFMz6Jcnse7rdScxRsoMHU89tDmXG9mo3PhUXyfQJzyESlotKek99eHPkSr7EW/SBj3xMc+ysrBZd+4tFOZJIRIlFf/eSQIDAQAB";
  4. //还原出RSA公钥对象
  5. private static PublicKey getPubKey() throws Exception {
  6. X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64Util.decode(pub_key));
  7. KeyFactory keyFactory;
  8. keyFactory = KeyFactory.getInstance("RSA");
  9. PublicKey key = keyFactory.generatePublic(keySpec);
  10. return key;
  11. }
  12. public static void main(String[] args) throws Exception {
  13. String params = request.getParameter("params");
  14. String key = request.getParameter("key");
  15. PublicKey publicKey = getPubKey();
  16. String cinfo = CustomerInfoCryptoUtil.decryptByPublicKey(params, key, publicKey);
  17. JSONObject dataJsonObject = JSON.parseObject(cinfo);
  18. //加验时间戳
  19. Date requestDate = new Date(dataJsonObject.getLong("timestamp"));
  20. Date now = new Date();
  21. //...
  22. //TODO 业务处理
  23. }
  24. }

4.4 常见解密问题

data must start with zero

解决方式:URLEncode解密方法入参参数

  1. CustomerInfoCryptoUtil.decryptByPublicKey(URLEncoder.encode(params, "UTF-8"), URLEncoder.encode(key,"UTF-8"), publicKey);

5. iframe对接规范

iframe方式接入的访客名片和云客服页面之间通过浏览器的 window.postMessage进行双向数据交互。

访客名片页面只需要在适当时机将数据发送给云客服页面,即可完成iframe页面高度自适应、关联userId到服务记录等操作,详见后续章节。

5.1 postMessage数据结构

5.1.1 参数描述

由于postMessage只支持传递字符串,为了方便进行数据解析,我们规定传递的数据为标准的JSON格式字符串。详细的字段定义如下:

名称 类型 可空 描述
type String 接口类型
iframeKey String 区分iframe页面用,从url中获取iframeKey参数,原封不动回传即可
resource String 固定为:csbridge
data mix 接口需要的业务数据,不同的接口data字段的值要求也不一样,详见下面接口列表中说明

5.1.2 示例

下面是一个基于上述数据结构封装的通用函数及调用示例

  1. function sendMessage(type, data) {
  2. const params = {};
  3. params.type = type;
  4. params.data = data;
  5. params.resource = 'csbridge';
  6. params.iframeKey = '1'; // 从url参数获取,示例假设值为1
  7. window.parent.postMessage(JSON.stringify(params), '*');
  8. }
  9. sendMessage('updateHeight', 300); // 更新iframe容器高度
  10. sendMessage('updateTitle', '王某某来电'); // 修改热线来电tab标题

5.2 接口列表

访客名片目前会使用在热线工作台,在线工作台,服务记录详情页三个地方,每个地方适用的接口都不同,下方接口明细中会指明接口的适用范围,请知悉

5.2.1 更新iframe高度

接口名(type)

updateHeight

参数(data)

需要设定的高度,数值格式

适用范围

热线工作台,在线工作台,服务记录详情页

示例
  1. sendMessage('updateHeight', 300);

5.2.2 更新用户信息

接口名(type)

updateUserInfo

业务数据(data)

需要更新的用户信息,json格式,定义的有效字段如下:

名称 类型 可空 描述
userId String 来访用户id,非常重要,用来关联服务记录
userName String 来访用户名称
适用范围

热线工作台,在线工作台

示例
  1. sendMessage('updateUserInfo', {
  2. "userId": "2088212121",
  3. "userName": "王某某"
  4. });

5.2.3 更改来电tab标题

接口名(type)

updateTitle

业务数据(data)

需要更新标题,字符串格式

适用范围

热线工作台

示例
  1. sendMessage('updateUserInfo', '王某某来电');

5.2.4 发起一个外呼

接口名(type)

outcall

业务数据(data)

需要外呼的号码,字符串格式

适用范围

热线工作台

示例
  1. sendMessage('outcall', '13333333333');

5.2.5 结束善后

接口名(type)

workRoundUp

业务数据(data)

适用范围

热线工作台

示例
  1. sendMessage('workRoundUp');

5.2.6 关闭当前来电tab

接口名(type)

closeCurrentTab

业务数据(data)

示例
  1. sendMessage('closeCurrentTab');
本文导读目录