介绍

为了实现动态组合拨号方案避免重复配置，把拨号方案拆分成了2个部分，一个是cti_dialplan_extensio@domain,保存单个拨号方案配置，一个是cti_dialplan_context@domain把多个拨号方案组合一个路由表。拨号方案和路由配置修改后会自动生效。生效时间是cti.json 的gui->dialplan_cacheable”配置的，默认配置是1分钟之内自动生效，如果测试过程要实时生效可以改成0，就是每次拨号方案都会从redis中获取。

用法

条件

把变量和正则表达式匹配，如果匹配，就执行对应的动作。详细参考 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Dialplan/XML-Dialplan/

动作

也叫APP，就是一个功能函数，常见的APP参考 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod_dptools_1970333

通道变量

拨号方案的原理就是对通道变量执行正则表达式匹配，如果匹配上了，就执行对应的动作(APP)。fs的很多特性是通过设置通道变量来实现的。这里介绍一下常用的通道变量，更详细的说明参考 https://freeswitch.org/confluence/display/FREESWITCH/Channel+Variables 和 https://freeswitch.org/confluence/display/FREESWITCH/Variables+Master+List

设置通道变量的方法

action=“set” data=“变量=值” ，详细参考 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod-dptools/6586661

action=“export” data=“变量=值” 详细参考 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod-dptools/6586592/

set和export的区别是set设置的变量只作用于本通道,export设置的变量会带入到后续桥接的通道。

如果只需要给后续桥接的通道设置变量，不需要作用于本通道export设置的变量名前面加一个nolocal:前缀或者_nolocal_前缀。

action=“bridge_export” data=“变量=值” 详细参考https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod-dptools/6586489/

bridge_export和export的区别，export只能导出到拨号方案中bridge的通道（export其实就是switch_ivr_originate中处理的），bridge_export可以导出到任何能通话的通道，包含ESL调用的uuid_bridge（bridge_export其实就是switch_ivr_multi_threaded_bridge中处理的）。

呼入常用的通道变量

• caller_id_number 来电号码
• network_addr 来电IP
• destination_number DID

呼出常用的通道变量

• origination_nested_vars=true 允许origiante参数不解析变量，变量格式\${变量名}。
• absolute_codec_string 设置声音编码
• call_timeout 设置呼叫超时 ，只作用于后续桥接的通道
• effective_caller_id_number 设置主叫号码，只作用于后续桥接的通道
• originate_timeout 设置呼叫超时 ，只作用于本端，一般添加在拨号串里，或者export设置
• origination_caller_id_number 设置主叫号码，只作用于本端，一般添加在拨号串里，或者export设置
• leg_timeout 为每条腿设置超时时间。可以用于单条腿上[]
• origination_aleg_uuid a路UUID
• originate_continue_on_timeout The originate_continue_on_timeout is set to true for this: if the bridge’s dial string specifies several destinations separated by the «|» (this is for failover), the bridge will time out on an unanswered destination and will attempt the next specified destination. Without originate_continue_on_timeout set to true, the bridge will time out on the first destination it tries and the bridge itself will fail.

转接常用的通道变量

• ignore_early_media 【被叫设置】忽略早期媒体,可选的值 true:忽略 consume:忽略但是可以获取数据,ring_ready:183改成180

• bridge_early_media 【被叫设置】 主叫可以听到早期媒体，透传还是转码，暂时未测试

• ringback 【主叫设置】设置呼叫彩铃 ，中国标准的回铃:$${cn-ring} 实际值:%(1000,4000,450)

• transfer_ringback 【主叫设置】设置转接彩铃，主叫接通之后值bridge，就算转接,未设置transfer_ringback，会使用ringback。

• call_timeout 【主叫设置】设置呼叫超时

• originate_timeout 【被叫设置】设置呼叫超时，会覆盖call_timeout

• instant_ringback=true 【主叫和被叫设置都可以】发送假回铃(被叫没发送180，主叫就先发送嘟嘟的声音)

