Callcenter API
JS SDK
JS SDK可以直接在浏览器中使用。JS SDK底层使用Websocket与XSwitch后台通信,使用长连接。
JS SDK可以使用以下方式鉴权:
- 用户名/密码:该方式主要用于客户端与后台通信(C-S架构),因为在流量器端保存密码通常不够安全。
- 用户Token登录:推荐的登录方式,用户Token即坐席Token,可以代表坐席登录到系统,订阅事件和发送命令。
- 分机Token登录:分机Token主要是为了区分WebRTC坐席,目前系统不支持WebRTC坐席,因此暂不需要使用分机Token登录。
具体的登录和鉴权方式可以参考XSwitch认证和鉴权接口。
SDK引入
JS SDK支持es5和es6语法和开发方式,具体可参考callcenter代码示例 。
es5方式可以直接在HTML文件中引入JS,如:
<script type="text/javascript" src="//xswitch.cn/static/js/verto-min.js"></script>
es6可以直接在package.json
中添加@xswitch/rtc
,或通过npm install @xswitch/rtc
、yarn add @xswitch/rtc
等安装SDK。
SDK使用
SDK使用Verto库连接Websocket。Verto是XSwitch中连接Websocket协议的JS库,支持连接、登录验证、API、以及WebRTC呼叫等。在呼叫中心应用中暂不考虑WebRTC部分。
在es5中,可以初始化一个实例变量,如:
var verto = new Verto();
在es6中,可以使用以下方法引入:
import verto, {Verto, VertoCallcenter} from '@xswitch/rtc'
verto
是一个单例,不需要初始化。
有了verto
以后,可以继续初始化Callcenter:
var vcc = new VertoCallcenter(verto);
vcc是在Verto连接的基础上增加了Callcenter相关的控制函数。
连接
可以使用以下代码连接:
const loginParams = {
xui_sessid: '你的用户token 或分机 token'
};
const params = {
login: '1001@xswitch.cn',
passwd: 'password',
socketUrl: socketUrl,
loginParams: loginParams
}
verto.connect(params, callbacks);
params
参数:
login
:字符串,格式是user@domain
。domain
必须是正确的域,否则可能不能通过认证或订阅不到消息。一般来说可以在XSwitch Web界面首页上查到这个“域” 。passwd
:如果使用Token登录,passwd
固定调为password
,否则填真正的密码。socketUrl
:Websocket的地址,具体有管理员配置,一般是ws://host:port/ws
。loginParams
:对象。xui_sessid
:字符串,用户或分机Token。如果使用密码登录,则不要提供该字段。
callbacks
回调对象:
onMessage
:function(verto, dialog, msg, data)
,收到消息时回调。verto
:verto
实例dialog
:只在WebRTC中使用msg
:收到的消息对象,根据不同的消息内容不同data
:收到的数据,内容因具体的消息而异
onWSLogin
:function(verto, success)
,登录时回调。verto
:verto
实例success
:true|false
,是否成功。
onWSClose
:function (v, success)
,Websocket断开时回调。参数同上。onEvent
:function(v, e)
,事件回调。
具体的消息内容(msg
、data
等)可以在使用时打印出来看看。
订阅
连接成功后,要订阅感兴超的消息(事件)。如班长需要订阅整个队列所有人的状态,坐席通常只需要订阅自己的状态。函数原型如下:
verto.subscribe(eventChannel, { handler: onAgentEvent });
eventChannel
:事件类型。eventChannel是以“.
”分割的主题名。如:vcc
:订阅所有vcc
开头的消息vcc.default
:订阅default
这个组的vcc
消息,如班长要订阅所有人的状态vcc.default.1007
:订阅1007
这个坐席的状态
handler
:回调函数,原型是:onAgentEvent(vt, event)
。vt
:verto
实例event
:事件
事件的具体格式由event.eventType
决定。典型的如下:
agentStatus
:坐席状态- 其它:略
函数简介
一般来说,事件以队列方式分组,比如vcc.队列名.座席名
,队列名也称组名。
设置
目前后面默认硬编码了group_id
为default
。如果需要其它组ID,请与我们联系。
vcc = new VertoCallcenter(verto);
vcc.setGroup('default');
签入
vcc.ccLogin(queue, agent, extn, success_cb, failed_cb);
queue
:队列名,与XSwitch后台一致agent
:坐席名,当前坐席工号extn
:分机号。目前只有在后台设置的与坐席对应的分机号才能登录,下一个版本中将放开这个限制,坐席以选择任意的分机号。success_cb
:登录成功时回调。failed_cb
:登录失败时回调。
签出
vcc.ccLogout(queue, agent, success_cb, failed_cb);
示闲
将坐席置于READY
状态,可以接听来话。
vcc.ccGoReady(queue, agent, success_cb, failed_cb);
示忙
将坐席置于UNREADY
状态,不能接听来话。
vcc.ccGoBreak(queue, agent, reason, success_cb, failed_cb);
reason
:可选,原因值,任意字符串,如吃饭
等。这个会影响统计结果,所以建议在使用前规划好。常用的有:DND
:Do Not Disturb,免打扰BRB
:Be Right Back,一会就回
外呼
vcc.ccDial(agent, extn, cidNumber, destNumber, earlyMedia, success_cb, failed_cb);
callerID
:主叫号码destNumber
:被叫号码earlyMedia
:早期媒体,默认为false
外呼将使用回呼方式。系统先呼叫坐席对应的分机,分机接听后再去呼叫destNumber
。
其他
其它函数参数示例。
断开连接
可以用如下代码断开WebSocket连接:
verto.logout();
多连接
Verto是一个类,verto
是一个Verto的实例。为方便使用,ES6中有一个verto
单例,因而可以直接使用。
如果需要创建多个Websocket连接,比如同时连接多个Websocket服务器,或者在同一个Websocket服务器上创建多个连接,可以直接初始化多个实例。
var verto1 = new Verto();
var verto2 = new Verto();
...
verto1.connect(...);
verto2.connect(...);