全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 智能硬件
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 更多

软电话SDK前端接入

更新时间:2018-06-15 18:22:16

软电话SDK前端接入

通过该文档,您可以实现将坐席工作台嵌入到第三方系统中,直接在您系统中实现单点登录、接打电话等功能,并且您可以通过监听SDK中的方法来实现来电弹屏,下面的工作需要您公司的前端工程师来实施。workbench(0.2.6)

1.引入sdk静态资源

  1. <!--sdk样式文件-->
  2. <link rel="stylesheet" type="text/css" href="https://g.alicdn.com/acca/workbench-sdk/{version-sdk}/main.min.css">
  3. <!--sdk js文件-->
  4. <script type="text/javascript" src="//g.alicdn.com/crm/acc-phone/{version-sip}/SIPml-api.js"></script>
  5. <script type="text/javascript" src="//g.alicdn.com/crm/acc-phone/{version-sip}/index.js"></script>
  6. <script type="text/javascript" src="https://g.alicdn.com/acca/workbench-sdk/{version-sdk}/workbenchSdk.min.js"></script>
  7. <!--开发模式时workbench-sdk推荐引入workbenchSdk.js,会有一些打印提示.-->
  8. 以上静态资源,将上面的{version-sdk}和{version-sip}替换为对应的版本号,当前最新版本号为:
  9. version-sip ==> 1.1.0
  10. version-sdk ==> 0.2.6

您可随时关注该文档页面,SDK有更新时会第一时间更新文档页面。

2.初始化sdk

  1. window.workbench = new WorkbenchSdk(config)

3.config必选配置

  1. - dom //挂载元素id
  2. - instanceId //实例Id 使用主账号登录https://ccc.console.aliyun.com/AccInstance,点击每条实例后面的实例id复制过来即可。

4.config可选配置

  1. - header //是否展示头部(小休,下线,手机接听),默认展示,参数类型:Boolean;
  2. - width //宽度,默认280,参数类型:Number;
  3. - height //高度,默认552,参数类型:Number;(为了保证完整的UI展示,建议高度最低552);
  4. - defaultVisible // 默认是否展示面板,默认为true,参数类型:Boolean;
  5. - offlineImage // 下线展示的静态图片地址,参数类型:String;
  6. - breakImage // 小休展示的静态图片地址,参数类型:String;
  7. - afterCallRule // 挂机后进入空闲状态的时间,单位秒,默认15秒,参数类型:Number;如果不想自动切换进入空闲状态,而是等待客服手动去从话后处理切换到空闲状态,那么这个值必须为’manual‘;
  8. - autoAnswerCall //有来电时自动接听电话的时长,单位秒,默认为手动接听,参数类型:Number;
  9. - ajaxType // 请求路径形式,值为“param”或“path”,默认为“param”。
  10. - 为“param”请求路径为 ajaxOrigin/ajaxPath?ajaxApiParamName=apiName
  11. - 为“path”请求路径为 ajaxOrigin/ajaxPath/module/action
  12. - ajaxOrigin //请求源,默认请求当前源(location.origin),跨域需手动配置
  13. - ajaxPath // 请求路径,默认为“/data/api.json”
  14. - withCredentials // 表示跨域请求时是否需要使用凭证,是否允许携带cookie
  15. - ajaxApiParamName // ajaxType为param时指定区分action的名称,默认action
  16. - ajaxMethod // post|get 默认post
  17. - ajaxOtherParams //其他自定义参数和request同一层级
  18. - ajaxHeaders //请求的header,参数类型:Object;
  19. - moreActionList // 在头部的功能模块的按钮列表,值可为['mobilePhoneAnswer', 'break', 'offline'],分别对应[手机接听,小休,下线],用户可根据需求选择配置项,参数类型:Array;
  20. - useLocalStorageToCall // 是否允许使用多标签页外呼,默认为false,参数类型:Boolean;详细介绍请参考第9条说明。
  21. 钩子:某些事件触发时的回调函数
  22. - onInit //SDK对象实例化完成
  23. - onRegister //sip服务注册成功,参数表(config<呼叫中心配置项>)
  24. - onCallComing //来电,参数表(connid<通话id>, caller<主叫号码>, calee<被叫号码>,contactId<录音id>,skillgroupId<技能组id>)
  25. - onCallDialing //去电,参数表(connid, caller, calee, contactId)
  26. - onCallEstablish //通话建立连接时触发,参数表(connid<通话id>, caller<主叫号码>, calee<被叫号码>,contactId<录音id>)
  27. - onCallRelease //通话结束时触发,参数表(connid<通话id>, caller<主叫号码>, calee<被叫号码>,contactId<录音id>)
  28. - onErrorNotify //错误,参数表(error) error = { errorApi
  29. xx<错误API>,errorCode:xx<错误code>, errorMsg:xx<英文错误信息>, errorMsgTip:xx<中文错误信息>,requestId:xx<请求ID>
  30. }
  31. - onLogOut //签出
  32. - onLogIn //签入
  33. - onBreak //小休
  34. - onReady //空闲
  35. - onHangUp //挂机,参数表(type),type值为ringing<呼入未接时挂机>,dialing<呼出未接时挂机>,inbound<呼入通话,通话中挂断>,outbound<呼出通话,通话中挂断>
  36. - onStatusChange //状态code(含义参考7)改变通知,参数表(code, lastCode, context<包含通话id:connid>)

