成都添闰OLA-API文档

添添呼 | 管理一步到位

免费试用

成都添闰OLA-API文档

本手册提供了呼叫中心相关的 API 说明。该项目以软交换平台 FreeSWITCH 为核心，对外提供呼叫中心开发接口。开发者可以灵活方便的与其行业应用业务系统进行集成。

目的

本手册提供了呼叫中心相关的 API 说明。

背景

该项目以软交换平台 FreeSWITCH 为核心，对外提供呼叫中心开发接口。开发者可以灵活方便的与其行业应用业务系统进行集成。

名词术语

• HTTP Hyper Text Transfer Protocol

• JS JavaScripts

• FreeSWITCH 软交换平台

• 坐席(agent) 每个话务员（SIP 客户端）即为一个坐席

• 队列(queue) 为了能跟踪坐席状态，每个坐席必须加入一个队列。队列和坐席的关系为一对多的关系。

• WebSocket协议它实现了浏览器与服务器全双工(full-duplex)通信——允许服务器主动发送信息给客户端。

概述

• 系统集成接口主要采用JavaScripts对外提供，部分接口采用HTTP对外提供。

• 坐席(agent)状态主要有：未签入、已签入、示闲中、示忙中。

• 部分方法依赖于坐席状态，只有特定状态才能操作。

• 只有示闲中，才能呼入呼出。

1. JS接口

1.1引入ola_api.js文件

具体文件请联系添闰通讯获取。

1.2创建Websocket连接

1.2.1方法定义

方法名称	说明	依赖
websocket_connect()	与话务服务器创建连接。	无
onMessage()	回调函数，用于接受服务器端推送信息。（状态变更，来电弹屏等都在该函数中处理）。	无
onConnect()	创建连接后订阅服务器端信息。	无
onClose()	连接关闭后执行操作。	无

1.2.2 方法示例

function websocket_connect()

{

var websocket_url = "ws://"+serIp+":"+serPort+"/ola_socket";

ola.connect(websocket_url);

ola.onConnect = onConnect;

ola.onClose = onClose;

ola.onMessage = onMessage;

}

//注：serIp为服务器ip；serPort为服务器应用端口

function onConnect()

{

console.log("websocket connected!");

ola._extn = ola_extn;

ola.subscribe('ola.queue.' + ola_queue + '.' + ola_extn);

ola.subscribe('ola.caller.' + ola_extn);

ola.get_agent_state(ola_extn);

}

//注：ola_extn为坐席分机号；ola_queue为坐席队列号

function onClose() {

//自定义内容，可为空

}

//注：ola_extn为坐席分机号；ola_queue为坐席队列号

function onMessage(evt)

