====== 软电话工具条集成 ======

===== 应用场景 =====

您拥有自己的CRM系统，希望在CRM系统里实现一键拨打客户电话，或者希望将呼叫中心工作台嵌入CRM系统，实现客服人员直接在CRM系统里处理来电或拨打电话。

通过以下文档，您可以实现上述目的，下面的工作需要您公司的前端工程师来实施。


===== 安装或引入文件 =====

demo示意：

{{ :cs:500cloudcccintegration:签入后.png?nolink&600 |}}

使用方法：引入js文件。

如需获取源码包，请提供租户id并联系商务。

===== 服务器端准备工作=====

软电话SDK嵌入到了您的自有业务系统中，在初始化sdk时，需要您传入坐席对应的环信客服账号和密码用来初始化软电话工具条。

方法1：客服无需手动登录：在您的自有业务系统中，需要维护一套自有业务系统客服账号与环信客服账号的对应关系，需由您的后端根据登录的客服账号和对应关系获取到环信客服账号、密码，返回给您的前端，由您的前端调用初始化方法时传入。

方法2：客服手动登录：需要在您的自有业务系统页面上，实现环信客服账号及密码的输入框，由客服自行输入环信客服账号、密码后手动登录。

===== 初始化=====

==== 初始化必备工作 ====


   -  必须使用chrome浏览器，版本号为58以上。原因是云呼叫中心的通话是通过webRTC技术实现的，目前chrome浏览器对于webRTC技术的支持是最好的。为了保证您的通话质量及安全性，所以我们做出了这样的要求。
  -   软电话SDK所嵌入的自有业务系统必须使用https协议。原因是chrome在47版本之后，禁止http协议获取系统麦克风权限，会造成无法正常通话。
  -   如果您是在iframe标签内使用软电话SDK，那么需要为iframe标签增加 allow="microphone" 属性，来允许iframe标签获取系统麦克风权限。

==== 初始化SDK ====

在页面添加id为“id_name”的容器
<code><div id="id_name"></div></code>
 
配置示例:
<code>
HxCccSdk.callcenterInit({
    dom:"id_name", //挂载元素id
    name: "huanxin", //登录名
    password: "psd", //密码
    origin: "//kefu.easemob.com", //域名 默认为"//kefu.easemob.com"
    defaultVisible: true, // 默认是否展示工具条，参数类型：Boolean，默认为true
    phoneProtection: false //隐藏客户号码中间4位，座机号隐藏后4位，以*代替, 默认为false
    afterCallRule: 20, // 默认话后处理时间
    loginText: '环信电话签入', //签入按钮文案，可自定义
    monitor: false,  //是否使用监听功能，默认不使用
})
</code>

===== SDK方法=====

1.首次签入
<code>HxCccSdk.onRegister()</code>
自动检测当前是否符合云呼工具条初始化条件，若符合，则自动执行

2.签入
<code>HxCccSdk.logIn()</code>
签入（处于签出状态可调用），调用该方法实现上线操作

⚠️注：签入之前需要先加入呼叫技能组。

3.签出
<code>HxCccSdk.logOut()</code>
签出，调用该方法实现下线操作

4.拨打
<code>HxCccSdk.onCall("被叫号码")</code>
打电话，传入被叫号码即可

5.接听
<code>HxCccSdk.answer()</code>
接听电话，通过该方法可接听来电，建立通话连接

6.挂机
<code>HxCccSdk.hangUp()</code>
挂断，通过该方法可结束通话

7.通话保持
<code>HxCccSdk.callHold()</code>
通话保持，通过该方法可使通话进行保持，客户端听到的是一段音乐，坐席端说话客户端无法听到

8.通话取回
<code>HxCccSdk.callRetrieve()</code>
通话取回，通过该方法结束通话保持的状态，重新建立客户端和坐席端的通话

9.开始接听，恢复空闲状态
<code>HxCccSdk.ready()</code>
置空闲，通过该方法可将坐席置为空闲状态，空闲状态可接听、拨打电话。

