顶顶通呼叫中心中间件(mod_cti基于FreeSWITCH)-http cli 接口

介绍

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