5.sdk方法

  1. - changeVisible(true/false) //显示或隐藏面板
  2. - register() //首次签入,包含了sip服务注册+签入+置空闲,页面加载完毕,首次签入需调用该方法,调用完成后坐席进入空闲状态(需要在onInit钩子方法执行之后才可以调用)
  3. - logIn() //签入(处于签出状态可调用)
  4. - logOut() //签出
  5. - ready() //置空闲
  6. - applyForBreak(breakId, breakName) //申请小休,小休id和小休名称来区分小休类型
  7. - hangUp() //挂断
  8. - answer() //接听电话
  9. - getStatus() //获取当前状态描述,具体参考7
  10. - getStatusCode() //返回对象, 有两个属性: code是当前状态 lastCode是上一次的状态,具体参考7
  11. - call(callee, caller) //拨号,caller为主叫号码,可以指定主叫号码,也可以不传,或者传‘auto’,不传时使用面板里选择的主叫号码或技能组所绑定外呼号码的第一个,为‘auto’时,根据被叫号码归属地自动选择主叫号码;callee为被叫号码不可空,必传
  12. - sendDtmf(number) //二次拨号,发送dtmf; number可为0~9,*或#
  13. - callHold() //通话保持
  14. - callRetrieve() //通话取回
  15. - offline(mobileNumber, caller) //离线坐席,mobileNumber为离线坐席的手机号码,caller为外呼号码
  16. - online() //回到坐席接听方法
  17. - transferStatisfic() // 发送满意度,调用后将自动挂机,让客户进行满意度评分
  18. - downloadRecord(contactId,onlyPlay) // 播放和下载录音,contactId为话务ID(录音ID)(参数类型:String),onlyPlay是否仅播放(参数类型:Boolean),详情可查看本文档第10条

例如在第二步中初始化SDK时保存到了window下的变量workbench,比如外呼时,调用方法时写法为:workbench.call(‘17688888888’,’01066668888’)

6.服务端准备工作

  • 转发sdk发的请求到阿里云云呼叫中心服务端,参数加上token,结果直接返回
  • 坐席,技能组等需要再阿里云云呼叫中心后台系统进行配置,否则无法使用

7.状态对照表

状态码(getStatusCode) 注释 描述(getStatus)
-1 未注册 off
0 注册中 off
1 签出 off
2 签入 logIn
3 空闲 ready
4 小休 break
5 话后处理 other
6 振铃 callComing
8 拨号 dialingCall
9 呼入通话 inCall
10 呼出通话 inCall
11 内部通话 inCall
12 通话保持 inCall
16 发起三方 other
17 咨询通话 other
18 咨询通话,再切换通话 other
19 会议 other
20 被动求助 other
21 监听 monitoring

8.各个状态下的sdk方法约束说明

