顶顶通呼叫中心中间件(mod_cti基于FreeSWITCH)-http cli FreeSWITCH命令接口 | 顶顶通 - 呼叫中心二次开发接口,smartivr,mod_vad,FreeSWITCH,语音识别,呼叫中心中间件,电话机器人,空号检测,智能外呼。

介绍

http cli的原理是cti模块实现了一个http server 接收http get请求，执行FreeSWITCH命令后把执行结果返回给http client，常用的使用场景包含http接口实现挂断指定的通话，http接口实现点击拨号（先呼叫坐席电话，座席接听后再呼叫客户电话），以及监听，强插，转接电话等功能。

本接口使用FreeSWITCH原生参数格式，建议使用httpapi接口 http://www.ddrj.com/callcenter/httpapi.html#%E6%89%A7%E8%A1%8CFreeSWITCH-%E5%91%BD%E4%BB%A4 ，httpapi接口发起呼叫参数更简单明了，并且有呼叫进度通知回掉。

配置

cti.conf.xml http_cli节点就是配置http server监听的IP和端口，以及接口的KEY。

 <http_cli>
     <param name="http_server_domain" value="mydomain.com"/>
     <param name="http_server_ip" value="0.0.0.0"/>
     <param name="http_server_port" value="88"/>
     <param name="http_api_cli_key" value="abc"/>     
     <param name="http_api_cli_acl" value="127.0.0.1/32"/>      
</http_cli>

http_server_domain 配置一个域名或者本机外网IP，只有回拨转直拨业务才需要配置。。
http_server_ip 监听的IP，如果只限本机调用，可以配置 127.0.0.1。
http_server_port 监听的端口。
http_api_cli_key http接口调用是key参数，相当于密码，防止非法调用,必须包含数字字母特殊符号。
http_api_cli_acl 那些IP可以调用这个接口，防止非法调用。

如果 cti.json 配置了api.key，会覆盖http_api_cli_key 配置，如果 cti.json 配置了api.acl，会覆盖http_api_cli_acl 配置。cti.json[api]配置是可以动态生效的。建议使用这个配置代替。

接口说明

例子 http://ip:88/cli?cmd=log&arg=测试&key=abc

key 必须和cti.conf.xml http_cli节点http_api_cli_key配置的value内容一致。
cmd FreeSWITCH的命令。
arg FreeSWITCH命令的参数。

每个字段都要求url编码，支持各种URL编码格式。

originate 发起呼叫的命令

cti_originate是cti模块提供和originate功能一样的命令，主要是修复了originate命令设置变量不支持类似这样的格式： ${函数(参数)} ，例子：name=${strftime(%Y-%m-%d)} 。

同步和异步

cmd=bgapi，后台执行的意思，就是异步执行，不管后续的命令是否执行成功都立马返回，arg为命令参数（arg的命令和参数中间用空格隔开）。如果需要命令执行成功了才返回，cmd就设置为具体的命令比如cti_originate，arg为命令的具体参数。

originate是收到早期媒体就返回的，不是接通后才返回的。如果需要接通后才返回，就需要添加变量ignore_early_media=true或者ignore_early_media=consume后面的参数说明有更详细的描述。

JONS 格式的参数和返回数据

如果需要json格式的请求参数和返回数据应该这样

cmd=json

arg= {"command":"fsapi|execute|channelData|mediaStats|status","data":json命令参数,"format":"pretty"}

command
- fsapi 执行FreeSWITCH API
  - data {"cmd":"命令","arg":"参数"}
    - cmd FreeSWITCH的命令
    - FreeSWITCH命令的参数
- execute 执行FreeSWITCH APP
  - data 请求参数
    - uuid 通道UUID
    - app APP名字
    - arg APP参数
    - inline yes 同步, no异步
    - extendedData yes 返回包含 channelData，no只返回channelName。
- channelData 获取通道数据
  - data 请求参数
    - uuid 通道UUID
- mediaStats 获取媒体状态
  - data 请求参数
    - uuid 通道UUID
    - channelData 布尔类型的tue返回通道变量
- status 获取系统状态
响应JONS格式
- status success或者error
- message 执行结果的文本内容。
- response 执行的错误信息
- 不同命令有不同的更多输出
format 如果设置为pretty，返回的JSON文本进行了格式化。

例子:查询媒体状态

http://127.0.0.1:88/cli?key=abc&cmd=json&arg={"command":"mediaStats","data":{"uuid":"18d02496-dbe1-46f5-bf6b-675a6eb07ceb"}}

常用例子

点击拨号

例子1

最基本的例子呼叫分机1000，分机1000接听后，听到自己声音

key = abc
cmd = bgapi
arg = originate user/1000 &echo

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=originate user/1000 &echo
URL编码后（对arg=后面参数进行url编码）
http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=originate+user%2f1000+%26echo

例子2

先呼叫分机user/121，分机应答后，再使用线路组default呼叫手机 5555
呼叫分机使用主叫clicktocall,呼叫手机使用主叫121，并且手机接听后开始录音

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate {origination_caller_id_number=clicktocall,origination_nested_vars=true,execute_on_answer_set_record_filename='export record_filename=$${recordings_dir}/${strftime(%Y-%m-%d)}/${uuid}.wav'}user/121 &bridge({origination_caller_id_number=121,execute_on_answer_start_record='record_session \${record_filename}'}linegroup/default/5555)

URL编码后

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate%20%7Borigination_caller_id_number%3Dclicktocall%2Corigination_nested_vars%3Dtrue%2Cexecute_on_answer_set_record_filename%3D%27export%20record_filename%3D%24%24%7Brecordings_dir%7D%2F%24%7Bstrftime(%25Y-%25m-%25d)%7D%2F%24%7Buuid%7D.wav%27%7Duser%2F121%20%26bridge(%7Borigination_caller_id_number%3D121%2Cexecute_on_answer_start_record%3D%27record_session%20%5C%24%7Brecord_filename%7D%27%7Dlinegroup%2Fdefault%2F5555)

如果需要分机应答就开始录音

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate {origination_caller_id_number=clicktocall}user/121 export:record_filename=$${recordings_dir}/${strftime(%Y-%m-%d)}/${uuid}.wav,record_session:${record_filename},bridge:{origination_caller_id_number=121}linegroup/default/1380000000 inline

URL编码后

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate%20%7Borigination_caller_id_number%3Dclicktocall%7Duser%2F121%20export%3Arecord_filename%3D%24%24%7Brecordings_dir%7D%2F%24%7Bstrftime(%25Y-%25m-%25d)%7D%2F%24%7Buuid%7D.wav%2Crecord_session%3A%24%7Brecord_filename%7D%2Cbridge%3A%7Borigination_caller_id_number%3D121%7Dlinegroup%2Fdefault%2F1380000000%20inline

例子3
先呼叫分机，分机接通后呼叫手机，设置自定义的彩铃

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate+{origination_nested_vars=true,instant_ringback=true,transfer_ringback=声音文件路径,origination_caller_id_number=9999}user/1000 &bridge({origination_caller_id_number=1000,execute_on_answer='record_session /fs/recording/20220624144610983/100000102896000118380317308.wav',ignore_early_media=true}linegroup/default/138000000)

外呼拨号串参数描述

arg的格式是 cti_originate空格{呼叫分机的变量}拨号串空格&bridge({呼叫手机的变量}拨号串)

例子： cti_originate {var=val}usr/分机号 &bridge({var=val}sofia/external/手机号@落地IP)

注意：
如果先呼叫分机后呼叫手机，变量要分开设置，不要把呼叫手机用的变量设置到呼叫分机去了。

拨号串格式
- 呼叫分机:user/分机号
- 通过线路组呼叫:linegroup/线路组/号码
- 通过网关呼叫:sofia/gateway/网关名/号码
- 通过IP直接呼叫:sofia/external/号码@落地IP
参数说明
- origination_caller_id_number 设置主叫号码
- origination_uuid 如果需要使用自定义的呼叫UUID，通过这个参数传给FS。
- record_filename 写入CDR表的录音路径
- execute_on_answer=’record_session $${recordings_dir}/20210303/${uuid}.wav’ 接通后开始录音，$${recordings_dir}/日期目录/${uuid}.wav 这个是录音文件路径
  - $${recordings_dir} vars.xml 配置的录音文件路径默认是 fs安装目录 recording
  - ${caller_id_number} 来电号码
  - ${uuid} 通话callid
  - ${strftime(%Y-%m-%d)} 日期
- ignore_early_media=true 忽略早期媒体，如果坐席使用手机接听，需要这个参数，也就是先呼叫的号码，如果是手机，需要加上这个参数，如果需要录制早期媒体，需要改成 ignore_early_media=consume。
- absolute_codec_string=g729 指定g729编码，如果需要同时指定多个编码可以设置为 ^^:G729:PCMA:PCMU ^^:意思是把逗号用:代替，类似转义符。
- originate_timeout 呼叫超时（比如分机30秒不接听就停止呼叫），需要和ignore_early_media=true 一起使用。
- instant_ringback=true 安装自定义彩铃
- transfer_ringback=$${cn-ring} 设置自定义彩铃声音，可以指定具体的文件名，$${cn-ring}使用嘟嘟声音，如果不和ignore_early_media=true一起使用，线路响应了183，就会播放线路的提示音。
- origination_nested_vars=true 允许origiante参数不解析变量，变量格式\${变量名}。
- export_vars 把变量传递到后续桥接的通道，比如export_vars=‘record_filename,其他变量名’ ，如果只需要设置变量到后续桥接的通道，用前缀nolocal:例子：{nolocal:sip_h_X-AutoAccept=true,export_vars=’nolocal:sip_h_X-AutoAccept’}
- sip_h_* 添加自定义sip头到 INVITE ；如果值里面又逗号用\转义，例子 sip_h_X-My-Header=one\,two\,three。
- sip_rh_* 添加自定义sip头到 200
- sip_ph_* 添加自定义sip头到 180 183
- sip_bye_h_* 添加自定义sip头到 bye

呼叫一个号码接通后进入电话机器人

呼叫分机接通后进入电话机器人

http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000,话术变量=话术变量的值}user/1000 'set:park_timeout=3600,cti_robot:话术,park' inline

呼叫手机接通后进入电话机器人

http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000,话术变量=话术变量的值}linegroup/线路组/号码 'set:park_timeout=3600,cti_robot:话术,park' inline

呼叫分机接通后录音然后进去电话机器人http话术接口

http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000,话术变量=话术变量的值}user/1000 'set:record_filename=$${recordings_dir}/${strftime(%Y-%m-%d)}/${uuid}.wav,record_session:${record_filename},set:park_timeout=3600,cti_robot:http://ip/flow,park' inline

呼叫一个手机号码，电话接通后播放一个录音

播放本地声音文件

http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000}sofia/external/1380000000@vosIP &playback(声音文件路径)

播放网络文件

http://127.0.0.1:88/cli?key=123456&cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000}sofia/external/abc@27.156.125.43:6066 'playback:file_string://http://ip/uploads/audio/20200526/getaudio493c5/202005261100135ecc863db4775.wav' inline

播放多个文件

http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000}sofia/external/1380000000@vosIP &playback(file_string://文件1.wav!文件2.wav)

播放tts声音

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000}user/123 'playback:file_string://http://127.0.0.1:9989/tts?text=这个测试是放音文字转语音测试' inline

对通话中双方播放声音

http://ip:88/cli?key=key&cmd=uuid_broadcast&arg=uuid 放音文件放音方式

UUID: 通话的UUID
声音文件：可以是FS服务器的本地文件，也可以是http连接的wav文件（8K16bit单声道）。
放音方式： [aleg|bleg|holdb|both] aleg 对A端放音，bleg对B段放音， holdb b端口播放hold， both双端放音，不设置A端放音B端播放hold
例子

http://down.ddrj.com:88/cli?key=abc&cmd=uuid_broadcast&arg=b2961087-c353-45f6-a50e-1fd957e23fec http://127.0.0.1:9989/tts?text=这个测试是放音文字转语音测试 both

通话中双方播放声音，同时不影响算双方通话（需要背景音模块授权）

http://ip:88/cli?key=key&cmd=uuid_cti_background&arg=uuid 放音文件放音方式

UUID: 通话的UUID
声音文件：可以是FS服务器的本地文件，也可以是http连接的wav文件（8K16bit单声道）。
放音方式： mfr(声音文件混音到接收流)或者mfw（声音文件混音到发送流）

监听、强拆等坐席工具条操作

请看分机文档页面 http://www.ddrj.com/callcenter/exten.html#%E7%9B%91%E5%90%AC%E5%88%86%E6%9C%BA%E9%80%9A%E8%AF%9D

拨打一个电话接通后检测到提示音发送DTMF按键，然后开始录音

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate {origination_caller_id_number=8888,ignore_early_media=consume,park_timeout=3600}user/121 'export:record_filename=$${recordings_dir}/${strftime(%Y-%m-%d)}/${uuid}.wav,record_session:${record_filename},cti_dial_exten:1234 inband 10000,park' inline

park_timeout 设置最大通话时间，单位毫秒。

cti_dial_exten 发送按键，具体请看 http://www.ddrj.com/callcenter/dialplan.html#%E8%87%AA%E5%8A%A8%E5%A4%96%E5%91%BC%E8%BE%93%E5%85%A5%E5%88%86%E6%9C%BA%E5%8F%B7%EF%BC%88%E6%AF%94%E5%A6%82%E9%9A%90%E7%A7%81%E5%8F%B7%EF%BC%89

拨打一个电话接通后等1秒发送DTMF按键

方法1

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate {origination_caller_id_number=8888,ignore_early_media=consume,park_timeout=3600}user/121 senddtmf:1234 park' inline

方法2

http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=cti_originate {origination_caller_id_number=8888,ignore_early_media=consume,park_timeout=3600，execute_on_answer_senddtmf='senddtmf W1234'}user/121 &park

senddtmf 用法 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod-dptools/6587078/
小写w 延时0.5秒
大写W 延时1秒，如果延时2秒可以WW1234

查询会议信息

返回json格式：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 json_list")
返回xml格式 http://ip:88/cli?key=key&cmd=conference&arg=urlencode("会议名 xml_list")

对会议中成员操作（静音，取消静音，踢出等）

静音：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 mute 成员ID")
取消静音：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 unmute 成员ID")
踢出不播放kick sound：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 hup 成员ID")
踢出播放kick sound：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 kick 成员ID")
对会议成员放音：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 play 声音文件成员ID")
对会议混音放音（所有成员都可以听到）：http://ip:88/cli?key=key&cmd=conference&arg=urlenode("会议名 play 声音文件 async")
对会议所有成员都执行操作成员ID可以用”all”，更多操作请看 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod_conference_3965534/#api-reference