{

var data = JSON.parse(evt.data);

console.log(data);

if (data.event_type == "agent_state")//分机状态

{

if (data.state == "busy")

{

if (data.private_data == "ring") //话机振铃

{

//data.other_dn; 呼入的号码

//data.call_accept 话务流水（是通话记录表里的主键） //此处可open页面作为来电弹屏

} else if (data.private_data == "answered")//话机已接听

{

//此处可open页面作为接听弹屏

}

else if (data.old_state == "busy") //已挂机

{

//可扩展自动示闲

}

1.3签入

1.3.1方法定义

方法名称	说明	依赖
login()	签入	分机未签入

1.3.2 方法示例

function login()

{

ola.login(ola_queue, ola_extn, {type: "onhook"});

}

//注：ola_queue为坐席签入队列;ola_extn为坐席分机号

1.4签出

1.4.1方法定义

方法名称	说明	依赖
logout()	签出	分机已签入

1.4.2 方法示例

function logout()

{

ola.logout();

}

1.5示闲

1.5.1方法定义

方法名称	说明	依赖
go_ready()	示闲	分机已签入；分机非空闲

1.5.2 方法示例

function go_ready()

{

ola.go_ready();

}

1.6示忙

1.6.1方法定义

方法名称	说明	依赖
go_break()	示忙	分机空闲

1.6.2 方法示例

function go_break()

{

ola.go_break();

}

1.7拨号

1.7.1方法定义

方法名称	说明	依赖
dial()	拨号	分机空闲

1.7.2 方法示例

function dial(phone)

{

ola.dial(phone);

}

//注：phone为电话号码

1.8转呼

1.8.1方法定义

方法名称	说明	依赖
transfer()	转呼	通话中

1.8.2 方法示例

function transfer(phone)

{

ola.transfer(phone);

}

//注：phone可为电话号码或者分机号

1.9三方通话

1.9.1方法定义

方法名称	说明	依赖
three_way(ola_extn,phone)	三方通话	通话中

1.9.2 方法示例

function three_way(phone)

{

ola.three_way(ola_extn,phone);

}

//注：ola_extn为本机分机号；phone为第三方分机号

1.10通话保持

1.10.1方法定义

方法名称	说明	依赖
hold()	通话保持	通话中

1.10.2 方法示例

function hold()

{

ola.hold();

}

1.11解除保持

1.11.1方法定义

方法名称	说明	依赖
unhold()	解除保持	通话中，已保持

1.11.2 方法示例

function unhold()

{

ola.unhold();

}

1.12监听

1.12.1方法定义

方法名称	说明	依赖
monitor(ola_extn,dest)	监听	示闲中；被监听分机在通话中

1.12.2 方法示例

function monitor(ola_extn,dest)

{

ola.monitor(ola_extn + "", dest + "");

}

//注：ola_extn为本机分机号；dest为被监听方的分机号

1.13解除监听

1.13.1方法定义

方法名称	说明	依赖
unmonitor(ola_extn)	取消监听	监听中

1.13.2 方法示例

function unmonitor(ola_extn)

{

ola.unmonitor(ola_extn);

}

//注：ola_extn为本机分机号

1.14挂机

1.14.1方法定义

方法名称	说明	依赖
hangup()	挂机	通话中

1.14.2 方法示例

function hangup()

{

ola.hangup();

}

2. HTTP接口

2.1队列创建

2.1.1 URL

/api/ola/queues/

2.1.2 调用说明

调用方式：POST

HTML头部信息Content-Type：application/x-www-form-urlencoded

2.1.3 参数说明

参数名称	是否必须	类型	长度	描述
queueId	是	Integer	6	队列编号，唯一
strategy	是	String	11	策略，写死为fifo_onhook
moh	是	String	100	用户呼入队列时的等待音乐。该音乐文件在服务器上必须存在。例如： /temp/wait.mp3
other_attrs	是	String	500	其它配置信息，以key-value结构存放，下面单独一个表格进行说明

other_attrs参数说明：

参数名称	是否必须	类型	长度	描述
chim_freq	是	Integer	3	队列等待超时时间。单位：秒
agent_timeout	是	Integer	3	分机等待超时时间。单位：秒
hidden_caller_number	是	String	5	是否隐藏号码。true隐藏；false不隐藏
judge_after_hangup	否	Integer	1	呼入挂机评价。1需要/0不需要
judge_after_hangup_ob	否	Integer	1	呼出挂机评价。1需要/0不需要

2.1.4 示例

curl -XPOST -d "strategy=fifo_onhook&&moh=/temp/wait.mp3&other_attrs{'chim_freq':'30','agent_timeout':'30',hidden_caller_number:'false'}" http://127.0.0.1:8080/api/ola/queues/100001

返回值

成功：

{"queue":{"name":"100001","id":"","strategy":"fifo_onhook","callback":"","moh":"/temp/wait.mp3","state":"stopped","created_at":[50,48,49,56,45,48,51,45,48,53,32,49,55,58,51,50,58,52,54,46,54,56,53,52,49,52],"other_attrs":"undefined","comment":""}}

2.2队列启动和停止

2.2.1 URL

/api/ola/queues//

2.2.2调用说明

调用方式：PUT

HTML头部信息Content-Type：application/x-www-form-urlencoded

2.2.3参数说明

参数名称	是否必须	类型	长度	描述
queueId	是	Integer	6	队列编号
action	是	String	11	动作。启动或停止，start/stop

2.2.4 示例

curl -XPUT http://127.0.0.1:8080/api/ola/queues/100001/start

curl -XPUT http://127.0.0.1:8080/api/ola/queues/100001/stop

返回值

成功：

{"queue_state":"running","queue_pid":"<0.19954.16>"}

{"queue_state":"stopped"}

2.3队列删除

2.3.1 URL

/api/ola/queues/

2.3.2调用说明

调用方式：DELETE

HTML头部信息Content-Type：application/x-www-form-urlencoded

2.3.3参数说明

参数名称	是否必须	类型	长度	描述
queueId	是	Integer	6	队列编号

2.3.4 示例

curl -XDELETE http://127.0.0.1:8080/api/ola/queues/100001

返回值

成功：

{"code":200,"result":"success"}

2.4队列排队情况查询接口

2.4.1 URL

/api/ola/queues//get_callers

2.4.2调用说明

调用方式：GET

HTML头部信息Content-Type：application/x-www-form-urlencoded

2.4.3参数说明

参数名称	是否必须	类型	长度	描述
queueId	是	Integer	6	队列编号

2.4.4 示例

curl -XGET http://127.0.0.1:8080/api/ola/queues/100001/get_callers

返回值

成功：

{"count":"0","callers":[]}

2.5队列空闲坐席查询接口

2.5.1 URL

/api/ola/agents?queue_name=&state=ready

2.5.2调用说明

调用方式：GET

HTML头部信息Content-Type：application/json

2.5.3参数说明

参数名称	是否必须	类型	长度	描述
queueId	是	Integer	6	队列编号

2.6.4 示例

curl -XGET http://127.0.0.1:8080/api/ola/agents?queue_name=100001&state=ready

返回值

成功：

{"count":"0","agents":[]}

2.6坐席信息查询接口

2.6.1 URL

/api/ola/agents/

2.6.2调用说明

调用方式：GET

HTML头部信息Content-Type：application/x-www-form-urlencoded

2.6.3参数说明

参数名称	是否必须	类型	长度	描述
extn	否	Integer	4	分机号，不传则查询所有

2.6.4 示例

curl -XGET http://127.0.0.1:8080/api/ola/agents/1001

返回值

成功：

{"agent":[{"extn":"1001","id":"1001","channel_uuid":"","name":"1001","type":"onhook","weight":"0","queue":"10020","moh":"","wrapup_time":"5000","dial_string":"user/1001","state":"unready","old_state":"","private_data":"","sip_state":"","device":"","sip_ip":"","created_at":"2018-03-05 17:26:40.892605","updated_at":"undefined","call_direction":"","other_number":"","gateway":"","answered_at":"","comment":""}]}

2.7批量外呼接口

2.7.1 URL

/api/ola/agents//group_call/

2.7.2调用说明

调用方式：PUT

HTML头部信息Content-Type：application/x-www-form-urlencoded

2.7.3参数说明

参数名称	是否必须	类型	长度	描述
extn	是	Integer	4	分机号
queueId	是	Integer	6	接听后转入的队列号
numbers	是	String	200	被叫号码串，以半角的逗号分隔【,】
batch_accept	否	String	20	批量外呼流水，可在通话记录中根据该值查询
gateway	否	String	20	外呼线路。若不填，则自动根据extn查找该组织默认线路。

2.7.4 示例

curl -XPUT -d "numbers=13900000001,13900000002&batch_accept=12345" http://127.0.0.1:8080/api/ola/agents/1001/group_call/10285

返回值

成功：

{"code":200,"result":"success"}

2.8批量外呼播放录音/文字接口

2.8.1 URL

/api/ola/agents//play_audio

2.8.2调用说明

调用方式：POST

HTML头部信息Content-Type：application/x-www-form-urlencoded

文字转语音需要用到第3方接口，目前百度免费，需要您自行去百度申请账号，并将账号告知我们。

2.8.3参数说明

参数名称	是否必须	类型	长度	描述
extn	是	Integer	4	分机号
filetype	是	String	4	1. 值为text表示播放文字； 2. 为空则播放录音文件
file	是	String	200	1. 待播放文字（utf-8格式）； 2. 录音文件绝对路径
numbers	是	String	200	被叫号码串，以半角的逗号分隔【,】
batch_accept	否	String	20	批量外呼流水，可在通话记录中根据该值查询
gateway	否	String	20	外呼线路。若不填，则自动根据extn查找该组织默认线路。