状态 具体描述
未注册 状态值为-1,这时用户只能执行首次签入(即首次上线)操作。
签出 状态值为1,这时用户只能执行签入(即上线)操作。
签入 状态值为2,当用户签入后状态值变为2,签入成功后状态值又马上变为3(即空闲),状态值由2到3这个过程很快(几乎是同时进行);也就是说用户在2的状态时来不及做任何操作就进入到空闲状态(状态值3)。
空闲 状态值为3,空闲状态下用户可进行拨号小休退出组(即下线)等操作,注:只有该状态下可收到外部打过来的电话(即振铃)。
小休 状态值为4,该状态下可执行结束小休退出组拨号(即下线)操作。
话后处理 状态值为5,该状态下可执行退出组(即下线)、小休继续工作(即开始接听)、拨号再次拨打等操作。
振铃 状态值为6,该状态下只可执行接听操作。
拨号 状态值为8,该状态下只可执行挂机操作。
呼入通话 状态值为9,该状态下可执行挂机(需要设置)、保持(即通话保持)操作。
呼出通话 状态值为10,该状态下可执行挂机保持(即通话保持)、二次拨号操作。
话路保持 状态值为12,即通话保持,该状态下只可执行通话取回(通话取回)操作。
注:其他功能SDK暂未提供。

9. 多标签页外呼使用要点

使用场景

  1. 做了CRM系统集成的用户,可以使用我们的sdk界面进行外呼,但是也存在一些用户需要在其他页面,比如一些用户名单列表或用户详情页面通过点击按钮进行外呼,这时就需要在该页面进行sdk注册,但是我们的sdk是不支持多标签注册的,因此我们提供了这样的方案:在注册过sdk的标签页监听其他标签页localstorage的变化,在其他标签页设置localstorage来实现外呼。

使用方法

  1. 设置配置项useLocalStorageToCall为true
  2. 首先所有标签页都要在一个浏览器中,要求只有一个标签页注册WorkbenchSdk,并保持该标签页的登录状态。
  3. 在其他标签页拨打电话时设置一个localstorage,key为workbenchSdkCall,value为{callee:”15588888888”,caller:’057128236231’,random:’0.234234234’}。其中caller的值具体设置参照上面sdk方法中call(callee, caller)的规定,设置成功以后,当注册过WorkbenchSdk的标签页监听到localstorge的workbenchSdkCall变化时,便自动外呼电话:

    1. var value = {'callee':'15588888888','caller':'057128236231', 'random': Math.random()}
    2. localStorage.setItem('workbenchSdkCall', JSON.stringify(value))
  4. 在其他标签页挂断电话时,需设置一个key为workbenchSdkHangup,value为一个随机数的localstorage,便自动挂断电话

    1. localStorage.setItem('workbenchSdkHangup', Math.random())
  5. 可通过localStorage.getItem(‘workbenchSdkStatus’)来查询当前workbench状态码,当值为3,4,5时才可以外拨号码;当值为8,9,10,11,12时才可挂断电话。

10.录音播放和下载使用说明

`/**

  • downloadRecord(contactId, onlyPlay)
  • contactId[String] 话务id
  • onlyPlay[Boolean] 是否仅可以播放,默认为true,只可以播放,不可以下载
  • */`
  • 提供了简单的录音播放和下载的方式,内部实现方式为根据contanceId调用ListRecordingsByContactId获取到录音详细信息,再根据录音详细信息中的fileName去调用DownloadRecording来获取录音播放的地址。所以如果您没有使用我们提供的java版crm-demo,需要您自行配置上面的两个API。
  • contactId获取方式:
    • 根据ListCallDetailRecords获取;
    • 在呼入呼出时,根据onCallComing和onCallDialing两个钩子方法的参数中获取,自行存储起来。
  • 调用后,会出现如下图界面,自动播放第一条录音,

11.开发错误与操作逻辑错误

