目的
本手册提供了呼叫中心相关的 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查找该组织默认线路。 |
2.8.4 示例
curl -XPOST -d "filetype=text&file=utf8格式的文字&numbers=13900000001,13900000002&batch_accept=12345"
http://127.0.0.1:8080/api/ola/agents/1001/ play_audio
curl -XPOST -d " file=/soft/bea/xx.mp3&numbers=13900000001,13900000002&batch_accept=12345"
http://127.0.0.1:8080/api/ola/agents/1001/ play_audio
返回值
成功：
{"code":200,"result":"success"}
