1 概述

1.1 工具包构成

电话工具包包含三部分：

• SDK部分：

• 纯JS代码，向应用提供JS API，包括可供应用调用的函数，及需要应用实现的回调函数

• 完成坐席登录，呼叫控制，事件通知等功能

• UI工具条（可选）：

• 登录、呼叫按钮，用户号码输入框等；坐席代表可直接用来拨打电话

• 状态展示区；向坐席展示当前的登录及呼叫状态。

• 提供标准的的界面，包括

• 可嵌入客户应用界面

• jsPhone

• 基于WebRTC技术实现，语音通信功能在浏览器中完成

• 对浏览器版本要求比较严格，PC网络环境要求严格，不支持一个坐席同时多个页面使用电话条

客户应用可以仅集成SDK部分，也可以包含UI工具条部分。

1.2 电话终端（接听设备）

电话工具包本身集成了“jsPhone”终端，坐席在浏览器中即可接听，不依赖任何外部设备，并且使用非常方便，但对浏览器版本有一定要求。

电话工具包也支持与外置的SIP终端配合（需要在SIP终端上配置坐席对应SIP账号、密码以及SIP服务地址）。

外置SIP终端包括

• SIP话机终端，例如方位、潮流、亿联等品牌，需要单独购买

• SIP软电话程序，例如Linphone、eyeBeam等等，需要单独下载安装

此外，坐席也可以使用PSTN电话作为接听设备。          具体来说

• PSTN电话可以是坐席自己的手机或者座机

• 在后台设置坐席绑定PSTN电话号码即可

• 接听时会产生话费成本

2 工具包集成说明

2.1 工具包文件说明

工具包所有文件打包在PhoneKit.zip中。

具体包括：

*/PhoneKit/js/PhoneKit.js           //工具包脚本*/PhoneKit/template/template.html   //电话条UI*/PhoneKit/js/jssip-3.3.6.min.js    //jsPhone依赖库*/PhoneKit/res                      //资源文件夹，包括来电铃音。

2.2 工具包导入

1. 将PhoneKit.zip解压到集成页面的同级目录，保持文件夹结构不变

2. 在页面头部引入js文件：

// 引入SDK<script src="/PhoneKit/js/PhoneKit.js"></script>// 引入jsPhone<script src="/PhoneKit/js/jssip-3.3.6.min.js"></script>

引入后在window作用域有该Sdk的对象：PhoneKit。

3. 在页面相应的地方嵌入电话条UI

<iframe
    id="pbFrame"    width="100%"
    frameborder="0"
    scrolling="no"
    style="border:0px;"
    src="/PhoneKit/template/template.html">
</iframe>

如果不使用UI工具条，则第3步不需要。但若要使用jsPhone，则需增加audio并关联

<audio id="pbAudio" width="1px" height="1px" autoplay></audio>// 页面加载后调用PhoneKit.setAudioStub(document.getElementById('pbAudio'));

2.3 工具包初始化

<script>    // 初始化工具包
    PhoneKit.initial({
      url: "{CTI服务器地址}",
      appSid: "{应用id}",
      agentNo: "{坐席号}",
      pwd: "{坐席密码}",
      onStatusEvent: function (data) {},
      onCallEvent: function (data) {},
      onConnEvent: function (connEvent) {},
    }, function(resp) {});</script>

初始化接口说明

PhoneKit.initial(params, callback)

params参数说明

参数名	说明
url	CTI服务器地址
appSid	应用id
agentNo	坐席号
seed	32位以内随机字符串（数字、字母）
spwd	加密坐席密码，md5(坐席密码+":"+seed)。采用此方式则不填pwd。
pwd	坐席密码
encryptNumber	"true"表示用户号码加密
onStatusEvent	坐席状态事件回调函数
onCallEvent	呼叫事件回调函数
onConnEvent	连接事件回调函数

callback回调函数返回对象，属性如下：

参数	说明
statusCode	"00000"表示成功
statusMsg	说明
data	json对象，包含以下属性
phoneType	话机类型
workStatus	工作状态：0:下班, 1:就绪, 2:未就绪
pstnNumber	座席绑定的PSTN电话号码
sipNumber	座席绑定的SIP分机号码
sipPwd	SIP登陆密码
wsAddr	jsPhone注册地址

3 回调接口

3.1 呼叫事件回调接口 onCallEvent

onCallEvent(data)

返data回对象，属性如下:

属性	说明
eventName	initiated, ringing, answered, completed, failed
appSid	应用id
agentNo	坐席号
agentNumber	坐席号码
conversationSid	会话id
callSid	呼叫id
failedCause	failed, no-answer, canceled，time-out
sipCause	呼叫客户失败原因（callSubtype=1时有效）
completedCause	time-limit
callType	呼叫类型。1：拨号呼入、2：后台外呼、3：拨号外呼、4：点击外呼
callSubtype	呼叫子类型。1-呼叫用户;2-呼叫坐席
callState	呼叫状态：idle,ringing,connected,
userNumber	用户号码。来电呼入或外呼的用户号码
userNumberType	客户号码类型。1：固话、2：手机
userArea	用户号码归属地信息
isBridged	eventName="answered"且isBridged="0"表示应答未桥接
coAgentNo	合作坐席，用于咨询转接等场景
userData	自定义数据
timestamp	时间戳

3.1.1 eventName与failedCause说明

eventName值	说明
"initiated"	呼叫发起
"ringing"	被叫振铃
"answered"	被叫应答
"completed"	呼叫结束
"failed"	呼叫失败

failedCause值	说明
"failed"	呼叫失败-呼出失败
"no-answer"	呼叫失败-无应答
"canceled"	呼叫失败-取消
"time-out"	呼叫失败-超时

3.1.2 callSubtype与callType说明

callSubtype/callType

cst/ct	1-拨号呼入	2-后台外呼	3-拨号外呼	4-点击外呼
1-呼叫用户			M	M
2-呼叫坐席	M	M		O

3.1.3sipCause 取值说明

2xx

• 200 应答

4xx

• 403 禁止呼叫

• 404 号码不存在

• 408 呼叫请求超时

• 480 无法呼通被叫

• 484 请求地址格式无效

• 486 被叫忙

• 487 呼叫被取消

5xx

• 500 服务端异常

• 502 网关异常

• 510 关机

• 511 停机

• 512 空号

• 513 暂时无法接通

• 514 正在通话中（被叫启用呼叫等待）

• 516 无应答

• 518 忙

• 519 呼入限制

• 520 呼出限制

• 521 拒接

• 522 呼叫转移

3.2 坐席状态事件回调接口 onStatusEvent

onStatusEvent(data)

返回data对象，属性如下:

参数	说明
eventName	"login","pause","ready","autoReady","completed"
appSid	应用id
agentNo	坐席号
workStatus	座席工作状态：ready,pause
pauseCause	暂停原因(workStatus=pause时有效)
wrapupTime	整理时间(秒数) pauseCause=wrapup时有效)
readyCause	就绪原因(workStatus=ready时有效)
timestamp	时间戳

pauseCause取值说明

eventName	pauseCause取值	说明
pause	wc,..	来自pase操作的自定义状态(description)值
completed	wrapup	挂机后开始整理，自动进入pause状态

readyCause取值说明

eventName	readyCause取值	说明
autoReady	wrapup	整理时间到，自动进入ready状态

3.3 连接事件回调接口

onConnEvent(connEvent)

返回字符串，取值如下：

connEvent
connected
disconnected
connect_fail
auth_fail
auth_succ

4 坐席状态管理接口

4.1 登入 login

PhoneKit.login(params, callback)

params对象包含以下属性

属性	说明
phoneType	1:SIP话机, 2:PSTN电话, 3:jsPhone。必选。
workStatus	1:就绪, 2:非就绪。可选。

callback回调函数返回对象，属性如下：

参数	说明
statusCode	"00000"表示成功
statusMsg	说明

除特殊说明外，以下接口的callback与此相同。

4.2 登出 logout

PhoneKit.logout(callback)

4.3 就绪 ready

PhoneKit.ready(callback)

4.4 暂停 pause

PhoneKit.pause(params, callback)

params对象包含以下属性

属性	说明
pauseCause	暂停原因，用户可自定义

5 呼叫控制接口

5.1 外呼

PhoneKit.callOut(params, callback)

params对象包含以下属性

属性	说明
userNumber	用户号码
userData	自定义数据，字符串，100字符以内
userCli	用户侧显号标识。需200828或以上版本
agentCli	坐席侧显号标识。需200828或以上版本

5.2 挂机

PhoneKit.hangup(callback)

5.3 桥接

用于话机设为自动应答，由坐席通过电话条控制接听的场景

PhoneKit.bridge(callback)

5.4 保持

PhoneKit.holdCall(callback)

5.5 取回

PhoneKit.retrieveCall(callback)