介绍
http cli的原理是cti模块实现了一个http server 接收http get请求,执行FreeSWITCH命令后把执行结果返回给http client,常用的使用场景包含http接口实现挂断指定的通话,http接口实现点击拨号(先呼叫坐席电话,座席接听后再呼叫客户电话),以及监听,强插,转接电话等功能。
配置
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"/>
</http_cli>
- http_server_domain 配置一个域名或者本机外网IP,可不配置。
- http_server_ip 监听的IP,如果只限本机调用,可以配置 127.0.0.1。
- http_server_port 监听的端口。
- http_api_cli_key http接口调用是key参数,防止非法调用。
接口说明
- key 必须和cti.conf.xml http_cli节点http_api_cli_key配置的value内容一致。
- cmd FreeSWITCH的命令。
- arg FreeSWITCH命令的参数。
每个字段都要求url编码,支持各种URL编码格式。
常用例子
点击拨号
- 例子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编码)
- 例子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 忽略早期媒体,如果坐席使用手机接听,需要这个参数
- absolute_codec_string=g729 指定g729编码
- 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'}
呼叫一个号码接通后进入电话机器人
- 呼叫分机接通后进入电话机器人
http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000,话术变量=话术变量的值}user/1000 'cti_robot:话术,set:park_timeout=3600,park' inline
- 呼叫手机接通后进入电话机器人
http://127.0.0.1:88/cli?cmd=bgapi&arg=cti_originate {ignore_early_media=true,origination_caller_id_number=1390000000,话术变量=话术变量的值}linegroup/线路组/号码 'cti_robot:话术,set:park_timeout=3600,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(声音文件混音到发送流)
查询会议信息
- 返回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