• continue_on_fail=true 【主叫设置】转接失败不要挂断主叫

  添加自定义SIP头

  • sip_h_自定义头=值 添加自定义sip头到 INVITE
  • sip_rh_自定义头=值 添加自定义sip头到 200
  • sip_bye_h_自定义头=值 添加自定义sip头到 bye
  • sip_ph_自定义头=值 添加自定义sip头到 180 183

其他常用变量

• bridge_answer_timeout bridge时等待应答的超时时间,变量 continue_on_answer_timeout 可以控制超时时挂机，还是继续执行拨号方案。
• sofia_session_timeout 覆盖sip profile配置session_timeout
• continue_on_fail 呼叫失败后是否继续执行后面的拨号方案
• hangup_after_bridge bleg挂断后是否挂断aleg。
• transfer_after_bridge bleg挂断后，aleg transfer目的的。
• park_after_bridge bleg挂断后，aleg是否park,esl开发接口非常有用。
• exec_after_bridge_app bleg挂断后后,aleg执行一个APP。
• api_after_bridge bleg挂断后后，aleg执行一个API。

fs的通道变量非常多，怎么查看通话的通道变量呢，有2个方法 方法1 执行fs控制台命令 uuid_dump 通话UUID，方法2 拨号方案里面执行fs的动作info 也可以输出通道变量，info输出的通道变量有些名字和uuid_dump的不一样，文末复制了一个fs官方文档里面的对应关系。

通过通道变量绑定动作

• execute_on_answer 应答时

• execute_on_pre_answer 收到183时

• execute_on_pre_bridge 桥接前

• execute_on_post_bridge 桥接后

• execute_on_media 建立媒体时

• execute_on_ring 收到180时

• execute_on_tone_detect 检测到信号音时

• execute_on_originate 发送呼叫请求后

• execute_on_post_originate 呼叫前

• execute_on_pre_originate 呼叫完成（183或者200后）

  例子 应答的时候播放一个信号音

  execute_on_answer_play="playback tone_stream://%(10000,0,350,440)"

通过通道变量绑定API命令

• api_on_answer 应答时
• api_on_pre_answer 收到183时
• api_after_bridge 桥接前
• api_before_bridge 桥接后
• api_on_media 建立媒体时
• api_on_ring 收到180时
• api_on_tone_detect 检测到信号音时
• api_on_originate 发送呼叫请求后
• api_on_post_originate 呼叫前
• api_on_pre_originate 呼叫完成（183或者200后）
• api_hangup_hook 挂机时
• api_reporting_hook 生成报表时

例子 应答的时候播放一个信号音

api_on_answer_play="uuid_broadcast ${uuid} tone_stream://%(10000,0,350,440) [aleg|bleg|both]"

拨号方案中生成随机数

<!-- generate random number between 1 and 100 -->
<action application="set" data="rand_val=${expr(randomize(&x);ceil(random(0,100,&x)))}"/>

详细参考 mod_expr说明文档 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod_expr_6587353

把外呼的通道变量同步到坐席端

比如是自动外呼转人工，在进入排队的拨号方案 cti_acd 前面加入一个action是 exprot， data是变量名=${变量名}，这样就可以把外呼端设置的变量名传给分机了,如果需要单独设置被叫变量 action是 exprot， data是变量名=nolocal:${变量名}。

分机外呼拨号方案设置的数据未进入CDR

如果编码不匹配等呼入直接拒接的，可能还没进入动作就失败了，可以在拨号方案动作是set,和export 行勾选inline ，这样就避免这个问题。

拨号方案中调用http接口

通过API cti_http_get url [connect_timeout] [response_timeout] [varname] 可以在拨号方案任意位置调用http接口,可以把通道变量作为 http接口的参数，传递给接口。

