顶顶通呼叫中心中间件(mod_cti基于FreeSWITCH)-http cli 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