​ SDK会抛出两种类型的错误:开发错误和操作逻辑错误

  • 开发错误:简单的说就是可以通过修改您的代码来修复的错误,是稳定重现的,这一类型的错误常见的有配置参数类型出错调用sdk方法未按照状态约束表进行。比如配置项onInit要求是一个方法,但是却传入了一个字符串,那么sdk会直接执行如下代码,遇到这样的错误js执行被打断,必须要根据错误提示先进行修复

    1. throw new Error("onInit must be a function");
  • 操作逻辑错误:这一类错误是用户使用呼叫中心过程中一些操作不当造成的错误,不一定是稳定重现的,这一类型的错误常见的有未允许浏览器对本域名开启声卡权限操作不完整:点击拨打按钮时没有选择外呼号码或者没有输入正确的对方的电话号码账号在别处登录客服不在任何技能组中无法使用呼叫中心网络错误等。这类错误sdk会调用onErrorNotify方法通知外部系统,参数结构是:

    1. {
    2. errorCode: 'systemErrorNotInAnySkillGroup',
    3. errorMsg: '您不在任何技能组中,请联系管理员进行添加'
    4. }

    ​ 您应该通过某种方式把errorMsg告知给用户,方便用户解决问题后重新进行操作。我们推荐您在开发时配置onErrorNotify钩子并打印参数,方便排查问题。

12.常见问题解答

Q. SDK中有来电弹屏功能吗?A. 通过监听SDK中的onCallComing事件,每当有来电时,会携带来电号码,您根据该事件在您系统中做对应的来电弹屏即可。

Q. 可以不用SDK的页面吗?A. 可以的,可以完全只调用SDK中的方法,实现坐席工作台的功能。

Q. 可以多个标签页初始化SDK,达到每个标签页都可以外呼的场景吗?A. 不可以,目前一个浏览器中只能有一个标签页初始化SDK,多个标签页初始化,会将已上线的标签页踢出。但是可以保留一个标签页SDK只初始化注册一次,在配置项中添加useLocalStorageToCall为true,详情请参照第9条多标签页外呼使用要点

Q. 怎样可以实现初始化SDK后客服无感知的自动上线?A. 可以在onInit中去执行register方法即可。

