座席端SDK

适用版本agent-sdk_1.1.52

使用SDK之前，请确保你有一个可使用的SIP话机或使用WebRTC插件, 用于完成通话

DEMO获取

获取demo, 点击下载

安装

<script src="/agent-sdk/agent-sdk_1.1.52.js"></script>

or

npm install agent-sdk

快速使用

import AgentSdk from 'agent-sdk';

const op = {
    el: '#ElementId',
    url: 'WS地址',
    agentNumber: '座席工号',
    password: '座席密码',
    companyShortName: '企业简称'
}
const agentSdk = new AgentSdk(op);

agentSdk.call('21000');
agentSdk.on('MakeCall', (res) => {
    // 外呼发起
});
agentSdk.on('After', (res) => {
    // 通话结束
});

初始化配置 SDKOptions

在new AgentSdk(options)中，options配置项如下:

• url: string 必传

  远程websocket服务地址

• companyShortName: string 必传

  使用该应用的企业简称，可以在OBC查看。

• agentNumber: string 必传

  登录的目标坐席工号。

• agentPassword: string 必传

  登录的目标坐席密码。

• connectAccount: string 必传

  远程队列服务账号。

• connectPassword: string 必传

  远程队列服务密码。

• subscribePath: string 必传

  远程队列服务订阅地址。

• host: string 必传

  远程队列服务连接Virtual Host地址。

• el: string default: ''

  接收一个元素选择器，用于指定SDK的UI控件的显示位置, 不传则不展示UI控件。

<div id="sdk-box"></div>

const sdk = new AgentSdk({
    el: '#sdk-box',
    ...
});

如果配置正确, 会有如图控件出现在页面上的指定元素内。

• pingInterval: number default: 10000

  ws链接心跳间隔, 必须大于0。

• timeout: number default: 5000

  请求超时时间。

• maxReconnect: number default: 10

  最大重连次数, 当链接失败或链接关闭时, 会自动发起重新链接, 连续重连次数达到该值的时候会停止重连, 连接成功之后会重新计算, 配置时请注意不要超过浏览器的最大链接数量, 以下是各个浏览器的最大链接数量, 以供参考: Chrome: 256个 FireFox: 200个 safari: 1273个

• unDownloadLog: boolean default: false

  是否关闭下载日志

• softPhoneFactory: Function

  只有当loginType为3的时候才生效

  指定WebRTC话机构造函数, 未指定则在全局对象window上查找 SoftPhoneSdk, 当座席成功登录之后, 话机会自动注册, 并用采用默认配置进行通话

import AgentSdk from 'agent-sdk';
import SoftPhoneSdk from 'soft-phone-sdk';

const agentSdk = new AgentSdk({
    loginType: 3,
    softPhoneFactory: SoftPhoneSdk,
    ...
});

const loginAndReconnect = () => {
    // 获取软话机实例, 用于对话机操作
    const softPhoneInstance = agentSdk.getSoftPhoneInstance();

    softPhoneInstance.on('Registered', () => {
        console.log('话机注册完成');
    })
}

agentSdk.on('Login', () => loginAndReconnect());
agentSdk.on('Reconnect', () => loginAndReconnect());

• autoAnswer: boolean default: true

  是否开启自动应答, 默认开启, 仅WebRTC话机生效, 当座席发起外呼时强制使用

配合WebRTC话机

当前版本SDK内置了WebRTC话机, 在https环境中使用loginType: 3, 自动就会使用WebRTC话机

API

在const sdk = new AgentSdk(options)中，可以通过sdk直接调用的方法。

• getVersion(): string

  获取当前SDK版本号。

• getLoginType(): LoginType

  获取当前登录类型

• init(sdkOption ?: SDKOptions)

  接收一个SDK配置对象，将当前实例再次初始化，new AgentSdk(options)会自动调用，当你需要重新初始化SDK的时候可以使用, 失败会抛异常。

• connect()

  发起ws连接请求，返回一个连接实例，new AgentSdk(options)会自动调用，当你需要手动建立新连接的时候可以使用。

• login(loginConfig ?: LoginOptions)

  使用初始化时候的配置进行登录, 或指定配置进行登陆。
  LoginOptions成员如下:

