FreeSWITCH呼叫中心中间件-http 接口

介绍

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参数,防止非法调用。

接口说明

例子 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编码格式。

url编码说明 (参考来源 https://www.jianshu.com/p/9fd9bd197fd1)

RFC1738

https://www.ietf.org/rfc/rfc1738.txt
对字符串中除了-_.三个字符之外的所有非字母数字字符都替换成百分号(%)后跟两位十六进制数。

RFC3986

RFC-3986中采用统一的编码方式,字符的编码格式为:%HH(H为十六进制字符), 并没有对空格做特殊处理。按照RFC-3986规范,空格被编码成%20,而加号”+”被编码成%2B。

HTML4.01标准

编码方式是根据ContextType的不同而区别对待的,在form的ContextType是[x-www-form-urlencoded]的时候会对form中的键/值对进行编码,空格被转义成+,其他字符按照RFC1738标准处理成%HH的形式。

php urlencode()说明:

返回字符串,此字符串中除了 -_. 之外的所有非字母数字字符都将被替换成百分号(%)后跟两位十六进制数,空格则编码为加号(+)。此编码与 WWW 表单 POST 数据的编码方式是一样的,同时与 application/x-www-form-urlencoded 的媒体类型编码方式一样。由于历史原因,此编码在将空格编码为加号(+)方面与 ? RFC3986 编码(参见 rawurlencode())不同。

常用例子

点击拨号

  • 例子1

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

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

http://127.0.0.1:88/cli?key=abc&cmd=originate&arg=user/1000 &echo
URL编码后
http://127.0.0.1:88/cli?key=abc&cmd=originate&arg=user%2f1000+%26echo

  • 例子2

先呼叫分机user/1000,分机应答后,再呼叫手机 1380000000,
呼叫分机使用主叫clicktocall,呼叫手机使用主叫1000,并且手机接听时开始录音

key = abc
cmd = cti_originate
arg = {origination_caller_id_number=clicktocall}user/1000 &bridge({origination_caller_id_number=1000,record_filename=$${recordings_dir}/${strftime(%Y-%m-%d)}/${uuid}.wav,execute_on_answer='record_session $${recordings_dir}/${strftime(%Y-%m-%d)}/${uuid}.wav'}sofia/external/1380000000@网关IP)

http://127.0.0.1:88/cli?key=abc&cmd=cti_originate&arg={origination_caller_id_number=clicktocall}user/1000 &bridge({origination_caller_id_number=1000,execute_on_answer=’record_session $${recordings_dir}/20200303/${uuid}.wav’}sofia/external/9999@180.76.224.191:35580)
URL编码后
http://127.0.0.1:88/cli?key=abc&cmd=originate&arg=%7bignore_early_media%3dtrue%2corigination_caller_id_number%3dclicktocall%7duser%2f1000+%26bridge(%7borigination_caller_id_number%3d1000%2cexecute_on_answer%3d%27record_session+%24%24%7brecordings_dir%7d%2f20200303%2f%24%7buuid%7d.wav%27%7dsofia%2fexternal%2f9999%40180.76.224.191%3a35580)

arg的格式是 {呼叫分机的变量}user/1000空格&bridge({呼叫手机的变量}sofia/external/手机@网关IP)

注意:

cti_originate 是 cti模块在originate函数扩展的,用来支持变量中执行函数。

cti_originate是同步函数,需要等线路返回183,或者接通才返回,如果需要里面返回需要用bgapi执行,cmd=bgapi, arg=cti_originate 呼叫参数。

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

参数说明

  • 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 一起使用。

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

  • 播放本地声音文件

http://127.0.0.1:88/cli?cmd=originate&arg={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=originate {ignore_early_media=true,origination_caller_id_number=1390000000}sofia/external/abc@27.156.125.43:6066 ‘playback:file_string://http://106.14.165.135/uploads/audio/20200526/getaudio493c5/202005261100135ecc863db4775.wav‘ inline

  • 播放多个文件

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