changelog

  • 0.0.7(December 18, 2017)

    • 修复全局样式对外部系统的影响;
    • 添加二次拨号sendDtmf(number)、通话保持callHold()、通话取回callRetrieve()的方法;
    • 修改再次拨打的样式bug。
  • 0.0.8(December 21, 2017)

    • 新增onStatusChange(code, lastCode, context)的方法
    • 所有方法的调用增加了状态约束,当不能在该状态调用某个方法时会抛出错误信息
    • 修改通话中拨号键盘,和通话后再次拨打的弹出拨号层的交互方式
    • 修复全局reset样式对外部系统的影响
    • 修复号码删除Icon不显示的问题
    • 修复defaultVisible设置为false没有隐藏默认面板的问题
  • 0.0.9(December 28, 2017)

    • 新增afterCallRule配置项,可配置通话结束后自动进入ready状态的时间,默认为15(单位秒),afterCallRule接受量类型参数,一类为时间,一类为’manual’意思为手动控制,传manual时系统不会倒计时进入ready而是直接进入话后处理及时状态
    • 小休方法applyForBreak增加类型区分,具体参数参考上文
    • 修复reset样式不起作用导致的浏览器默认样式影响全局样式的bug
  • 0.1.0(January 12, 2018)

    • 在onCallComing和onCallDialing钩子函数中输出录音id(contactId)
    • 修改logOut约束码
  • 0.1.1(January 18, 2018)

    • 处理0.1.0版本不能”下线”和”小休”的bug;
    • 新增autoAnswerCall配置项,设置自动接听通话,单位秒,默认为手动接听。
  • 0.1.2(January 25, 2018)

    • 设置loash全局变量隐藏。
  • 0.1.3(January 30, 2018)

    • 处理自动回到空闲的问题
    • 处理麦克风错误页面不能点击按钮的问题
  • 0.1.4(January 31, 2018)

    • 新增isAgentReady配置项,设置状态值为“8-5”时是否置空闲
    • 新增processorJSON配置项,设置json字符串是否再次解析
    • 解决OnAndOff组件下includes报错
  • 0.1.5(February 8, 2018)

    • 新增ajaxHeaders配置项,对象格式
    • 添加离线坐席功能,即离线后设置手机接听;使用方法offline(),返回坐席接听方法online()
    • 新增”来电桌面提醒”功能,可以解决坐席没有佩戴耳机无法听到来电振铃声音,并且呼叫中心页面最小化造成的漏接来电。在您初次登录坐席工作台时,需要您授权同意浏览器显示桌面提醒,强烈建议您开启此功能!如您误操作点击了拒绝,可查看文档 如何开启来电桌面提醒
  • 0.1.8(March 5, 2018)

    • 将SDK注册sip服务的时间由加载时自动注册,改为点击上线按钮时进行注册,上线按钮做了以下几件事情:注册-签入-空闲;这样做是为了解决有些客服人员工作时需要通过多个标签页打开自有的CRM系统,但是每个标签页又都加载了SDK,造成了多个标签页都去注册sip服务引起的坐席状态异常。(请注意页面顶部的SDK静态资源均有更新)
  • 0.1.9(March 14, 2018)

    • onInit的作用变更为:SDK对象初始化完成。
    • 新增首次签入register方法,为上一个迭代(0.1.8)的深层次优化,通过此方法可实现首次登录sip服务注册以及自动签入的功能,不过该方法必须在onInit执行了之后才可以调用!
    • 新增onRegister钩子,首次签入register完成后调用,携带的参数为呼叫中心配置项config。
    • 修复调用call方法时,面板没有自动切换到拨打界面的问题。
  • 0.2.1(March 28, 2018)

    • 新增通话记录功能,坐席可查看自己近30天内前100条通话记录。
    • 新增配置项height,用来配置面板高度,高度越高,通话记录显示的条数越多,根据您的实际使用情况来填写即可。
    • 新增自动选择外呼号码功能,系统会在当前坐席可用的外呼号码列表中,自动匹配和外呼号码相同归属地的主叫号码进行外呼,当可用的外呼号码列表中没有相同归属地的号码时,降级匹配同省的主叫号码,如果依旧匹配不到,将随机选择;这样可以很大的提高外呼接通率;
    • 新增号码归属地显示功能,呼入呼出时,都会显示主被叫号码的归属地信息;数据来源于阿里通信,数据库数据相对来说比较新,但无法保证100%显示归属地信息。
  • 0.2.2(April 12,2018)

    • 新增转接功能,坐席在通话过程中,需要转接其他人来帮忙接待时,可以转接到其他坐席人员,也可转接到外部电话。转接分为咨询转接和直接转接,咨询转接是指正在通话坐席先与目标坐席通话,咨询是否可以转接到目标坐席,通话坐席可根据通话结果选择“取消转接”或“转移通话”;直接转接是指直接转接给目标坐席。
    • 改版坐席工作台UI界面,将横版的tab,改为左侧导航。
    • 将发送满意度的方法暴露出来,transferStatisfic(callee, connid),外界可直接调用,其中callee参数通过GetServiceExtensions访问。
    • 因本次增加了许多功能,所以非java后端的用户,需自行配置以下四个接口:
  • 0.2.3(May 3,2018)
    • 优化向外暴露的sdk方法中的call方法,call(callee, caller),caller为主叫号码,可以指定主叫号码,也可以不传,或者传‘auto’,不传时使用面板里选择的主叫号码或技能组所绑定外呼号码的第一个,为‘auto’时,根据外呼的号码的归属地选择与与其同一归属地的主叫号码,若没有同一归属地的就随机在技能组里选择一个主叫号码。;callee为被叫号码不可空,必传
    • 减少接口调用频率,优化转接功能
    • 实现多标签页外呼。
    • 添加满意度统计功能
    • 添加外呼号码和来电号码是否部分隐藏功能(隐藏号码中的四位数字)
    • 因本次增加了功能点,非java用户需自行配置以下接口
  • 0.2.4(May 24, 2018)

    • 拨打电话时,技能组没有绑定号码给提示信息并抛错。
    • 麦克风异常界面点击后给2s的提示,并且在上线后、通话前监测麦克风失败,自动下线。
    • 修改发送满意度方法
    • 优化onErrorNotify
  • 0.2.6(June 14, 2018)

    • 添加withCredentials配置,用以跨域请求时是否需要使用凭证
    • 通话记录添加搜索条件
    • 添加网络检测功能
    • 优化关闭浏览器二次提示的条件
    • 添加ivr认证功能
    • 上线前合并请求,解决操作过快接口无法返回情况
    • 增加便捷的录音播放和下载方法,详情查看此文档第10条
本文导读目录