FreeSWITCH的originate命令解析及示例
FreeSWITCH版本:1.10.9
操作系统:CentOS 7.6.1810
originate经常用于发起呼叫,在实际工作过程中用到的也比较多,今天总结下基本用法,也方便我以后查阅。
一、wiki及源码介绍
该命令在FreeSWITCH官方wiki也有介绍,这里列下wiki地址。
wiki首页:https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/
originate相关wiki地址:
源码文件:mod_commands.c
对应函数:originate_function
二、命令格式及解释
命令使用的基础模板:
originate ALEG BLEG
在fs_cli控制台使用的完整语法如下:
originate <call url> <exten>|&<application_name>(<app_args>) [<dialplan>][<context>] [<cid_name>][<cid_num>] [<timeout_sec>]
其中,
originate 为命令关键字,为必选字段,用于定义ALEG的呼叫信息,也就是通常说的呼叫字符串,可以通过通道变量定义很多参数;
|&<application_name>(<app_args>) 为必选字段,用于指定BLEG的分机号码或者用于创建BLEG的app(比如echo、bridge等);
[][<context>] 可选参数,该参数用于指定dialplan的context,默认值:xml default ;
[<timeout_sec>] 可选参数,该参数用于指定originate超时,默认值:60 ;
示例呼叫:
originate user/1000 9196 xml default 'mike' 18612345678
呼叫效果如下:
三、常见使用方式
1、基础使用
-
echo呼叫
示例如下:
originate user/1000 &echo
先呼叫1000分机,1000分机接听后,将1000分机所在的channel桥接到echo应用(将话筒传入的声音播放到听筒),以下命令具备同样效果:
originate user/1000 9196
-
分机互相拨打
示例如下:
originate user/1000 1001
先呼叫1000分机,1000分机接听后,再呼叫1001分机,1001分机接听后,将1000分机所在的channel桥接1001的channel,通话建立。
-
bridge到其它终端
这里以分机为例进行演示,具体如下:
originate user/1000 &bridge(user/1001)
和分机互相拨打类似。
-
分机共振
使用逗号语法关键字,示例如下:
originate user/1000,user/1001 9196
1000分机和1001分机同时响铃,任意一个分机接听后,另外一个分机自动挂机。
-
分机轮询
使用 | 语法实现,这里需要注意下,有呼叫默认超时时间的设置,示例如下:
originate {originate_timeout=30}[leg_timeout=10]user/1000|[leg_timeout=10]user/1001 9196
1000分机先振铃,10秒超时后呼叫1001分机。
-
呼叫外线
通过external进行外线呼叫,示例如下:
originate {origination_caller_id_number=00000000,origination_caller_id_name=000000000}sofia/external/18612345678@192.168.1.100:5060 &echo
-
播放音频给分机
使用playback命令进行声音播放:
originate user/1000 &playback(/tmp/test1.wav)
播放moh音频:
originate user/1000 &playback(local_stream://moh)
无限循环播放:
originate user/1000 &endless_playback(/tmp/test1.wav)
使用file_string进行多个文件依次顺序播放:
originate user/1000 &playback(file_string:///tmp/test1.wav!/tmp/test2.wav)
2、通道变量的使用
originate字符串里面可以设置很多通道变量来定义呼叫参数,基本使用格式示例如下:
originate {var1=$value1,var2=$value2}/user/1000 9196 originate {var1=$value1}[var2=$value2]/user/1000 9196
其中,大括号用于定义呼叫的通道变量,中括号用来定义某条leg的局部通道变量。
这里列举下常见的通道变量。
-
origination_uuid
发起呼叫时,用于定义leg的uuid,示例如下:
1)在呼叫时,指定A腿的uuid
originate {origination_uuid=xxxxx}user/1000 1001
2)在呼叫时,同时指定A腿和B腿的uuid
originate {origination_uuid=xxxxx}user/1000 &bridge({origination_uuid=yyyyy}user/1001)
-
origination_caller_id_name / origination_caller_id_number
用于设置主叫名称及号码,示例如下:
originate {origination_caller_id_name="mike",origination_caller_id_number=18612345678}user/1000 9196
会在话机及sip协议中体现,具体如下:
-
ignore_early_media
该参数适用于A leg,定义是否忽略B leg的early media。
-
originate_timeout
用于定义originate/bridge过程中的呼叫时长,超过该时间后就呼叫超时。
示例参考分机轮询部分。
-
leg_timeout
用于定义originate/bridge过程中某条leg的呼叫时长,超过该时间后就呼叫超时。
示例参考分机轮询部分。
-
absolute_codec_string
用于指定语音编码,示例如下:
originate {absolute_codec_string=‘^^:PCMA:PCMU’}user/1000 &playback(local_stream://moh)
其中,"^^"为转义符,后面跟冒号表示用冒号替代逗号。
-
自定义通道变量
在originate字符串中可以自定义通道变量,示例如下:
originate {var123="test123"}user/1000 9196
效果如下:
通道变量名称会自动添加 variable_ 前缀,具体来说就是 variable_var123
-
更多通道变量
具体参考switch_ivr_originate函数(switch_ivr_originate.c文件)
3、添加自定义sip头
在originate字符串中,可以自定义sip头,通过添加 sip_h_X 前缀来试下,示例如下:
originate {sip_h_X-varTest='123456'}user/1000 &playback(local_stream://moh)
会在sip协议中添加自定义的header,具体效果如下:
4、特殊呼叫
-
loopback呼叫
1)拨号方案自带的loopback
示例呼叫:
originate user/1000 &bridge(loopback/wait)
具体定义如下:
2)自定义loopback
dialplan添加如下内容:
<extension name="loopback_test"> <condition field="destination_number" expression="^loopTest1$"> <action application="answer"/> <action application="playback" data="local_stream://moh"/> </condition> </extension>
呼叫测试:
originate user/1000 &bridge(loopback/loopTest1)
-
null呼叫
呼叫示例:
originate null/1000 &echo
具体效果:
也可以和bridge一起使用:
originate user/1000 &bridge(null/1234)
具体效果:
-
其它endpoint呼叫
这里以rtc为例,演示其它endpoint呼叫:
bgapi originate {origination_uuid=111222}rtc/test &echo
具体效果如下:
-
指定sip使用tcp协议呼叫
需要使用 transport=tcp 来指定协议,示例如下:
originate {origination_caller_id_name=1111}user/1000;transport=tcp &playback(local_stream://moh)
效果如下:
四、资源下载
本文涉及freeswitch源码及使用的测试软电话可从如下渠道获取:
https://pan.baidu.com/s/16-H-ITuXAcPYRsZpa3At-g
关注微信公众号(聊聊博文,文末可扫码)后回复 2023040201 获取。