• logout()

  退出当前座席。

• break()

  退出并断开连接，通话期间不允许断开。

• call(called: string, calledType: number = 2, caller ?: string)

  指定被叫，发起呼叫, calledType是呼叫类型 1为坐席号，2为手机。caller是透传指定主叫号码

• hangup()

  挂断当前通话，拨通与呼叫中都可以使用。

• busy(busyType ?: string)

  将当前座席的状态设置为忙碌Busy, 可以指定忙碌类型, 登录时会返回可选的忙碌类型。

• idle()

  将当前座席的状态设置为空闲Idle。

• mute()

  开启静音, 通话中可使用。

• unMute()

  解除静音, 开启静音后可使用。

• transferCall (target: string, transferType: number)

  转接当前正在进行的通话，target表示要转接的目标，transferType表示转接目标的号码类型，1座席工号, 2手机号, 3技能组ID, 4 IVR模版ID。

• consult(consultTarget: string)

  发起咨询，consultTarget表示要咨询的目标。

• consultTransfer()

  咨询转接。

• tripartiteCall()

  会议或三方通话。

• on(eventName: string, callback: Function): string

  对sdk的事件进行监听，当事件触发时调用callback, 返回一个监听的uuid用于取消监听, 支持的事件名称在EventMap部分找到。

const uuid = sdk.on('Open', data => {
    // 链接建立成功
})

• once(eventName: string, callback: Function): string

  对sdk的事件进行监听，当事件触发时调用callback, 返回一个监听的uuid用于取消监听, 支持的事件名称在EventMap部分找到, 与on不同的是, once绑定的事件在触发之后会自动解绑, 一次绑定只会触发一次。

const uuid = sdk.once('Open', data => {
    // 链接建立成功
})

• off(eventName: string, uuidOrFn: string | Function): boolean

  取消一个SDK的事件监听, 需要指定eventName, 可以使用指定函数引用或监听的uuid。

sdk.off('Open', uuid);
// or
sdk.off('Open', functionPointer);

• setUserdata(userdata: string)

  指定用户透传数据, 后续所有事件的回传数据都会携带。

• isConnected(): boolean

  是否已链接

• isLogin(): boolean

  是否已登录

• getSoftPhoneInstance(): object

  当前使用的软话机实例, 用于对话机操作

班长座席 API

以下AIP的使用，需要当前登录座席是班长。

• surveillance()

  发起一次监控请求。

• surveillanceStart(filter ?: SurveillanceFilter, interval: number = 2000)

  开启监控, 自动发起监控请求 interval 是请求间隔, 默认两秒, filter 是监控信息的过滤, 当传递filter时, 必须包含groupId

• surveillanceEnd()

  关闭监控

• forceIdle(target: string)

  强制空闲，target表示目标座席工号。

• forceBusy(target: string)

  强制忙碌，target表示目标座席工号。

• forceLogout(target: string)

  强制退出，target表示目标座席工号。

• listen(target: string)

  监听通话，target表示目标座席工号，目标必须处于通话中。

• forceBreak(target: string)

  强制挂断通话，target表示目标座席工号，目标必须处于通话中。

• forceInsert(target: string)

  强制插入通话，target表示目标座席工号，目标必须处于通话中。

• intercept(target: string)

  拦截通话，target表示目标座席工号，目标必须处于通话中。

• getStateByAgentId(agentNumber: string)

  获取指定座席工号的状态。

• getIdleAgentByGroupId(groupId: string)

  获取技能组下的空闲坐席, 通过监听IdleAgent事件拿到数据。

• getGroups()

  获取所有技能组, 通过监听GroupInfo事件拿到数据。

• getAutoGroups()

  获取可预测外呼的技能组。

WebRTC话机相关API

当使用内置WebRTC话机时, 可以使用一下方法快速操作话机, 更多操作话机的方法请使用getSoftPhoneInstance

• isRegistered()

  获取话机是否注册

• register()

  发起话机注册

• unregister()

  取消话机注册

• stop()

  取消话机注册, 并断开链接

事件 EventMap

可以通过sdk.on方法绑定或解绑并取得响应数据的事件名称集合。

sdk.on('Login', res => { ... })

所有事件都会包含以下公共信息:

可监听的事件名称如下:

• Open

  成功建立链接
  回传数据类型: Frame 链接相关信息

• Error

  建立链接失败
  回传数据类型: Event 错误信息

• Close

  链接关闭
  回传数据类型: Frame 链接相关信息

• StateChange

  状态发生改变触发
  回传数据类型: string 状态值

• Login

  登陆成功
  回传数据类型: Object

• Logout

  退出成功
  回传数据类型: null

• Reconnect

  重链成功, 只有首次登录和退出后的登录会触发Login, 在缓存token信息失效之前, 都会触发Reconnect, 用于恢复座席状态

  回传数据类型: Object

• Idle

  制闲操作成功
  回传数据类型: null

• Busy

  制忙操作成功
  回传数据类型: null

• MakeCall

  发起通话成功
  回传数据类型: null

• MakeCallFail

  发起通话失败
  回传数据类型: Object

• AgentRinging

  座席振铃
  回传数据类型: Object

• AgentAnswer

  座席应答
  回传数据类型: Object

• CalledRinging

  被叫振铃
  回传数据类型: Object

• CalledAnswer

  被叫应答
  回传数据类型: Object

• Conversation

  通话中
  回传数据类型: Object

• TransferCall

  发起转接, 只有在通话中才能发起
  回传数据类型: null

• TransferCalling

  转接中
  回传数据类型: null

• TransferCallFail

  转接失败
  回传数据类型: null

• Listen

  发起监听
  回传数据类型: null

• Listening

  监听中
  回传数据类型: null

• ListenFail

  监听失败
  回传数据类型: null

• ForceBreak

  强制断开通话
  回传数据类型: null

• ForceInsert

  强制插入通话
  回传数据类型: null

• ForceInserting

  强制插入通话中
  回传数据类型: null

• ForceInsertFail

  强制插入通话失败
  回传数据类型: null

• Intercept

  拦截通话
  回传数据类型: null

• Intercepting

  拦截通话中
  回传数据类型: null

• InterceptFail

  拦截失败
  回传数据类型: null

• After

  话后
  回传数据类型: Object

• Kick

  被踢出
  回传数据类型: undefined

• SipError

  话机异常, 当话机取消注册时触发, 同时座席会退出
  回传数据类型: null

• QueueInfo

  队列等待消息
  回传数据类型: Object

• GroupInfo

  技能组信息
  回传数据类型: Object

• IdleAgent

  技能组信息
  回传数据类型: Object

• Surveillance

  座席监控信息
  回传数据类型: Object

• Exception

  UI操作异常事件
  回传数据类型: Exception

• 异常处理

  异常通常产生自非法的数据, 配置, 参数和方法调用的时机与顺序, 目前可能需要捕获的异常有三个场景, 捕获这些异常可以提供给使用者更多提示信息。

  1. 通过sdk句柄调用方法;
  2. sdk自带UI使用过程中;
  3. 发送命令之后, 来自远端回执的异常;

• 调用SDK方法中的异常捕获

  const agentSdk = new AgentSdk({...});
  /**
  * 因为call方法需要传入一个被叫, 这里没有传入, 所以会抛出一个异常
  */
  agentSdk.call();
  /**
  * 捕获异常
  */
  try {
    agentSdk.call();
  } catch (e) {
    console.log(e.message); // 被叫不能为空
  }

• SDK提供UI使用过程中的异常捕获

• 来自远端回执的异常捕获

  使用sdk自带UI过程中和来自远端回执的异常捕获方式相同, 由于方法不被开发人员调用, 所以不能直接使用try catch, 监听Exception事件捕获异常。

  // <div id="sdk-box"></div>
  const agentSdk = new AgentSdk({ el: '#sdk-box', ... });
  /**
  * 操作控件, 不填写被叫号码的情况, 直接点击呼叫按钮
  *
  * 捕获异常
  */
  agentSdk.on('Exception', e => {
      console.log(e.message); // 被叫不能为空
  })

• 话后状态cause说明

进入话后状态时, 会携带cause和data, 说明进入话后的原因, 以下是对照表: