目的
本手册提供了AI的 API 说明。
背景
该项目以软交换平台 FreeSWITCH 为核心，对外提供AI开发接口。开发者可以灵活方便的与其行业应用业务系统进行集成。
名词术语
• HTTP Hyper Text Transfer Protocol
• FreeSWITCH 软交换平台
• 坐席(agent) 每个话务员（SIP 客户端）即为一个坐席
• 队列(queue) 为了能跟踪坐席状态，每个坐席必须加入一个队列。队列和坐席的关系为一对多的关系。
概述
• 系统接口分为两种：1.采用HTTP对外提供；2.通过HTTP获取外部接口返回值。
对外提供接口
1. 发起呼叫
1.1 URL
/api/ola/agents//group_AiCall
1.2 调用说明
调用方式：PUT
HTML头部信息Content-Type：application/x-www-form-urlencoded
1.3 参数说明
| 参数名称 | 是否必须 | 类型 | 长度 | 描述 |
| extn | 是 | Integer | 4 | 分机号 |
| numbers | 是 | String | 200 | 被叫号码串，以半角的逗号分隔【,】 |
| batch_accept | 是 | String | 20 | 外呼计划Id，用于通话记录查询 |
| planId | 是 | String | 20 | 外呼计划Id |
| companyId | 是 | String | 20 | 公司Id |
| interrupt | 是 | String | 4 | 是否打断。true/false |
| gateWay | 否 | String | 20 | 外呼线路。若不填，则自动根据extn查找该组织默认线路。 |
1.4 示例
curl -XPUT -d "numbers=13900000001,13900000002&batch_accept=1&planId=1&companyId=1002&interrupt=false&gateWay=02865711111 "http://127.0.0.1:8080/api/ola/agents/1001/group_AiCall
返回值
成功：
{"code":200,"result":"success"}
2. AI监控
2.1 URL
/api/ola/ai_agents
2.2 调用说明
调用方式：GET
HTML头部信息Content-Type：application/x-www-form-urlencoded
2.3 参数说明
2.4 示例
curl -XGET http://127.0.0.1:8080/api/ola/ai_agents
返回值
成功：
{"ai_agents":[{"uuid": "b3f08dd6-e978-11e8-a8f6-2b6714e8667f","number":"18937524800","batchaccept": "2117","gateway": "037523124122","planid":"2117","companyid": "1358","sessionid": "2018-11-16 16:22:18.690252","create_at":"2018-11-16 16:22:05.917573"},{"uuid":"2a75488a-e978-11e8-b40c-ad115a03c78f","number":"15388126014","batchaccept":"94","gateway":"99906","planid":"94","companyid":"1015","sessionid":"undefined","create_at":"2018-11-16 16:18:15.266940"},{"uuid":"36587f82-e978-11e8-b4c4-ad115a03c78f","number":"13980599317","batchaccept":"148","gateway":"99911","planid":"148","companyid":"1018","sessionid":"undefined","create_at":"2018-11-16 16:18:35.231210"},{"uuid":"366883b4-e978-11e8-b4cc-ad115a03c78f","number":"13890297027","batchaccept":"59","gateway":"99927","planid":"59","companyid":"1022","sessionid":"undefined","create_at":"2018-11-16 16:18:35.326316"}]}
调用外部接口
1. AI交互
1.1 调用说明
调用方式：GET
HTML头部信息Content-Type：application/x-www-form-urlencoded
出参格式：json
1.2 入参
| 参数名称 | 是否必须 | 类型 | 长度 | 描述 |
| sessId | 否 | String | 20 | 话术节点Id。(上一次交互出参返回值，初次为空) |
| queryMsg | 是 | String | 100 | 客户语音转成的文字。(初次为:first。异常返回值有：timeout超时/exception异常/SILENT_SPEECH无声音) |
| gateWay | 是 | String | 20 | 外呼线路 |
| planId | 是 | String | 20 | 外呼计划Id |
| uuid | 是 | String | 50 | 通话流水（通话记录表主键） |
| splitRecord | 否 | String | 100 | 分段录音 |
1.3 出参
| 参数名称 | 是否必须 | 类型 | 长度 | 描述 |
| retCode | 是 | String | 1 | 返回代码（0成功/1失败） |
| retMsg | 是 | String | 500 | 返回信息（success/errormsg），汉字则需UTF-8格式 |
| bye | 是 | String | 1 | 是否挂机：Y挂机；N不挂机 |
| interrupt | 是 | String | 1 | 是否打断：N不打断；Y打断（此参数为Y时，接口1.1的参数interrupt必须为true） |
| planId | 是 | String | 20 | 外呼计划Id |
| gateWay | 是 | String | 20 | 外呼线路 |
| sessionId | 是 | String | 20 | 当前话术节点Id |
| type | 是 | String | 3 | 播放类型：mp3/txt |
| say | 是 | String | 500 | 播放内容：type是mp3，则为待播放录音绝对路径；type是txt，则为待播放文字（UTF-8格式） |
| trans | 否 | String | 2 | 转呼类型：空不转呼；qt转队列；ot转外线 |
| transGW | 否 | String | 20 | 转接线路：trans为ot时必填；其余时为空 |
| numbers | 否 | String | 100 | 转接号码：trans为qt时，传队列号；trans为ot时，可传多个号码。格式：b+号码+e。多个号码以竖线分割。 例如： b13900001e|b13900000002e |
1.4 示例
curl -XGET http://127.0.0.1:9280/AiService/tianrApi?sessId=&queryMsg=first&gateWay=02865711111&planId=1&uuid=456&splitRecord=
返回值:
{"retCode":"1","retMsg":"%E6%9C%AA%E6%89%BE%E5%88%B0%E7%9B%B8%E5%85%B3%E5%A4%96%E5%91%BC%E8%AE%A1%E5%88%92%EF%BC%8C%E6%8B%9C%E6%8B%9C","sessionId":"","type":"txt","planId":"1","say":"%E6%9C%AA%E6%89%BE%E5%88%B0%E7%9B%B8%E5%85%B3%E5%A4%96%E5%91%BC%E8%AE%A1%E5%88%92%EF%BC%8C88","gateWay":"02865711111","bye":"Y","trans":"","numbers":"","transGW":""}
2. 通话记录推送
2.1 调用说明
调用方式：GET
HTML头部信息Content-Type：application/x-www-form-urlencoded
2.2 入参
| 参数名称 | 是否必须 | 类型 | 长度 | 描述 |
| call_accept | 是 | String | 100 | 话务流水，主键。 2.1.2中的uuid |
| caller_id_name | 是 | String | 100 | 主叫名称 |
| caller_id_number | 是 | String | 100 | 主叫号码 |
| destination_number | 是 | String | 100 | 被叫号码 |
| created_time | 是 | String | 20 | 呼叫时间: yyyy-mm-dd hh24:mi:ss |
| answered_time | 否 | String | 20 | 接听时间: yyyy-mm-dd hh24:mi:ss |
| over_time | 是 | String | 20 | 挂机时间: yyyy-mm-dd hh24:mi:ss |
| status | 否 | String | 20 | 线路状态 |
| gate_way | 否 | String | 20 | 通话线路 |
| recording_file_name | 否 | String | 20 | 录音文件地址（绝对路径） |
| batch_accept | 否 | String | 100 | 扩展字段。1.1.3中的batch_accept参数 |
| recording_deal_flag | 否 | String | 10 | 录音处理标识 |
| hangup_side | 否 | String | 20 | 挂机方向 |
| trans_number | 否 | String | 100 | 转接号码 |
2.3 出参
| 参数名称 | 是否必须 | 类型 | 长度 | 描述 |
| retCode | 是 | String | 1 | 返回代码（0成功/1失败） |
| retMsg | 是 | String | 500 | 返回信息（success/errormsg），汉字则需UTF-8格式 |
2.4 示例
curl –XGET http://127.0.0.1:9280/AiService/callLog?call_accept=81905050-f900-11e8-8bbf-997ca41f188c&caller_id_name=1001&caller_id_number=1001&destination_number=13900000001&created_time=2018-11-06 10:42:00&answered_time=2018-11-06 10:42:20&over_time=2018-11-06 10:42:42&status=ai&gate_way=02865711111&recording_file_name=/soft/bea/tomcat4.0/webapps/tianr4/soft/recording/20181106/ai_agent-13383754306-81905050-f900-11e8-8bbf-997ca41f188c.mp3&batch_accept=2952&recording_deal_flag=&hangup_side=recv_bye&trans_number=
返回值:
{"retCode":"0","retMsg":"success"}
