一、场景说明
使用电话条对接,可以将云客服的电话条功能外呼、挂断、转接咨询等能力集成到您自己的业务系统中,在您自己的业务系统使用此功能。 注意:WEBRTC登陆方式请尽可能使用Chrome浏览器并使用HTTPS协议。
二、对接步骤
1、安装
NPM
npm install ue-softphone-sdk
import ueSoftPhone from 'ue-softphone-sdk'var ue = new ueSoftPhone ({ // 参数 })
CDN
<script src="https://cdn.jsdelivr.net/npm/ue-softphone-sdk@4.0.16/dist/lib/ue-soft-phone.min.js"></script>
注:4.0.16为当前版本号,后期电话条版本升级后,会修改对应版本号。cdn模式请把引入的script放在body中。
2、电话条初始化方法
var ue = new ueSoftPhone (Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
accountName | string | — | — | 是 | 座席账号,如6000@ykf |
password | string | — | — | 是 | 座席密码 |
loginType | string | PSTN / SIP / WEBRTC | PSTN | 否 | 登陆类型 1.手机、2.SIP话机、3.WEBRTC |
server | string | _ | __ | 否 | callApiUrl |
isOpenNetwork | boolean | true开启,false关闭 | false | 否 | 是否开启网络检测 |
pushCallinRingStatistics | boolean | true开启,false关闭 | false | 否 | 坐席callin来电振铃,是否推送ivr按键信息,排队时间,3天内来电次数 |
pushHangupStatistics | boolean | true开启,false关闭 | false | 否 | 坐席hangup挂机事件事件,是否推送坐席当日通话时长、当日通话次数。 |
isOpenCallQueue | boolean | true开启,false关闭 | false | 否 | 是否开启呼叫队列,查看实时排队情况 |
volume | object | interval: 100-5000 默认值500 | false | 否 | 是否开启音量检测。interval为音量检测的间隔 |
debug | boolean | — | false | 否 | 是否开启控制台日志 |
success | function | — | — | 否 | 座席初始化成功的回调函数 |
error | function | — | — | 否 | 座席初始化异常的回调函数 |
初始化请求参数示例:
window.ue = new ueSoftPhone({
accountName: '8088@useasy',
password: '123456Aa',
loginType: 'WEBRTC',
success(res) {
console.log(787877,res);
},
error:function(res) {
console.log('error',res);
}
})
3、监听通话事件
ue.listenCallEvent(Object object)
参数:
属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 事件绑定通道建立成功回调 |
message | function | — | — | 否 | 通话事件回调 具体看res.data参数说明 |
error | function | — | — | 否 | 事件绑定异常回调 主要是底层链接ws的异常回调 |
event | function | — | — | 否 | 捕获相同坐席登录多个的回调 |
object.message
回调函数参数Object res
属性 | 类型 | 说明 |
subType | string | — |
data | object | — |
Object res.data
名称 | 类型 | 说明 |
accountId | string | 账户编号 |
agentNumber | string | 座席编号 |
state | string | 状态编号,0:空闲、1:忙碌、2:呼叫中、3:振铃、4:通话中、5:整理、6:保持、7:静音、8:未连接、9:失效、10:咨询、 11:三方、 12:咨询(被咨询方)、 13:三方(被咨询方)100之后为自定义 |
stateName | string | 状态名称 |
callType | string | 通话类型,呼入:callin,外呼:callout,双向呼叫:twoWayCall,外呼任务:callTask,自动外呼:autoCallout |
queueNumber | string | 技能组编号 |
customerNumber | string | 客户号码 |
taskId | string | 任务id |
eventTime | string | 事件发生时间 |
defaultState | string | 默认登录状态 |
defaultStateName | string | 默认登录状态名称 |
callId | string | 通话ID |
eventType | string | 通话事件:呼叫:calling,振铃:ring,接通:link,挂机:hangup |
disNumber | string | 外显号 |
serviceNumber | string | 服务号 |
extras | string | 扩展参数 |
ivrKey | string | ivr按键信息,如1_2,多个按键之间以_分隔开,仅限于callin事件且pushCallinRingStatistics为true的情况下推送 |
queueDuration | int | 排队时间,单位为秒。仅限于callin事件且pushCallinRingStatistics为true的情况下推送 |
threeDayCallinTimes | int | 三天内来电次数。仅限于callin事件且pushCallinRingStatistics为true的情况下推送 |
dailyCallDuration | int | 当日通话时长,单位为秒。仅限于hangup事件且初始化时pushHangupStatistics为true情况下推送 |
dailyCallTimes | int | 当日通话次数。仅限于hangup事件且初始化时pushHangupStatistics为true情况下推送 |
dailyConnectTimes | int | 当日接通次数。仅限于hangup事件且初始化时pushHangupStatistics为true情况下推送 |
4、监听网络检测事件
ue.listenCallNetork(监听网络检测事件)
ue.listenCallNetork({
message(res) {
console.log(res);
}
})
message返回值
{
delay: 网络检测数值
}
属性 | 类型 | 说明 |
success | function | 事件绑定成功回调 |
error | function | 事件绑定异常回调 |
message | function | 网络检测事件回调,检测值res以json返回 |
5、监听呼叫队列
可使用此方法监听呼叫队列listenCallQueueEvent
// 监听呼叫队列socket
ue.listenCallQueueEvent({
success(res) {
console.log('监听呼叫队列socket成功',res);
},
message(res) {
console.log(res, '获取呼叫队列数据成功')
}
})
初始化队列数据
{
"success": true,
"message": "200 ok!",
"code": "200",
"data": [
{
"accountId": "1090",
"queueNumber": "10000187",
"queueName": "新需求",
"onlineCount": 1,
"idleCount": 1,
"callingCount": 0,
"currentWait": 0,
"online": [
"8006"
],
"groupLeader": [],
"idle": [
"8006"
],
"calling": [],
"currentQueue": []
},
{
"accountId": "1090",
"queueNumber": "10000188",
"queueName": "杨测试",
"onlineCount": 1,
"idleCount": 1,
"callingCount": 0,
"currentWait": 0,
"online": [
"8006"
],
"groupLeader": [],
"idle": [
"8006"
],
"calling": [],
"currentQueue": []
},
{
"accountId": "1090",
"queueNumber": "10000210",
"queueName": "ftest",
"onlineCount": 1,
"idleCount": 1,
"callingCount": 0,
"currentWait": 0,
"online": [
"8006"
],
"groupLeader": [],
"idle": [
"8006"
],
"calling": [],
"currentQueue": []
},
{
"accountId": "1090",
"queueNumber": "10000218",
"queueName": "8073",
"onlineCount": 1,
"idleCount": 1,
"callingCount": 0,
"currentWait": 1,
"online": [
"8006"
],
"groupLeader": [],
"idle": [
"8006"
],
"calling": [],
"currentQueue": [
{
"ivrId": null,
"callId": "740036808283537408",
"queueNumber": "10000218",
"trunkNumber": "02120775542",
"customerNumber": "13520558188",
"displayNumber": "",
"queueStartTime": "2023-11-23 16:54:26",
"waitDuration": 5938869,
"queueName": "8073"
}
]
},
{
"accountId": "1090",
"queueNumber": "10000579",
"queueName": "8006",
"onlineCount": 1,
"idleCount": 1,
"callingCount": 0,
"currentWait": 0,
"online": [
"8006"
],
"groupLeader": [],
"idle": [
"8006"
],
"calling": [],
"currentQueue": []
}
]
}
获取socket 呼叫队列
{
"subtype": "queue",
"data": {
"accountId": "1090",
"queueNumber": "10000210",
"queueName": "ftest",
"onlineCount": 1,
"idleCount": 1,
"callingCount": 0,
"currentWait": 0,
"online": [
"8006",
"8010"
],
"groupLeader": [
"8010"
],
"idle": [
"8006"
],
"calling": [],
"currentQueue": []
}
}
6、监听通话音量(webtrc模式可用)
可使用此方法监听通话音量listenCallVolume
开启音量检测
ue.listenCallVolume({
success(res) {
console.log('监听音量检测-->success',res);
},
message(res) {
console.log('监听音量检测-->message',res);
},
error(res) {
console.log('监听音量检测-->error',res);
}
})
关闭音量检测
window.ue.stopListenVolume({
success(res) {
console.log(res,'关闭音量监听成功')
},
error(error) {
console.log(error,'关闭音量监听失败')
}
})
三、通话能力方法
1、外呼
ue.call.callout(Object object)
参数:
属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
customerNumber | string | — | — | 是 | 外呼号码 |
agentTimeout | string | — | — | 否 | 呼叫座席侧超时时间,默认60秒 |
customerTimeout | string | — | — | 否 | 呼叫客户侧超时时间,默认120秒 |
customerDisNumber | string | — | — | 否 | 指定呼叫客户外显号码 |
agentDisNumber | string | — | — | 否 | 指定呼叫座席外显号码 |
loginType | string | PSTN / SIP / WEBRTC | PSTN | 否 | 登陆类型 1.手机、2.SIP话机、3.WEBRTC |
numberGroupName | string | — | — | 否 | 号码组名称,传该值,会查找对应名称的号码组,并根据策略选择外显号。未找到号码组按照没传处理 |
numberGroupId | string | — | — | 否 | 号码组编号,传该值,会查找对应Id的号码组,并根据策略选择外显号。未找到号码组按照没传处理,号码组名称和id同时存在时,优先根据编号查找号码组 |
extras | string | — | — | 否 | 自定义参数,通话中通过事件推送,通话后通话记录中可以查询搜索和定位 限制字节数为255个 超出则报错。 |
success | function | — | — | 否 | 外呼成功回调 |
fail | function | — | — | 否 | 外呼失败回调 |
2、挂断
ue.call.hangup(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 挂机成功回调 |
fail | function | — | — | 否 | 挂机失败回调 |
3、保持或取消保持
ue.call.holdOrUnHold(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 调用成功回调 |
fail | function | — | — | 否 | 调用失败回调 |
type | string | — | — | 是 | 操作类型 |
object.type 的合法值
值 | 说明 |
1 | 保持 |
2 | 取消保持 |
4、静音或取消静音
ue.call.muteOrUnMute(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 调用成功回调 |
fail | function | — | — | 否 | 调用失败回调 |
type | string | — | — | 是 | 操作类型 |
object.type 的合法值
值 | 说明 |
1 | 静音 |
2 | 取消静音 |
5、转接
ue.call.transfer(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 调用成功回调 |
fail | function | — | — | 否 | 调用失败回调 |
agentNumber | string | — | — | 否 | 当前座席工号 |
number | string | — | — | 是 | 转接号码、或转接的座席工号 |
type | string | — | — | 是 | 转接类型 |
object.type 的合法值
值 | 说明 |
agent | 座席 |
outline | 外线电话 |
ivr | 语音导航 |
6、咨询
ue.call.consult(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 调用成功回调 |
fail | function | — | — | 否 | 调用失败回调 |
agentNumber | string | — | — | 是 | 当前需要发起咨询的座席工号 |
number | string | — | — | 是 | 可传入,外线号码, 座席工号, 技能组编号例如:15010xxxx, 8000, 10014640 |
mode | string | — | — | 是 | 咨询类型 |
object.mode 的合法值
值 | 说明 |
agent | 座席 |
outline | 外线电话 |
ivr | 语音导航 |
7、取消咨询
可保持咨询状态继续咨询其他人
ue.call.cancelconsult(Object object)
参数:
属性 | 类型 | 可选值 | 默认值 | 必传 | 说明 |
success | function | — | — | 是 | 调用成功回调 |
fail | function | — | — | 是 | 调用失败回调 |
8、结束咨询
结束当前咨询,回到跟客户的通话
ue.call.endConsult(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 是 | 调用成功回调 |
fail | function | — | — | 是 | 调用失败回调 |
9、咨询接回
ue.call.callbackConsult(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 是 | 调用成功回调 |
fail | function | — | — | 是 | 调用失败回调 |
10、咨询转接
ue.call.consultTransfer(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 是 | 调用成功回调 |
fail | function | — | — | 是 | 调用失败回调 |
11、三方
ue.call.threeWayCall(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 是 | 调用成功回调 |
fail | function | — | — | 是 | 调用失败回调 |
12、满意度评价
ue.call.evaluate(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 调用成功回调 |
fail | function | — | — | 否 | 调用失败回调 |
type | string | — | — | 是 | 要转接的IVRl类型 如SATISFACTION |
13、会议
ue.call.meeting(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 调用成功回调 |
fail | function | — | — | 否 | 调用失败回调 |
number | string | — | — | 是 | 转接号 |
四、坐席相关方法
1、切换接听方式
ue.agent.switchLoginType(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
loginType | string | PSTN / SIP / WEBRTC | PSTN | 是 | 登陆类型 1.手机、2.SIP话机、3.WEBRTC |
loginNumber | string | — | 系统绑定的手机号 或者 SIP号 | 否 | 手机模式:需要更换坐席绑定的手机号时,该字段传新的绑定手机号。不需要更改时不传 |
success | function | — | — | 否 | 更新成功回调函数 |
fail | function | — | — | 否 | 更新失败回调函数 |
2、获取电话条状态列表
ue.agent.findPhoneBarList(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 获取成功回调函数 |
fail | function | — | — | 否 | 获取失败回调函数 |
object.success
回调函数参数Object res
属性 | 类型 | 说明 |
success | boolean | 执行是否成功 |
data | array | 电话条状态列表 |
data object
数组里的对象值Object
属性 | 类型 | 说明 |
name | string | 状态名称 |
number | string | 切换状态值 |
3、切换电话条状态
ue.agent.switchPhoneBar(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
stateNumber | string | — | — | 是 | 切换状态值 |
success | function | — | — | 否 | 获取成功回调函数 |
fail | function | — | — | 否 | 获取失败回调函数 |
object.success
回调函数参数Object res
属性 | 类型 | 说明 |
success | boolean | 执行是否成功 |
object.fail
回调函数参数Object res
属性 | 类型 | 说明 |
message | string | 错误描述 |
4、退出登录
ue.agent.logout(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
offlineAnswer | string | '0'/'1' | '0' | 否 | '0': 不离线接听 '1': 离线接听 |
success | function | — | — | 否 | 获取成功回调函数 |
fail | function | — | — | 否 | 获取失败回调函数 |
object.success
回调函数参数Object res
属性 | 类型 | 说明 |
success | boolean | 执行是否成功 |
object.fail
回调函数参数Object res
属性 | 类型 | 说明 |
message | string | 错误描述 |
5、获取服务组空闲座席(用于转接)
ue.agent.findIdleAgentsForQueue(Object object)
参数:属性 | 类型 | 可选值 | 默认值 | 必填 | 说明 |
success | function | — | — | 否 | 获取成功回调函数 |
fail | function | — | — | 否 | 获取失败回调函数 |
object.success
回调函数参数Object res
属性 | 类型 | 说明 |
success | boolean | 执行是否成功 |
object.fail
回调函数参数Object res
属性 | 类型 | 说明 |
message | string | 错误描述 |
五、webrtc模式设备操作方法
1、接听
ue.webrtc.accept()
2、注册设备
ue.webrtc.connect()
3、注销设备
ue.webrtc.disconnect()
4、检查设备是否注册
ue.webrtc.isConnected()
5、发送DTMF
ue.webrtc.sendDTMF(String)
String 的合法值值 | 说明 |
1 | 1号键 |
2 | 2号键 |
3 | 3号键 |
4 | 4号键 |
5 | 5号键 |
6 | 6号键 |
7 | 7号键 |
8 | 8号键 |
9 | 9号键 |
0 | 0号键 |
* | *号键 |
# | #号键 |
六、常见问题及处理方案
1、通话会出现无声
通话无声都是由于未处理互踢逻辑,座席多处注册导致语音流未流向正常座席导致的。可在listenCallEvent里监听互踢,如另一处登录,则销毁上一处实例,禁止多处登录。注意:使用时需把电话条升级到3.0.5以上版本
window.ueSoftphone.listenCallEvent({
event: res => {
console.log('互踢触发');
}})