• connect_timeout 连接超时
• response_timeout 等待返回超时
• varname 返回的数据写入这个变量，如果不设置，就会写入默认变量cti_http_get_last_result
• 例子
  • 例子1 eval ${cti_http_get(http://ip?arg=${通道变量})}
    执行http请求，返回的结果会写入默认变量cti_http_get_last_result
  • 例子2 set myval=${cti_http_get(http://ip?arg=${通道变量})}
    把cti_http_get返回的结果写入myval变量
• 接口返回数据说明
  • 返回文本数据
    返回文本数据不会进行解析和也不会去除空格换行，会把原始数据设置到变量里面。
  • 返回JSON数据
    {"header":{"value1":"1","value2":"2"},"body":""}
    head可用来设置自定义的变量，body会写入cti_http_get_last_result，或者自定义的变量名里面。

拨号方案的condition(条件)，也可以调用http接口，根据返回的结果和正则表达式进行匹配。具体可以看下图的例子。注意返回的数据前后不要有空格换行等不可见字符，会导致和正则表达式匹配不上。如果返回的是json数据，expression 和json的body属性 进行正则匹配，如果返回的是非法json数据，expression 直接和返回的文本数据匹配。

拨号方案中写redis和读redis

cti_hash_get hash field [varname] ，cti模块定义了cti_hash_get这个同名的API和APP，用来读取redis的hash表.

• hash 表的key

• field hash表的 field

• varname 读取到的value存放的变量

cti_hash_set hash field value cti模块定义了cti_hash_set这个同名的API和APP，用来设置redis的hash表

APP就是一个动作，拨号方案里面可以直接添加动作，拨号方案调用API就和使用变量一样${API名字(参数)}，多个参数用空格隔开，可以用set 这个APP把API的返回结果写入变量。也可以嵌套使用比如${cti_extension_exists(${cti_hash_get(callhistory@${cti_domain} ${cti_mid_string(${caller_id_number} -11)})})},如果不需要把返回结果写入变量，只是想执行这个API，可以用eval ，这个什么也不做的APP去调用API。

实现DID功能的例子

redis 创建一个 key 名字：cti_did@域名 ,类型：hash， filed 是DID号码， value为分机号。

匹配表达式写法 ${cti_extension_exists(${cti_hash_get(cti_did@${cti_domain} ${destination_number}}}))}

拨号方案例子，如果 cti_hash_get 没有设置获取value的变量名参数， 就会把获取到的数据 写入 默认变量 cti_hash_get_last_result。

拨号方案从redis获取通道变量

cti_variable hash field ，cti模块定义了cti_variable 这个同名的API和APP，用来从redis的hash表获取通道变量.

• hash 表的key

• field hash表的 field

  { "set": { "变量名": "值" }, "export": { "变量名": "值" }, "bridge_export": { "变量名": "值" } }

  • set 用法同 set
  • exort 用法类似export，和export的区别，会直接扩展变量
  • bridge_export 用法类似bridge_export，和bridge_export的区别，会直接扩展变量

被叫和路由、目的地绑定的例子

redis 创建一个 key 名字：cti_inbound_rule@域名 ,类型：hash， filed 是DID号码， value为json格式的转接规则。

{
    "set": {
        "cti_inbound_dest": "555",
        "cti_inbound_route": "internal"
    }
}

• cti_inbound_dest 转接目的地，如果要转接到分机，就是分机号，如果要转接给排队，就是排队号。

• cti_inbound_route 转接路由，如果要转接给分机，就是internal,如果要转接给排队，就是 acd。

  拨号方案的匹配表达式写法${cti_variable(cti_inbound_rule@${cti_domain} ${destination_number})}

  如果找到了规则，就把cti_inbound_dest和cti_inbound_route设置到通道变量。

  

通过http接口返回动作

APP cti_curl http://ip/app?number=${destination_number} cti_curl 这个APP会调用http，执行接口返回的动作。

返回例子说明，数组格式，支持多个动作。

[{"application":"log","data":"INFO 3text"}]

ivr例子

[
	{
		"application": "read",
		"data": "1 1 /var/1.wav input_dtmf 5000"
	},
	{
		"application": "cti_curl",
		"data": "http://ip/app?number=${destination_number}&call=${uuid}&input_dtmf=\\${input_dtmf}"
	}
]

read 放音并且读取DTMF，参数说明 <min> <max> <sound file> <variable name> <timeout> <terminators>

cti_curl 提交读取到的DTMF结果，继续返回新的放音。

如果需要实现按键错误提示音，可以使用 play_and_get_digits 代替 read, 具体可以看FreeSWITCH官方文档 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod-dptools/6586933/

自动外呼输入分机号（比如隐私号）

再执行机器人或者进入排队的动作之前，拨号方案里面的动作cti_robot,或者cti_acd 之前，添加一个动作 cti_dial_exten，参数 exten <rfc2833|inband> <wait_prompt_time> <input_prompt> <wait_input_time>

1. exten 分机
2. rfc2833|inband 发送DTMF类型 ,有的线路不支持rfc2833需要用inband,有的又不支持inband需要rfc2833,建议用inband 兼容性更好，可以根据自己的线路情况测试。
3. wait_prompt_time 等待请输入分机号的提示音时间 单位毫秒，比如设置10000，就是检测提示音最大时间10秒，检测到了提示音结束就发送按键，如果超过了10秒提示音也没播放或者还在播放提示音也发送按键。
4. input_prompt 发送分机号之后播放的提示音，可选。比如循环拨号一个提示音。类如按任意键转人工
5. wait_input_time 等待按键超时时间，可选。只有设置了播放提示音才有效

例子
action = cti_dial_exten data=1234 inband 10000

长签（坐席签入后不挂机等待来电）

长签就是坐席呼叫一个特别号码，接通后不挂机，一直等待接电话，没电话呼入的时候，听背景音乐。 一般用自动应答来实现呼入免操作直接接通，但是有的客户习惯长签模式，顶顶通呼叫中心中间件长签后，不光支持排队分配的电话直接接听，其他电话也一样可以呼入，做到了长签，却不占线。
例子：
action = cti_line_check_in data=linename moh

• linename 线路名 如果不设置会使用拨打电话的来电作为线路名，长签绑定的线路，长签后，线路并发会强制改成1，退出长签(电话挂机)后恢复默认并发设置。
• moh 保持音乐 如果不设置默认使用local_stream://default 配置文件->local_stream.conf 里面配置的默认保持音乐，也可以单独指定一个声音文件。

并发限制

限制并发，app默认超过限制会自动挂机，api通过参数控制超过是否挂机
app cti_limit_inc 参数1:限制类型 参数2:最大并发
api cti_limit_inc 参数1:限制类型 参数2:最大并发 参数3:[hangup]
api uuid_cti_limit_inc 参数1:限制类型 参数2:最大并发 参数3:[hangup]
挂机后会自动把统计的并发降1，如果需要提前降1，可以执行通过cti_limit_dec。
api cti_limit_dec 参数1:限制类型
例子限制呼入并发

${cti_limit_inc(callin 30)} 如果超过30并发返回false,没超过返回true。

对接黑名单

api cti_http_blacklist url [caller] [callee]
app cti_http_blacklist url [caller] [callee]
如果不设置caller和callee自动从通道变量caller_id_number和destination_number获取。
例子

流对接（推流到第三方接口和同时播放流）

app： cti_audio_stream
参数 remote-ip:remote-port

• native 可选参数 如果不设置，流格式为 8000hz 16位，如果设置了，就是原始的音频格式
• param 自定义参数

推流协议

1. 前面4字节 引导数据长度 网络字节顺序
2. 时间戳 8字节
3. 引导数据 {"uuid":"","codec":"","param":"自定义参数"}
4. 数据流

连接断开后会自动重连，并且重发引导数据。
返回的放音流需要和推流的编码一样，不需要引导数据。

流对接（旁路）

app: cti_unicast_start 启动推流
参数 tcp|udp remote-ip remote-port <local-ip> <local-port> <play|mix>

• tcp|udp 使用tcp还是udp协议推流
• remote-ip 远端 ip
• remote-port 远端端口，不设置用0.0.0.0
• local-ip 本地端口,不设置好用0，随机端口
• play|mix
  • play 支持播放远端返回的流，发送方必须是远端IP和远端端口
  • mix 把远端的流和本地放音混音

api uuid_cti_unicast_start 启动推流
参数 uuid tcp|udp remote-ip remote-port <local-ip> <remote-ip> <play|mix>

api uuid_cti_unicast_stop 停止推流
参数 uuid

按键触发动作

action: bind_digit_action
参数 name,按键,api:api命令,api参数 或者

比如按键1调用一个URL

action=bind_digit_action data=dtmfcallurl,1,api:cti_http_get,http://demo.ddrj.com/dtmf?uuid=c3129712-17da-4783-a8bf-530c91b84244

按键参数支持正则表达式,更详细的说明请看 https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod-dptools/6586414/

限制最大通话时间

<action application="sched_hangup" data="[+]<time>[ <hangup_cause>]"/>

例子

action =sched_hangup data=+60 ALLOTTED_TIMEOUT

呼入转接

比如要根据主叫号码被叫号码等信息把呼叫转接到分机、排队等，通过编写拨号方案就可以实现这样的功能，cti模块提供了通过redis设置规则来实现呼入转接的功能，提高性能和方便二次开发的对接。
condition ${cti_transfer(inbound_rule)} ^true$
action =cti_transfer

inbound_rule是hash表的key为规则名字，value是规则配置。支持多个规则，只要成功匹配到一个规则，其他规则就不在匹配。

redis hash 表的 value（规则配置）格式如下

{
    "conditions": [
        [
            {
                "variable": "destination_number",
                "method": "=",
                "value": "5555"
            },
            {
                "variable": "caller_id_number",
                "method": "=",
                "value": "122"
            }
        ],
        [
            {
                "variable": "caller_id_number",
                "method": "=",
                "value": "124"
            }
        ]
    ],
    "variables": {
        "custom_variables": "test"
    },
    "exports": {
        "custom_variables": "test"
    },
    "applications": [
        {
            "application": "bridge",
            "data": "user/120"
        }
    ],
    "priority": 10
}

• conditions

  根据这个里面设置的条件，如果命中就执行 variables、exports、applications等配置。

  是二维数组, 用于实现or和and。第一维为or,就是只需要匹配上任意一个就算命中。第二唯为and,就是必须全部匹配才算命中。

  [["条件1","条件2"],["条件3"]] 这个例子中 条件1和条件2都满足才算匹配，如果条件1和条件2有一个不满足，但是条件3满足也算匹配成功。相当于(条件1 and 条件2) or 条件3) 。

  • variable 用来比较的通道变量

  • value 要比较的值

  • method 比较方法

    • = 同EQUAL

    • == 同EQUAL

    • EQUAL variable等于value，区分大小写，匹配成功

    • equal variable等于value，不区分大小写，匹配成功

    • > variable大于value 匹配成功

    • >= variable大于等于value 匹配成功

    • < variable小于value 匹配成功

    • <= variable小于等于value 匹配成功

    • contain variable包含value，不区分大小写，匹配成功

    • CONTAIN variable包含value，区分大小写， 匹配成功

    • prefix variable前缀是value，不区分大小写，匹配成功

    • PREFIX variable前缀是value，区分大小写， 匹配成功

    • suffix variable后缀缀是value，不区分大小写，匹配成功

    • SUFFIX variable后缀是value，区分大小写， 匹配成功

    • regexp 使用正则表达式匹配

• variables

  要设置的变量，变量只设置到本段。{"变量名字":"变量值"} 这样的格式,变量的值必须是字符串。

• exports

  要导出的变量，就是变量会设置到本端和后续bridge的新通道。

• applications

  ​ 多个APP按顺序执行。

  • application app的名字
  • data app的参数

• priority 规则优先级，如果有多个规则，按优先级匹配

人工坐席主动接管机器人对话的电话

1. 人工坐席直接呼入接管

   添加拨号方案，并且在internal路由中启用，放到呼叫外线前面。

   answer
   log info uuid_cti_stop_robot ${uuid_cti_stop_robot($1 intercept)}
   intercept $1

   

   sip软件直接呼叫 intercept通话callid 进入接管

2. http接口先呼叫坐席，然后执行接管拨号方案

   http://127.0.0.1:88/cli?key=abc&cmd=bgapi&arg=originate user/1000 intercept通话callid XML internal

拨号方案redis配置

1. cti_dialplan_extensio@domain [哈希表]
   • key 拨号方案的名字
   • value

录音的例子
{
    "condition": [
        {
            "field": "${record_filename}",
            "description": "测试是否已经启动录音",
            "expression": ".+",
            "anti-action": [
                {
                    "application": "export",
                    "data": "RECORD_READ_ONLY=false",
                    "description": "是否只录音对方"
                },
                {
                    "application": "export",
                    "data": "RECORD_WRITE_ONLY=false",
                    "description": "是否只录音本方"
                },
                {
                    "application": "export",
                    "data": "RECORD_BRIDGE_REQ=false",
                    "description": "是否应答后开始录音"
                },
                {
                    "application": "export",
                    "data": "RECORD_STEREO=false",
                    "description": "是否双道录音"
                },
                {
                    "application": "export",
                    "data": "record_filename=$${recordings_dir}/${strftime(%Y-%m-%d)}/${caller_id_number}.${destination_number}.${strftime(%H-%M-%S)}.${uuid}.wav",
                    "description": "录音录音文件名"
                },
                {
                    "application": "record_session",
                    "data": "${record_filename}",
                    "description": "开始录音"
                }
            ]
        }
    ],
    "continue": true
}

外呼的例子
{
    "condition": [
        {
            "field": "destination_number",
            "expression": "^00\\d*$",
            "description": "静止呼叫国际长途",
            "action": [
                {
                    "application": "hangup",
                    "description": "00开始的号码挂断"
                }
            ],
            "break": "on-true"
        },
        {
            "field": "destination_number",
            "expression": "^\\d+$",
            "description": "允许全数字号码呼出",
            "action": [
                {
                    "application": "bridge",
                    "description": "通过default网关呼出",
                    "data": "sofia/gateway/default/${destination_number}"
                }
            ]
        }
    ]
}

这里就不做解释了，具体参考FreeSWITCH的拨号方案写法。
支持嵌套等XML拨号方案的所有功能。

1. cti_dialplan_context@domain [list]

[
    "call extension",
    "call trunk",
    "testabc"
]

CTI模块根据顺序把cti_dialplan_extensio@domain里面的内容组合成一个拨号方案的XML文件。

呼叫路由规则

1. 分机呼叫使用的呼叫路由规则
   如果分机配置了呼叫路由，就优先使用分机配置的呼叫路由，如果分机没单独配置呼叫路由，就使用SIP配置internal(分机注册的那个profile)的呼叫路由，如果sip的profile配置也没配置呼叫路由，就使用default这个呼叫路由。
2. 网关呼入使用的呼叫路由
   如果网关配置了呼叫路由，就使用网关配置的呼叫路由，如果网关配置没配置呼叫路由，就使用SIp配置external(关联网关的那个profile)的呼叫路由，如果sip的profile配置也没配置呼叫路由，就使用default这个呼叫路由。
3. 呼叫路由配置必须小心，防止给盗打，网关和external配置的呼叫路由不能配置呼叫外线的拨号方案。

Info Application Variable Names (variable_xxxx)

Some variables, as shown from the info app, may have variable_ in front of their names. For example, if you pass a header variable called type from the proxy server, it will get displayed as variable_sip_h_type in FreeSWITCH™. To access that variable, you should strip off the variable_, and just do ${sip_h_type}. Other variables shown in the info app are prepended with channel, which should be stripped as well. The example below show a list of info app variables and the corresponding channel variable names: