电话工具包(JS SDK) 文档_v1.0
1 概述
1.1 工具包构成
电话工具包包含三部分：
-
SDK部分：
-
纯JS代码，向应用提供JS API，包括可供应用调用的函数，及需要应用实现的回调函数
-
完成坐席登录，呼叫控制，事件通知等功能
-
UI工具条（可选）：
-
提供标准的的界面，包括
-
登录、呼叫按钮，用户号码输入框等；坐席代表可直接用来拨打电话
-
状态展示区；向坐席展示当前的登录及呼叫状态。
-
可嵌入客户应用界面
-
JsSIPPhone
-
基于WebRTC技术实现，语音通信功能在浏览器中完成
-
对浏览器版本要求比较严格，PC网络环境要求严格，不支持一个坐席同时多个页面使用电话条
客户应用可以仅集成SDK部分，也可以包含UI工具条部分。
1.2 电话终端（接听设备）
电话工具包本身集成了“jsSIPPhone”终端，坐席在浏览器中即可接听，不依赖任何外部设备，并且使用非常方便，但对浏览器版本有一定要求。
电话工具包也支持与外置的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 //jsSIPPhone依赖库
2.2 工具包导入
-
将PhoneKit.zip解压到集成页面的同级目录，保持文件夹结构不变
-
在页面头部引入js文件：
// 引入SDK
<script src="/PhoneKit/js/PhoneKit.js"></script>
// 引入jsSIPPhone
<script src="/PhoneKit/js/jssip-3.3.6.min.js"></script>
引入后在window作用域有该Sdk的对象：PhoneKit。
-
在页面中加入电话条UI
如果不使用UI工具条，则第3步不需要
参考template_b.html。
若使用jsSIPPhone，需在页面中添加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
|
坐席号
|
|
pwd
|
坐席密码
|
|
onStatusEvent
|
坐席状态事件回调函数
|
|
onCallEvent
|
呼叫事件回调函数
|
|
onConnEvent
|
连接事件回调函数
|
callback回调函数返回对象，属性如下：
|
参数
|
说明
|
|
statusCode
|
"00000"表示成功
|
|
statusMsg
|
说明
|
|
data
|
json对象，包含以下属性
|
|
phoneType
|
话机类型
|
|
workStatus
|
工作状态：0:下班, 1:就绪, 2:未就绪
|
|
pstnNumber
|
座席绑定的PSTN电话号码
|
|
sipNumber
|
座席绑定的SIP分机号码
|
|
sipPwd
|
SIP登陆密码
|
|
wsAddr
|
jsSIPPhone注册地址
|
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.3 sipCause 取值说明
2xx
4xx
-
403 禁止呼叫
-
404 线路失败
-
408 呼叫请求超时
-
480 无法呼通被叫
-
484 请求地址格式无效
-
486 被叫忙
-
487 呼叫被取消
5xx
3.2 坐席状态事件回调接口 onStatusEvent
onStatusEvent(data)
返回data对象，属性如下:
|
参数
|
说明
|
|
appSid
|
应用id
|
|
agentNo
|
坐席号
|
|
workStatus
|
座席工作状态：ready,pause
|
|
eventName
|
"login","pause","ready","completed"
|
|
pauseCause
|
暂停原因(workStatus=pause时有效)
|
|
readyCause
|
就绪原因(workStatus=ready时有效)
|
|
timestamp
|
时间戳
|
坐席状态事件说明
|
eventName
|
workStatus取值
|
事件说明
|
|
login
|
ready或pause
|
坐席登录成功，坐席状态为ready或pause
|
|
pause
|
pause
|
坐席暂停成功，坐席状态为pause
|
|
ready
|
ready
|
坐席就绪成功，坐席状态为ready
|
|
completed
|
pause
|
呼叫结束，坐席自动进入pause状态，用于整理
|
3.3 连接事件回调接口
onConnEvent(connEvent)
返回字符串，取值如下：
|
connEvent
|
说明
|
|
connected
|
WS已连接
|
|
disconnected
|
WS连接已断开
|
|
connect_fail
|
WS连接失败
|
|
auth_fail
|
鉴权失败
|
|
auth_succ
|
鉴权成功
|
|
sip_registered
|
JSSIP注册成功
|
|
sip_registeration_failed
|
JSSIP注册失败
|
|
sip_unregistered
|
JSSIP注册停止。当收到此回调后，应用必须调用login才能重新开始JsSIP注册
|
4 坐席状态管理接口
4.1 登入 login
PhoneKit.login(params, callback)
params对象包含以下属性
|
属性
|
说明
|
|
phoneType
|
1:SIP话机, 2:PSTN电话, 3:jsSIPPhone。必选。
|
|
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
|
用户侧显号标识
|
|
agentCli
|
坐席侧显号标识
|
5.2 挂机
PhoneKit.hangup(callback)
5.3 桥接
用于话机设为自动应答，由坐席通过电话条控制接听的场景
PhoneKit.bridge(callback)
5.4 保持
PhoneKit.holdCall(callback)
5.5 取回
PhoneKit.retrieveCall(callback)