10.监听
<code>hx.onMonitor(monitordn)</code>
监听功能，monitordn为被监听者的分机号

11.结束监听
<code>hx.stopMonitor()</code>
结束监听功能，恢复空闲

12.二次拨号
<code>hx.sendDtmf(number)</code>
外呼通话，需要按键时使用。number可为0~9，*或#

===== 监听当前工具条状态=====
<code>
window.addEventListener("message", function(msg){
	if(msg.data.easemob){
		var message = msg.data.easemob.kefu;
		for(var key in message){
			var type = key.toUpperCase();
			var value = message[key];
			switch (type) {
				case "ONINIT":
					console.log("工具条初始化")
					break;
                case "ONLOGIN":
                    console.log("签入")
                    break;
                case "ONREDAY":
                    console.log("空闲")
                    break;
                case "ONBREAK":
                    console.log("小休")
                    break;
                case "ONLOGOUT":
                    console.log("签出")
                    break;
                case "ONHANGUP":
                    console.log("挂机")
                    break;
                case "SENDDTMF":
                    var number = value.number;
                    console.log("二次拨号", number)
                    break;
                case "ONCALLCOMING": //来电时触发，用户可以在该函数内获取参数信息
		            var calee = value.calee;   //被叫
		            var caller = value.caller; //主叫
		            var contactId = value.contactId;  // 通话ID，
		            console.log(calee,caller)
		            break;			
                case "ONCALLDIALING":  // 去电、拨号振铃时触发，用户可以在该函数内获取参数信息
                    var calee = value.calee; //被叫
                    var caller = value.caller;//主叫
                    var contactId = value.contactId;  // 通话ID，
                    break;
                case "ONCALLESTABLISH": // 通话建立连接时触发
                    var caller = value.caller;
                    console.log(caller)
                    break;
                case "ONCALLRELEASE": // 通话结束时触发，
                    var caller = value.caller;
                    console.log(caller)
                    break;
				case "ONSTATUSCHANGE": //任何状态改变都会触发该函数，用户可在该函数内监听当前状态值的变化过程，状态code的含义请参考本文档状态对照表。
					var code = value.code;
					var lastCode = value.lastCode;
					console.log("当前状态："+code)
					console.log("上一个状态："+lastCode)
					break;
				case "ONERRORNOTIFY": //当有一些错误信息的时候触发，可以获取error信息
					var error = value.error;
					var errorMsgTip = error.errorMsgTip;
					console.log(error.errorCode +"--"+errorMsgTip);
					break;
				
			}
		}
	}
}
</code>

===== 状态对照及方法约束说明=====

|状态码|注释|描述(getStatus)|说明|
|-1|未注册|off|这时用户只能执行首次签入（即首次上线）操作|
|0|注册中|off||
|1|签出|off|这时用户只能执行签入（即上线）操作|
|2|签入|login|当用户签入后状态值变为2，签入成功后状态值马上变为3（即空闲）|
|3|空闲|ready|可执行拨号、签出（即下线）等操作，注：只有该状态下可收到外部打过来的电话（即振铃）|
|4|小休|break|可执行结束小休、签出（即下线）、拨号（操作）|
|5|话后处理|other|可执行签出（即下线）、继续工作(即开始接听)、再次拨打等操作|
|6|振铃|callComing|只可执行接听操作|
|8|拨号|dialingCall|只可执行挂机操作|
|9|呼入通话|inCall|可执行挂机、保持（即通话保持）操作|
|10|呼出通话|inCall|可执行挂机、保持（即通话保持）操作|
|11|内部通话|inCall|可执行挂机、保持（即通话保持）操作|
|12|通话保持|inCall|只可执行通话取回（通话取回）操作|
|21|监听中|monitoring|只可执行结束监听操作|


===== 操作逻辑错误 =====

以下参数格式为：errorCode：errorMsg/errorMsgTip
当出现as错误码和event签出时，都建议重新刷新页面登录。
<code>
{
// as返回的错误码
	KEFU_003:  '账号名/密码不正确',
	KEFU_122:  '您的账号已被禁用，请联系您的管理员',
	101:  '请使用chrome浏览器！',
	102:  '请使用58版本以上chrome浏览器',
	103:  '请切换为https协议！',
	104:  '您当前未属于任何技能组，请联系管理员为您添加',
	105:  '您所在的技能组没有外呼号码',
	106:  '您不在任何技能组中，请联系管理员进行添加',
	107:  '工具条已经初始化了,禁止再次调用',
	108:  '请设置挂载元素',
	109:  '云呼资质待审核',
	110:  '查询租户呼叫中心信息失败',
	111:  '请输入正确的电话号码',
	112:  '当前坐席状态未处于空闲或小休中，请空闲或小休时再回呼',
	114:  '没有可外呼的号码，请确定技能组是否绑定了外呼号码！',
	115:  '只有呼叫中心客服和全渠道客服可以使用云呼叫中心',
	116:  '话费余额小于50元(含)不允许外呼，请充值',
	200:  "注册中，请等待！"
	201:  "当前坐席已签出，请签入！"

    6001: '管理员不存在',
    6002: '管理员未登录',
    6003: '技能ID不存在',
    6004: '管理员ID不存在',
    6005: '当前状态忙碌，请求失败，请刷新页面后重试',
    6006: '当前状态忙碌，请求失败，请刷新页面后重试',
    6007: '当前状态忙碌，请求失败，请刷新页面后重试',
    6008: '当前状态不对',
    7001: '后端服务任务请求不对',
    7002: '您请求对应的电话已经不存在',
    8020: '该账号有人正在使用且在通话中',
    8021: '您的账号已在别处登录，如需登录请刷新页面', // 界面提醒，按钮不可点
    8022: '需重新加载配置', // 这个配置如何展示
    8001: '请检查声卡权限', // 提示设备异常的界面
    8002: '请检查声卡权限', // 提示设备异常的界面

    `以下为迁出的event事件:`
    AB_normal: '软电话正常签出',
    ASM_Private: '坐席管理服务连接超时，请检测网络连接情况', // '私协超时',
    ASM_SIP: '语音服务连接超时，请检测网络连接情况', // 'SIP 30秒超时',
    'ASM_Private&SIP': '坐席管理服务和语音服务连接超时，请检测网络连接情况', // '私协和SIP都超时',
    ka_unregister: '您的账号已在别处登录，如需登录请刷新页面', // ka发送的unregister签出
    KA_register: '您的账号已在别处登录，如需登录请刷新页面' // 'KA发送的register',
    // WS连接缓慢
    WSConnectSlowly: '当前WebScoket连接缓慢，请等待或刷新后重新上线',
    // 坐席没有配置技能组
    systemErrorNotInAnySkillGroup: '您尚未被加入到技能组中，暂时无法使用，请联系呼叫中心管理员添加',
 }
</code>

===== 后续工作 =====

==== 获取通话记录 ====

如果您要在您的自有业务系统查看历史通话，就需要将环信客服云的历史通话记录同步到您的自有业务系统。

同步方式：
  - 调用api平台【获取历史通话列表】接口，详情请参考[[cs:400systemintegration:api-open-platform#获取历史通话列表|API开放平台]]。
  - 通过自定义事件推送，将通话详单及录音推送至您的服务器。具体请参考 [[cs:400systemintegration:20webhook|自定义事件推送]]-呼叫事件推送。

注：api开放平台和自定义事件推送为旗舰版标准功能，标准版和企业版增值功能。

===== 常见问题 =====

 - 自有业务系统集成软电话条后，同一个客服账号可以既在环信客服云登录，又在自有业务系统使用云呼吗？
  不可以。同一个账号只能同时登录一个系统，在自有业务系统已签入云呼的前提下，再登录环信客服云，自有业务系统客服账号会下线，云呼会签出。
 - 同一个浏览器，可以用一个账号登录环信客服云，用另一个环信客服账号登录自有业务系统，签入云呼吗？
  不可以。同一个浏览器只能同时登录1个环信客服云账号。使用浏览器隐身窗口可以登录2个账号。