About
This page contains a list of every variable defined in the documentation. If you find a variable that's defined somewhere else, but not here, that's a bug!
absolute_codec_string
string Sets the absolute codec string to use (nothing will be appended).Usage
<action application="set" data="absolute_codec_string=PCMU,GSM"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
accountcode
string Account code is mostly an arbitrary value that you can assign on a per leg basis. An important feature of accountcode is that if its value matches one of the CDR CSV templates defined incdr_csv.conf.xml
then that CDR template will be used when generating a CSV CDR.Usage
<action application="set" data="accountcode=custom"/>
acl_token
string If an incoming SIP INVITE message matches against a user ACL, this variable is set to the user ID and domain name.alert_info
string Add anAlert-Info
Header like Snom and other Phones need for Ring or Ringtone information.Usage
Load an external WAV ringtone on all calls:
<action application="export" data="alert_info=http://192.168.181.5/sounds/ctu.wav"/>
Use the External Ringer (Change the Ringtone for the alert-external, alert-group and alert-internal in Snom under Setup > Preferences > Alert-Info Ringer):
<action application="export" data="alert_info=http://www.notused.com;info=alert-external;x-line-id=0"/>
answer_epoch
integeranswer_stamp
stringanswer_uepoch
integeranswermsec
integeranswersec
integeranswerusec
integerapi_after_bridge
string Execute an API command after bridge.Usage
Paging to PA System via Portaudio (with chime before and after announcement):
<extension name="paging-with-chime"> <condition field="destination_number" expression="^7243$"> <action application="set" data="bridge_pre_execute_bleg_app=playback"/> <action application="set" data="bridge_pre_execute_bleg_data=/tmp/2_tone_chime.wav"/> <action application="set" data="api_after_bridge=luarun post-chime.lua"/> <action application="bridge" data="portaudio/auto_answer"/> </condition> </extension>
post-chime.lua
:
api = freesswitch.API() api:execute("pa", "play /tmp/2_tone_chime.wav")
api_hangup_hook
string Execute an API command on hangup.See also:
- session_in_hangup_hook
- api_reporting_hook - like
api_hangup_hook
but after reporting state (both honor session_in_hangup_hook)
Usage
<action application="set" data="api_hangup_hook=jsrun cleanup.js ${uuid}"/>
api_on_answer
string Execute an api (not an application) when the called party answers. To set an application, use execute_on_answer.Usage
<action application="export" data="nolocal:api_on_answer=uuid_broadcast ${uuid} beep.wav both"/>
<action application="bridge" data="{api_on_answer='uuid_broadcast ${uuid} beep.wav both'}sofia/gateway/provider/5551231234"/>
api_on_media
string Execute a FreeSWITCH API command when the far end sends media, i.e. ringing or 183/SDP.The command is executed only on channels that are not already answered. Just use export
or export
with nolocal:
prefix to make sure it is executed when b-leg answers.
Usage
<action application="export" data="nolocal:execute_on_media=lua incrInUse.lua ${uuid}"/>
api_on_originate
stringapi_on_post_originate
string Execute an api on the chosen newly originated channels unlike api_on_originate which runs on all candidates.api_on_pre_answer
stringapi_on_pre_originate
stringapi_on_ring
stringapi_on_sip_extra_headers
stringapi_on_startup
string Execute an api (not an application) when the switch starts up.Usage
<X-PRE-PROCESS cmd="set" data="api_on_startup=sofia recover"/>
api_on_tone_detect
stringasr_intercept_dtmf
stringauto_answer_destination
string In an inbound call, the remote side may send aSIP NOTIFY
message with the event type talk
, telling Sofia endpoint to answer the call. In this case, the variable auto_answer_destination
is set to the channel's destination_number, and the call is transferred to the extension auto_answer
within current dialplan and context.auto_hunt
boolean Settingauto_hunt
to true
will alter the normal sequential processing of dialplan extensions. auto_hunt
will cause the dialplan to 'jump' to a specific extension name, not processing any other extension. The destination_number and extension name must be the same in order for this to work. The condition must still match, but the extension name is the operative element.Usage
In conf/vars.xml
:
<X-PRE-PROCESS cmd="set" data="auto_hunt=true"/>
<extension name="do_xfer"> <condition field="destination_number" expression="^.*$"> <action application="set" data="auto_hunt=true"/> <action application="transfer" data="333"/> </condition> </extension> <extension name="333"> <condition field="destination_number" expression="^333$"> <action application="info"/> </condition> </extension>
base_dir
stringThis defines the base directory for most other directory settings
billmsec
integerbillsec
integerbillusec
integerbind_meta_key
dtmf digit Selects the meta key to use with the bind_meta_app dialplan application.Usage
<action application="set" data="bind_meta_key=#"/>
bridge_answer_timeout
integer Timeout in seconds how long to tolerate a bridge that is in early media without being answered (can be set on either leg). Introduced in build 15057.See also: Early Media
Usage
<action application="set" data="bridge_answer_timeout=20"/>
bridge_channel
stringbridge_early_media
boolean By default this is false. Set to true, this makes the bridge use the live audio from the b-leg as ringback to the a-leg. Setting bridge_early_media=true
means the early media will be buffered.
Consider setting this to true if:
- you are using a loopback channel to execute a bridge to an endpoint which sends back early media and the received early media's audio is degraded.
Note: The buffering resulting from setting bridge_early_media=true
brings with it a higher resource cost than bridge_early_media=false
, but may improve the sound quality of the early media. Set bridge_early_media
before the bridge, or in the dial string for the bridge.
- you are using multiple targets in originate or bridge (e.g.: originate {globalVar=global}[channelVar=channel1]sofia/gateway/GW1/123456|[channelVar=channel2]sofia/gateway/GW2/123456) where you need to receive network generated Call Progress Tones (e.g.: ringtones and network announcements). You can combine this with continue_on_fail so you can fine-tune fallback on specific release causes only.
bridge_epoch
integerbridge_export_vars
string bridge_export_vars
lists variables to be exported to the other leg upon bridge.
bridge_filter_dtmf
boolean Setting this variable totrue
will prevent DTMF digits received on this channel when bridged from being sent to the other channel.Usage
In the dialplan:
<action application="set" data="bridge_filter_dtmf=true" />
Dialstring:
{bridge_filter_dtmf=true}sofia/default/blah@baz.com
bridge_generate_comfort_noise
string Generates comfort noise when bridged session is receiving discontinuous audio frames (silence suppression).When greater than 0
, this variable is set to the divisor of the silence generating function. 400 or 1400 are common values set, but you may experiment with other choices to pick one that sounds best.
When true
, FreeSWITCH will pick a default comfort noise value.
When -1
, FreeSWITCH will transmit silence without comfort noise. (As of 2012-10-25)
Usage
Leg A wants a continuous stream of audio, but leg B is using silence suppression:
<action application="set" data="bridge_generate_comfort_noise=true"/> <action application="bridge" data="sofia/user/1000"/>
Leg A uses silence suppression, but leg B wants a continuous stream of audio:
<action application="bridge" data="{bridge_generate_comfort_noise=true}sofia/user/1000"/>
bridge_hangup_cause
string This is set to the hangup cause of the last bridged B leg of the call. If you havecontinue_on_fail=true
and hangup_after_bridge=false
you can do checks on this to see what "really" happened to the call. You can for instance do execute_extension after bridge, do a condition check on ${bridge_hangup_cause}
to see if it contains MEDIA_TIMEOUT and then trigger a redial of the call or transfer to a cell phone. For a list of hangup causes, see Hangup Causes.Usage
<action application="log" data="1 B-leg hangup cause: ${bridge_hangup_cause}"/>
bridge_pre_execute_aleg_app
string Command or api to be executed on the A leg before bridging the two channels. App arguments can be passed by setting bridge_pre_execute_aleg_data. this is executed AFTER the call is setup but BEFORE the media (audio) is bridged
bridge_pre_execute_bleg_app
string Command or api to be executed on the B leg before bridging the two channels. Useful when originating a call from the event socket, CLI or XML-RPC.It could for instance be used to do a HTTP GET with a script or mod_http to the IP address of a Snom phone to increase the ringer volume if you need to do a wakeup call.
Can also be used to bind a dtmf to an app on the b leg of a call so that it can survive a transfer.
Arguments can be passed to the app with bridge_pre_execute_bleg_data.
this is executed AFTER the call is setup but BEFORE the media (audio) is bridged.
Usage
<action application="set" data="bridge_pre_execute_bleg_app=bind_meta_app"/> <action application="set" data="bridge_pre_execute_bleg_data=1 a s att_xfer::sofia/profile/destination"/>
bridge_pre_execute_bleg_data
string Arguments to be used with bridge_pre_execute_bleg_app.Usage
<action application="set" data="bridge_pre_execute_bleg_app=bind_meta_app"/> <action application="set" data="bridge_pre_execute_bleg_data=1 a s att_xfer::sofia/profile/destination"/>
bridge_stamp
stringbridge_terminate_key
dtmf digit Allows you to bind a key and the bridge will terminate if the DTMF matches.You can set bridge_terminate_key
on either or both legs which will end the bridge, if it hangs up or not is decided by hangup_after_bridge=false
or what is next in your dialplan.
bridge_to
stringbridge_uepoch
integerbridge_uuid
stringbypass_keep_codec
boolean By doing exportbypass_keep_codec=true
to force re-invite with the same codec it was using previously.bypass_media
boolean When set, the media (RTP) from the originating endpoint is sent directly to the destination endpoint and vice versa. The signaling (SIP) for both endpoints still goes through FreeSWITCH, but the media is point-to-point. See also: Bypass Media OverviewUsage
<action application="set" data="bypass_media=true"/>
bypass_media_after_bridge
boolean Same as bypass_media but will handle media for a call until it has reached the answered state (and has processed a few RTP frames.) At this point FreeSWITCH will use a ReInvite to take itself out of the media path. This helps reduce audio latency and take some load off FreeSWITCH. Especially useful for UACs behind Coned NAT as it gives RTP Auto-Adjust enough time to determine the correct ports to avoid one-way audio.cache_dir
stringcache_speech_handles
stringcall_clientcode
string This is used by SNOM phones. When FreeSWITCH receives aSIP INFO
message with x-clientcode
header, this variable is set to the value of that header.call_timeout
integer Controls how long (in seconds) to ring the B leg of a call when using the bridge application. The timeout is set on the A leg, and applies to any bridges that happen in the channel.If you need to set a timeout on a call that has no A leg, use originate_timeout.
If you need to set a timeout with enterprise bridging/originate, use originate_timeout.
If you need to set the timeout on a per-leg basis (i.e. a different timeout for each destination), use the leg_timeout variable.
Beware that if you are not using {
ignore_early_media=true}
, call_timeout
is no longer applicable as soon as early media signal is received.
Default Value: 60
Usage
<action application="set" data="call_timeout=20"/>
If a call timeout is to be specified against a group_call() list, use the following format:
<action application="bridge" data="{originate_timeout=24}${group_call(sales@$${domain})}"/>
See Also
bridge_answer_timeout - to set unanswered timeout that circumvents early media
leg_timeout - to set unanswered timeout on an individual call leg
originate_timeout - to set unanswered timeout that circumvents early media
callee_id_name
stringcallee_id_number
stringcaller_id_name
string readonly The caller id name set by the inbound call, not a real variable. Practically it is read only.caller_id_number
string readonly The caller id phone number set by the inbound call, not a real variable. Practically it is read only. From sofia.c, the values used (in precedence) are the user parts from:P-Preferred-Identity
, P-Asserted-Identity
, Remote-Party-ID
, and the From
header.campon
boolean Controls whether camping is enabled or not.Default: false
Usage
<action application="set" data="campon=true"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
campon_announce_sound
string File to play back after the first bridge fails (e.g. to announce what key to press to skip to fallback extension).Default: none
Usage
<action application="set" data="campon=true"/> <action application="set" data="campon_stop_key=1"/> <action application="set" data="campon_announce_sound=press_one_to_stop.wav"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
campon_fallback_context
string Optional context name where the call is transferred for fallbackcampon_fallback_dialplan
string Optional dialplan name where the call is transferred for fallbackcampon_fallback_exten
string Extention number where the call is transferred for fallbackcampon_hold_music
string Optional hold music to play while camping instead of default hold_music.Usage
<action application="set" data="campon=true"/> <action application="set" data="campon_hold_music=/data/campmusic/RelaxingCampSounds.wav"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
campon_retries
integer Controls how many times the bridge will be retried before falling back.Default: 100
Usage
<action application="set" data="campon=true"/> <action application="set" data="campon_retries=13"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
campon_sleep
integer Controls how long to wait before starting a retry.Default: 10
Usage
<action application="set" data="campon=true"/> <action application="set" data="campon_sleep=30"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
campon_stop_key
dtmf digit DTMF digit that breaks the campon loop and skips directly to fallback extensionDefault: none
Usage
<action application="set" data="campon=true"/> <action application="set" data="campon_stop_key=1"/> <action application="set" data="campon_announce_sound=press_one_to_stop.wav"/> <action application="set" data="campon_fallback_exten=1000"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
campon_timeout
integer This variable controls how long to attempt each bridge before timing out. It works exactly like call_timeout but only applies to camping.Default: 10
Usage
<action application="set" data="campon=true"/> <action application="set" data="campon_timeout=20"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
cdr_csv_base
string
certs_dir
stringCHANNEL
stringchannel_name
stringcodec_string
string Sets the base codec string to use.Usage
<action application="set" data="codec_string=PCMU,GSM"/>
conf_dir
stringconference_auto_outcall_announce
string File name of audio message to play to conference member joining conference via the conference_set_auto_outcall application. Because the conference would be originating an outbound call to a member this typically would be a greeting with an explanation that the recipient will be joining a conference call.Usage
<action application="set" data="conference_auto_outcall_announce=sounds/soundfile.wav"/>
conference_auto_outcall_caller_id_name
string Caller ID name to use when dialing endpoints to join the conference via the conference_set_auto_outcall application.Usage
<action application="set" data="conference_auto_outcall_caller_id_name=$${effective_caller_id_name}"/>
conference_auto_outcall_caller_id_number
string Caller ID number to use when dialing endpoints to join the conference via the conference_set_auto_outcall application.Usage
<action application="set" data="conference_auto_outcall_caller_id_number=${effective_caller_id_number}"/>
conference_auto_outcall_flags
string Conference flags to set for members joining conference via the conference_set_auto_outcall application.Usage
<action application="set" data="conference_auto_outcall_flags=mute"/>
conference_auto_outcall_maxwait
integer Maximum time in seconds that the channel that initiated the conference_set_auto_outcall will wait for members to join the conference.Usage
<action application="set" data="conference_auto_outcall_maxwait=10"/>
conference_auto_outcall_prefix
string The value ofconference_auto_outcall_prefix
is prepended to each of conference_set_auto_outcall values, of which there can be more than one.Usage
<extension name="mad_boss_intercom"> <condition field="destination_number" expression="^0911$"> <action application="set" data="conference_auto_outcall_caller_id_name=Mad Boss1"/> <action application="set" data="conference_auto_outcall_caller_id_number=0911"/> <action application="set" data="conference_auto_outcall_timeout=60"/> <action application="set" data="conference_auto_outcall_flags=mute"/> <action application="set" data="conference_auto_outcall_prefix={sip_auto_answer=true,execute_on_answer='bind_meta_app 2 a s1 transfer::intercept:${uuid} inline'}"/> <action application="set" data="sip_exclude_contact=${network_addr}"/> <action application="conference_set_auto_outcall" data="${group_call(sales)}"/> <action application="conference" data="madboss_intercom1@default+flags{endconf|deaf}"/> </condition> </extension>
conference_auto_outcall_profile
string Conference profile to use for members joining the conference via the conference_set_auto_outcall application.Usage
<action application="set" data="conference_auto_outcall_profile=default"/>
conference_auto_outcall_timeout
integer Originate timeout to use when joining a member to a conference via conference_set_auto_outcall.Usage
<action application="set" data="conference_auto_outcall_timeout=60"/>
conference_controls
string Set this variable to specify which conference control set to use when transferring a caller into a conference. This allows you, for example, to have a control set for the conference moderator and another control set for regular conference members. The control set for the moderator could include the ability to mute or kick people, for example. You must create the desired conference control set. Also, if this is not set then the default conference control set is used for the conference member.
Usage
<action application="set" data="conference_controls=moderator"/>
conference_enforce_security
boolean Allows the conference security to be overridden. This applies in two different scenarios, one for inbound and one for outbound. By default, conference security is always applied to inbound calls and is always skipped for outbound calls. This channel variable allows the behavior to be modified.Usage
Inbound:
<action application="set" data="conference_enforce_security=false"/> <action application="conference" data="3000"/>
Outbound:
originate {conference_enforce_security=true}sofia/internal/1001 &conference(3000)
conference_enter_sound
string When set, this channel variable will override the enter-sound param on conference profile for any conferences into which the call leg is transferred.Usage
<action application="set" data="conference_enter_sound=silence_stream://10"/>
conference_exit_sound
stringUsage
<action application="set" data="conference_exit_sound=silence_stream://10"/>
conference_last_matching_digits
dtmf digit readonly Contains the last matching digits that the user on this channel sent into the conference.Usage
<action application="log" data="INFO Last digits sent by this user: ${conference_last_matching_digits}"/>
conference_member_id
string Contains theconference_member_id
value for any conference to which the channel may be connected.conference_moderator
boolean Istrue
if the channel is connected to a conference as a moderator.conference_recording
string Contains the file name of the conference recording for the conference to which the channel is connected.conference_uuid
string Every instance of a conference has its own UUID. This channel variable stores the conference UUID for the most recent conference in which the channel was a member. It is set as soon as the channel enters the conference, and will show up in XML CDRs and uuid_dump calls, as well as any events that show channel variables.continue_on_fail
string Controls what happens when the called party can not be reached (busy/offline). Iftrue
the dialplan continues to be processed. If false
the dialplan will stop processing. Can contain the return messages that will continue on fail also.Usage
<action application="set" data="continue_on_fail=true"/>
<action application="set" data="continue_on_fail=NORMAL_TEMPORARY_FAILURE,USER_BUSY,NO_ANSWER,NO_ROUTE_DESTINATION"/>
With Q.850 cause codes:
<action application="set" data="continue_on_fail=3,17,18,27"/>
copy_xml_cdr
string Copies the other leg's XML CDR into this leg's CDR. For example, the A leg's CDR will contain a variable namedb_leg_cdr
whose contents are the URL-encoded XML CDR data from the B leg. This variable must be set on the B leg, so use {copy_xml_cdr=true}
in the dialstring or use export
instead of set
.Usage
<action application="bridge" data="{copy_xml_cdr=true}user/${dialed_extension}@${domain_name}"/>
core_uuid
stringcreated_time
string Contains the start time (in microseconds) of when the call was created.In the event that a call is transferred, this will contain the time of when the entire call was created, not that specific transfer. If you need the transfer created time, see profile_created_time and variable_progress_time.
current_application
stringcurrent_application_data
stringcurrent_application_response
stringdata
stringdb_dir
stringdefault_language
string Controls the default language the Say Phrase engine will use when no language is explicitly specified in the API call. This permits you to easily support multiple languages by only changing a single variable at call time.Usage
<action application="set" data="default_language=fr"/>
deny_refer_requests
string If this variable is set totrue
on either leg of a bridged SIP call, and the other end sends a REFER
request, this will be denied by FreeSWITCH.destination_number
string
dialed_domain
stringdialed_group
stringdialed_user
stringdigits_dialed
string
Seems to be the DTMF buffer, but only seems to be set on hangup. At least it only shows up in CHANNEL_HANGUP
and CHANNEL_HANGUP_COMPLETE
, but then all the entered DTMF digits are there.
TODO So where is the buffer, and how to access it and to flush it? (The latter may be important for a long running IVR).
UPDATE: it's not the DTMF buffer...
direction
string It is used to determine if the particular leg of the call is inbound or outbound.Usage
<condition field="${direction}" expression="^inbound$">
disable_app_log
booleandisable_q850_reason
boolean When set to true, this disables sending of the Reason header, which includes the Q.850 reason code, in responses and BYEs. For a list of hangup causes and their Q.850 codes, see Hangup Causes. This is available as of revision 15850 committed 12/8/2009.Usage
<action application="set" data="disable_q850_reason=true"/>
disable_radius_start
booleandisable_radius_stop
booleandisable_rtp_auto_adjust
string Disable rtp auto adjust if it is not behaving as you expected. It stops the switch from rewriting the RTP destination based on the source. When RTP Auto-Adjust is ON FreeSWITCH will change the destination RTP address to match the source of the incoming packets, this doesn't work if the other end is really wanting to send and receive on a different addr.Usage
Add {disable_rtp_auto_adjust=true} in your dial string.
DISPLACE_HANGUP_ON_ERROR
boolean When set totrue
this channel variable will cause the call to hangup if there is an error when trying to mod_commands#uuid_displace the call. The default is false
. The default behavior before 2013/03/21 was to hangup.Usage
<action application="set" data="DISPLACE_HANGUP_ON_ERROR=true"/>
dl_cid_msg
stringdl_from_host
stringdl_from_user
stringdl_host
stringdl_user
stringdomain_name
stringdrop_dtmf
boolean Set this on an inbound channel before answer or on an outbound channel before the bridge/originate in order to prevent DTMF events from being sent to the channel.Only tested with RFC2833, may also work for INFO / inband. See - FS-4769Getting issue details... STATUS Commit 60f7849cbe72.
TODO RFC 2833 is obsoleted by RFC 4733.
Usage
<action application="set" data="drop_dtmf=true"/> <action application="answer"/>
<action application="export" data="nolocal:drop_dtmf=true"/> <action application="bridge" data="sofia/internal/100@1.2.3.4"/>
<action application="bridge" data="{drop_dtmf=true}sofia/internal/100@1.2.3.4"/>
drop_dtmf_masking_digits
dtmf digit Ifdrop_dtmf
is true
play specified tone for every tone received.Usage
Each DTMF tone that is entered into the a-leg will be dropped and a "d" sent to the b-leg.
<action application="set" data="drop_dtmf=true"/> <action application="set" data="drop_dtmf_masking_digits=d"/>
To drop and replace DTMF on the b-leg use:
<action application="export" data="nolocal:drop_dtmf=true"/> <action application="export" data="nolocal:drop_dtmf_masking_digits=d"/>
drop_dtmf_masking_file
string Ifdrop_dtmf
is true
, play specified file for every tone received.Usage
Each DTMF tone that is entered into the a-leg will be dropped and the file dtmf_masking_tone
played to the b-leg.
<action application="export" data="drop_dtmf=true"/> <action application="export" data="drop_dtmf_masking_file=/etc/freeswitch/Sounds/dtmf_masking_tone"/>
To drop and replace DTMF on the b-leg use
<action application="export" data="nolocal:drop_dtmf=true"/> <action application="export" data="nolocal:drop_dtmf_masking_file=/etc/freeswitch/Sounds/dtmf_masking_tone" />
A, B, C, D tones
Make sure to expect (and handle) the DTMF tones A
, B
, C
, and D
; these are very rare nowadays but they are still possible to send (e.g., someone has an old device with the extra ABCD column). See DTMF for more.
dtmf_type
string For inband DTMF, start_dtmf must be used in the dialplan.Usage
<action application="set" data="dtmf_type=info"/>
<action application="set" data="dtmf_type=rfc2833"/>
TODO RFC 2833 is obsoleted by RFC 4733.
<action application="set" data="dtmf_type=none"/>
dtmf_verbose
boolean Enables verbose logging of Spandsp DTMF detector. Default isfalse
. Set this variable prior to executing spandsp_start_dtmf.Usage
<action application="set" data="dtmf_verbose=true"/> <action application="spandsp_start_dtmf" />
duration
integereasy_acctcode
stringeasy_destnum
stringeasy_dialstring
stringeasy_group
stringeasy_limit
stringeavesdrop_annnounce_macro
stringeavesdrop_announce_id
stringeavesdrop_group
stringeavesdrop_indicate_failed
stringeavesdrop_indicate_idle
stringeavesdrop_indicate_new
stringeavesdrop_require_group
stringeffective_ani
stringeffective_aniii
stringeffective_caller_id_name
string Sets the effective callerid name. This is automatically exported to the B-leg; however, it is not valid in an origination string. In other words, set this before calling bridge, otherwise use origination_caller_id_name.Snom 370/820
If you want to display LEG A's name (if available) as soon as LEG B (here the local Snom) rings, you have to set origination_caller_id_name
or effective_caller_id_name
as described. Otherwise, in LEG B's display, you will see LEG A's number during ringing and switching to LEG A's name after picking up the call by LEG B. To remove it set it to _undef_
.
Usage
<action application="set" data="effective_caller_id_name=Bob Smith"/>
effective_caller_id_number
string Sets the effective callerid number. This is automatically exported to the B-leg; however, it is not valid in an origination string. In other words, set this before calling bridge, otherwise use origination_caller_id_number.Usage
<action application="set" data="effective_caller_id_number=9185551212"/>
effective_sip_cid_in_1xx
boolean Prevents FreeSWITCH when it receives 183 from leg-B to automatically insert RPID before sending 183 to leg-A.Usage
<action application="set" data="sip_cid_in_1xx=false"/>
enable_file_write_buffering
string Enable file buffering when recording a file, defaults totrue
if not set. Buffer size defaults to SWITCH_DEFAULT_FILE_BUFFER_LEN
but can be overridden by putting bytes size instead of true
(see below example). Mailing list discussionUsage
<action application="set" data="enable_file_write_buffering=false"/>
<action application="set" data="enable_file_write_buffering=true"/>
<action application="set" data="enable_file_write_buffering=65535"/>
enable_heartbeat_events
booleanend_epoch
integerend_stamp
stringend_uepoch
integerendpoint_disposition
stringep_codec_prefer_sdp
stringep_codec_prefer_sdp
contains the "endpoint" codec string on the A leg. The order of preference is chosen by the A legep_codec_string
stringep_codec_string
contains the "endpoint" codec string on the A leg. This codec list includes only the codecs that both the A leg and FreeSWITCH agree upon. This variable is set only when inbound-late-negotiation is enabled on the SIP profile. When there is more than one codec in the list, the order of preference is chosen by FreeSWITCH, not by the A leg.
Usage
<action application="bridge" data="{absolute_codec_string=${ep_codec_string}}sofia/foo/bar@baz"/>
exec_after_bridge_app
string Execute an application command after the bridge has been terminated. To be used with exec_after_bridge_arg. By contrast, to execute when the bridge has been established use execute_on_answer.Usage
<action application="set" data="exec_after_bridge_app=transfer"/> <action application="set" data="exec_after_bridge_arg=2102"/>
exec_after_bridge_arg
string Argument passed to exec_after_bridge_app.Usage
<action application="set" data="exec_after_bridge_app=transfer"/> <action application="set" data="exec_after_bridge_arg=2102"/>
execute_on_answer
string Execute an application (not an api) when the called party answers. To set an api, use api_on_answer.execute_on_answer
will also allow for more control when dealing with no answer conditions in cases where you cannot ignore early media.The command is executed only on channels that are not already answered. Just use export
or export
with nolocal:
prefix to make sure it is executed when b-leg answers.
In the second usage example below, we have originated an outbound call to a local extension, where we will wait 30 seconds while manually ignoring media. In this case we use set
and not export
.
Usage
<action application="export" data="nolocal:execute_on_answer=lua incrInUse.lua ${uuid}"/>
To wait 30 seconds for an answer while 'manually' ignoring early media:
originate {ignore_early_media=true}sofia/gateway/my_gateway/5551212 885551212
<extension name="exe_on_ans"> <condition field="destination_number" expression="^88(\d+)$"> <action application="set" data="execute_on_answer=transfer ANSWEREDCALL XML default"/> <action application="log" data="INFO Waiting 30 seconds for $1 to answer..."/> <action application="sleep" data="30000"/> <action application="log" data="INFO Call to $1 was not answered, taking alternative action..."/> <action application="transfer" data="UNANSWEREDCALL XML default"/> </condition> </extension>
execute_on_fax_detect
stringexecute_on_fax_failure
stringexecute_on_fax_result
stringexecute_on_fax_success
stringexecute_on_media
string Execute an application when the far end sends media, i.e. ringing or 183/SDP.The command is executed only on channels that are not already answered. Just use export
or export
with nolocal:
prefix to make sure it is executed when b-leg answers.
In the second usage example below, we have originated an outbound call to a local extension, where we will wait 30 seconds without ignoring media. In this case we use set
and not export
.
Usage
<action application="export" data="nolocal:execute_on_media=lua incrInUse.lua ${uuid}"/>
To wait 30 seconds for an answer without ignoring early media:
originate sofia/gateway/my_gateway/5551212 885551212
<extension name="exe_on_ans"> <condition field="destination_number" expression="^88(\d+)$"> <action application="set" data="execute_on_media=transfer ANSWEREDCALL XML default"/> <action application="log" data="INFO Waiting 30 seconds for $1 to answer..."/> <action application="sleep" data="30000"/> <action application="log" data="INFO Call to $1 was not answered, taking alternative action..."/> <action application="transfer" data="UNANSWEREDCALL XML default"/> </condition> </extension>
execute_on_media_timeout
string Execute an application if the far end stops sending media and times out.Usage
<action application="export" data="nolocal:execute_on_media_timeout=lua oops_timeout.lua ${uuid}"/>
<action application="set" data="execute_on_media_timeout=transfer HANDLE_MEDIA_TIMEOUT XML default"/>
execute_on_originate
stringExecute syntax: <app> <arg>
Asynchronous syntax: <app>::<arg>
Executes code on successful origination.
Successful origination means the remote server responds, NOT when the call is actually answered.
Usage
originate {ignore_early_media=true,execute_on_originate='cng_plc'}sofia/gateway/foo/123456789 9664
originate {ignore_early_media=true,execute_on_originate='my_app::my_arg'}sofia/gateway/foo/123456789 9664
execute_on_post_bridge
STRING
execute_on_post_originate
string
execute_on_pre_answer
string Execute an application (not an api) when the called party "preanswers" - that is, when some form of early media is coming or the far end sends a 180 Ringing.The command is executed only on channels that are not already answered. Just use export
or export
with nolocal:
prefix to make sure it is executed when b-leg answers.
In the second usage example below, we have originated an outbound call to a local extension, where we will wait 30 seconds without ignoring media. In this case we use set
and not export
.
Usage
<action application="export" data="nolocal:execute_on_pre_answer=lua incrInUse.lua ${uuid}"/>
To wait 30 seconds for an answer without ignoring early media:
originate sofia/gateway/my_gw/5551212 885551212
<extension name="exe_on_preans"> <condition field="destination_number" expression="^88(\d+)$"> <action application="set" data="execute_on_pre_answer=transfer ANSWEREDCALL XML default"/> <action application="log" data="INFO Waiting 30 seconds for $1 to answer..."/> <action application="sleep" data="30000"/> <action application="log" data="INFO Call to $1 was not answered, taking alternative action..."/> <action application="transfer" data="UNANSWEREDCALL XML default"/> </condition> </extension>
execute_on_pre_bridge
STRING
execute_on_pre_originate
string
execute_on_ring
string Execute a command when the called party rings.Usage
<action application="set" data="nolocal:execute_on_ring=lua markring ${uuid}"/>
execute_on_sip_extra_headers
string Execute a command when SIP extra headers are detected in a SIP message.
execute_on_sip_reinvite
string Execute a command when SIP Reinvite.
execute_on_tone_detect
STRING
export_vars
stringexport_vars
lists variables to be exported to the other leg upon bridge. Unlike export, it only lists the variables to export without actually setting them. This is useful to transfer information from a-leg (INVITE) to the future b-leg of REFER.
EXTEN
stringfail_on_single_reject
string This is useful when using the,
AND operator in the data
field of a bridge. The AND operator notifies a list of destinations, bridging to the first destination that accepts the call. Typically if a destination in the list rejects the call, the bridge will continue to be attempted until either another destination accepts the call, or a timeout occurs. See below for an example of using fail_on_single_reject
with the |
OR operator.This variable allows one to terminate the bridging attempt on a single rejection of the call. This means the bridge attempt would fail, and if continue_on_fail has not been set, the call is terminated. This variable would be set within a condition before a bridge application. When used in conjunction with the continue_on_fail
variable, one can perform operations such as rolling over a rejected caller to an answering machine application.
The default setting is false
, meaning a single rejection will not terminate the bridging attempt.
It can also be set to a list of failure causes to stop on, and can be negated to a list of causes not to stop on (i.e. stop on all other failure causes).
Usage
<action application="set" data="fail_on_single_reject=true"/> <action application="bridge" data="sofia/$${profile}/$${kitchen}%$${domain},sofia/$${profile}/$${dining}%$${domain}"/> <action application="javascript" data="answermachine.js"/>
<action application="set" data="fail_on_single_reject=USER_BUSY"/>
<action application="set" data="fail_on_single_reject=!NORMAL_CIRCUIT_CONGESTION"/>
To use a list:
<action application="set" data="fail_on_single_reject=^^:CALL_REJECTED:NORMAL_CLEARING:USER_BUSY"/>
For negated list:
<action application="set" data="fail_on_single_reject=!^^:ALLOTTED_TIMEOUT:NETWORK_OUT_OF_ORDER"/>
For use with the OR operator, consider the following example. Here the dialplan sends a call to multiple gateways simultaneously. In the case of GATEWAY_DOWN
or INVALID_GATEWAY
the bridge should not fail (i.e. negated fail_on_single_reject
) and the dialplan should continue (i.e. continue_on_fail
):
<action application="set" data="continue_on_fail=GATEWAY_DOWN,INVALID_GATEWAY"/> <action application="set" data="fail_on_single_reject=!^^:GATEWAY_DOWN:INVALID_GATEWAY"/> <action application="set" data="hangup_after_bridge=true"/> <action application="bridge" data="sofia/gateway/gw1/$1|sofia/gateway/gw2/$1|sofia/gateway/gw3/$1"/>
failed_xml_cdr_prefix
string If you set that on the A leg and any and all failed B originates generate a full XML CDR report and set it as a variable, this includes during a forked dial.So say you try to call sofia/profile/a@xxxxxxx,sofia/profile/b@xxxxxxx
.
And it fails completely, before you make the call you set failed_xml_cdr_prefix
to "bad_call".
Then you end up with ${bad_call_1}
and ${bad_call_2}
which are each a full XML report including all the vars etc.
Usage
<action application="set" data="failed_xml_cdr_prefix=failinggw" />
failure_causes
string Controls which failure causes will be considered as a failure to the bridge(s). This will change the values for which continue_on_fail will fail by default unlesscontinue_on_fail
is set to true
.Usage
<action application="set" data="failure_causes=USER_BUSY,NO_ANSWER"/>
With Q.850 cause codes:
<action application="set" data="failure_causes=487"/>
fax_bad_rows
stringfax_disable_v17
booleanfax_disable_v17
prevents the use of the V.17 (9,600bps to 14,400bps) FAX modem. This means FAXes will be limited to the use of V.29 (9,600bps and 7,200bps) and V.27ter (4,800bps). Some VoIP systems handle V.17 so poorly there are often good reasons to want to disable the use of this modem.fax_document_total_pages
integerfax_document_transferred_pages
integerfax_ecm_requested
booleanfax_ecm_used
booleanfax_end_page
stringfax_filename
stringfax_force_caller
booleanfax_header
stringfax_ident
stringfax_image_resolution
stringfax_image_size
stringfax_local_station_id
stringfax_prefix
stringfax_remote_station_id
stringfax_result_code
stringResult Code | Message |
0 | OK |
2 | Timed out waiting for initial communication |
3 | Timed out waiting for the first message |
5 | The HDLC carrier did not stop in a timely manner |
6 | Failed to train with any of the compatible modems |
13 | Unexpected message received |
14 | Received bad response to DCS or training |
15 | Received a DCN from remote after sending a page |
17 | Received a DCN while waiting for a DIS |
20 | Received no response to DCS or TCF |
23 | Invalid ECM response received from transmitter |
31 | Timer T2 expired while waiting for fax page |
32 | Timer T2 expired while waiting for next fax page |
48 | Disconnected after permitted retries |
49 | The call dropped prematurely |
fax_result_text
stringfax_start_page
stringfax_success
booleanfax_transfer_rate
stringfax_use_ecm
booleanfax_v17_disabled
booleanfax_verbose
booleanfifo_announce
string If you invokefifo
without providing an announce file as an argument, mod_fifo will fall back to the value of fifo_announce
.fifo_caller_consumer_import
string Import list of variables from the caller to the consumer.Usage
<action application="set" data="fifo_caller_consumer_import=var1,var2"/>
fifo_caller_exit_key
dtmf digit When the caller dials one of the digits you define infifo_caller_exit_key
, they will exit the fifo.fifo_chime_freq
integer The time to wait between playing each chime.fifo_chime_list
string A,
delimited list of files to broadcast while the customer is waiting for someone to answer.fifo_consumer_caller_import
string Import list of variables from the consumer to the caller.Usage
<action application="set" data="fifo_consumer_caller_import=var1,var2"/>
fifo_consumer_exit_key
dtmf digit Whenfifo_consumer_exit_key
is pressed, we hangup on the caller (unless we've put the caller on hold).fifo_consumer_id
string If set, mod_fifo will set the fifo_serviced_by variable to this value when the consumer answers a call from the fifo.fifo_consumer_wrapup_key
dtmf digit If this variable is set and the consumer is inwait
mode, mod_fifo will cause the consumer to reenter the fifo when they press fifo_consumer_wrapup_key
or the fifo_consumer_wrapup_time milliseconds timeout is met.fifo_consumer_wrapup_sound
string Played at the end of a serviced caller when wrapup starts.fifo_consumer_wrapup_time
string A timeout in milliseconds that, when reached, will cause the consumer to reenter the fifo.fifo_hold_music
string The music played to the consumer when they place a caller on hold by pressing0
. It falls back to fifo_music and then the default hold music if fifo_music
is not set.fifo_manual_bridge
boolean readonly mod_fifo sets this variable totrue
when a manually tracking a call.fifo_member_wait
string If this variable is set towait
, the consumer's leg will not hangup when the caller hangs up. This is the default behavior.If set to nowait
, the consumer's leg will hangup when the caller hangs up.
Usage
<action application="set" data="result=${fifo_member(add MyQueueName {fifo_member_wait=nowait}user/1001@VoiceNetwork.ca )"/>
fifo_music
stringfifo_orbit_announce
string This file will be played to the caller before transferring the caller to fifo_orbit_exten.fifo_orbit_context
string Sets the context for fifo_orbit_exten. Must be set prior to placing the caller in the queue.Usage
<action application="set" data="fifo_orbit_context=MyContext"/>
fifo_orbit_exten
stringSyntax: exten:timeout
Set a destination extension and timeout, and it will cause FreeSWITCH to run the caller through the FIFO until the specified timeout, then the caller will get transferred to the destination extension. Can be set before launching the caller into the FIFO.
Usage
Before executing the fifo
application:
<action application="set" data="fifo_orbit_exten=MyFIFOVoicemail:60"/>
Now after 60 seconds of waiting in the FIFO, the caller will be transferred to MyFIFOVoicemail
.
<action application="fifo" data="MyFIFO in"/>
fifo_outbound_announce
string Play this to a member.fifo_override_announce
string Play this announcement to the consumer.fifo_pop_order
string A,
delimited list of priorities to answered from most important to least important.Usage
<action application="set" data="fifo_pop_order=1,2" />
fifo_priority
stringfifo_record_template
string If set, this is the file where the session will record to, expanded on the caller channel.fifo_role
string For reporting purposes, i.e. in the CDRs, the variable will contain "consumer" or "caller" depending upon the call leg.fifo_serviced_by
stringfifo_serviced_uuid
stringfifo_status
string The status of the consumer or caller. UsuallyWAITING
or TALKING
.fifo_strategy
stringfifo_target
stringfifo_timestamp
string Contains the timestamp of when the caller was bridged to the consumer.fire_asr_events
boolean If set, fire an event when speech is detected.See Also
flow_billmsec
integerflow_billsec
integerflow_billusec
integerforce_transfer_context
string When handling transfer/REFER FreeSWITCH normally inherits the context from the original channel. This variable forces the context in which to handle the transfer/REFER.Usage
<action application="bridge" data="{force_transfer_context=some_context}sofia/gateway/gw_name/12345"/>
force_transfer_dialplan
string When handling transfer/REFER FreeSWITCH normally inherits the diaplan from the original channel. This variable forces the dialplan in which to handle the transfer/REFER.funny_stun
stringgrammar_dir
stringgroup_confirm_cancel_timeout
integer If set, cancels leg_timeout after the call is answered. originate_timeout still remains active.When using group confirm, a call passes through three phases:
- Call is ringing.
- Call is answered, waiting to be confirmed.
- Call is confirmed and bridged.
However, if you do
<action application="set" data="group_confirm_cancel_timeout=1"/>
then the timeout will only apply to phase 1. So, once phase 1 is crossed, leg_timeout
counter stops.
group_confirm_file
string This variable is used together withgroup_confirm_key
. In group_confirm_file
, you specify the wav file you want to play when the called party picks up the call. See answer confirmation for more examples.Usage
<action application="set" data="group_confirm_file=/usr/local/freeswitch/sounds/take_call_question.wav" />
group_confirm_key
dtmf digit In thegroup_confirm_key
variable, you define the DTMF that the called party should send to FS to bridge the call. If a wrong DTMF or no DTMF is sent, the called won't be bridged and the wav file will be repeated.Usage
<action application="set" data="group_confirm_key=1" />
group_context
stringtrue
the dialplan will stop processing, and the A leg will be terminated when the B leg terminates. If false
(default) the dialplan continues to be processed after the B leg terminates. This is checked after park_after_bridge
and transfer_after_bridge
.The default value is false
Usage
<action application="set" data="hangup_after_bridge=true"/>
hangup_after_conference
boolean Controls what happens to a calling (A) party when in a conference and the conference ends (e.g. endconf flag set and moderator leaves). Iftrue
(default) the dialplan will stop processing and the A leg will be terminated. If false
the dialplan continues to be processed after the end of conference.Usage
<action application="set" data="hangup_after_conference=false"/>
<!-- all regular memebers who dial "3500" will continue to the echo action after the "endconf" member below leaves conference --> <!-- note that "hangup_after_true" is depenent on "endconf", one members (or more) must have endconf flag --> <!-- if two or more managers join, call, participants will be kicked after laster member with "endconf" flag leaves --> <!-- When a person calls into "3500-admin" and leaves, the partipants who came in via "3500" will continue to thier own echo app --> <extension name="cdquality_conferences"> <condition field="destination_number" expression="^(35\d{2})$"> <action application="answer"/> <action application="set" data="hangup_after_conference=false"/> <action application="conference" data="$1-${domain_name}@video-mcu-stereo"/> <action application="set" data="echo_encode_video=true"/> <action application="echo"/> </condition> </extension> <extension name="conference manager"> <condition field="destination_number" expression="^(35\d{2})-admin$"> <action application="set" data="conference_member_flags=endconf"/> <action application="conference" data="$1-${domain_name}@video-mcu-stereo"/> </condition> </extension>
hangup_cause
string This is set to the hangup cause of the A leg of the call (note that as such it doesn't make much sense before the end of the call). Often this will take the hangup cause from the B leg of the call, if there is one. For a list of hangup causes, see Hangup Causes.Usage
<action application="log" data="1 A-leg hangup cause: ${hangup_cause}"/>
hangup_cause_q850
string This is set to the Q850 numeric code of the hangup cause of the A leg of the call (note that as such it doesn't make much sense before the end of the call). Often this will take the hangup cause from the B leg of the call, if there is one. For a list of hangup causes, see Hangup Causes.Usage
<action application="log" data="1 A-leg hangup Q850 cause: ${hangup_cause_q850}"/>
has_t38
boolean
hold_hangup_xfer_exten
string Controls what happens to a calling (A) party when in a bridge state and the bridge ends while the called (B) party is on hold. If not set on leg B (ie. the default), then A leg is hung up. If it is set on leg B, then leg A is transferred to the given extension, as per transfer_after_bridge.Usage
<action application="set" data="hold_hangup_xfer_exten=1000:XML:default"/>
hold_music
string Per-channel hold music. Supports all audio formats and audio streams. Thehold_music
variable can also be set globally in vars.xml
.Usage
<action application="set" data="hold_music=/sounds/holdmusic.wav" />
<action application="set" data="hold_music=silence" />
You can also use phrase:
to indicate to use a phrase instead of a specific file:
<action application="set" data="hold_music=phrase:my_hold_music" />
You can also set your hold_music
to the special value indicate_hold
instead of a music source and it will pass the hold req through but not the SDP:
<action application="set" data="hold_music=indicate_hold" />
For multi-tenant environment, if you want to have a separate MOH for the phone with hold button (like Polycom) that utilizes RE-INVITE with no media ip addr (0.0.0.0) for hold, you can override the hold-music values in the sip profile parameter similar to the following example:
<action application="bridge_export" data="hold_music=$${sounds_dir}/music/company-a.mp3"/>
holding_uuid
stringhostname
string This global variable is set dynamically by the FreeSWITCH core and is set to the host name of the server on which FreeSWITCH is running. You cannot override the value of this variable by setting it. However if you change the host name of the server the value of the variable will be updated.htdocs_dir
stringid
stringignore_display_updates
string Tells freeswitch not to send display UPDATEs to the leg of the call. (update_display)Usage
From dialplan/default.xml
, to set on A-Leg:
<action application="set" data="ignore_display_updates=true"/>
To set on B-Leg:
<action application="bridge" data="{ignore_display_updates=true}sofia/gateway/provider/18005551212"/>
ignore_early_media
string Controls if the call returns on early media or not. Default isfalse
.Usage
<action application="set" data="ignore_early_media=true"/>
You may also specify a value for ignore_early_media
in the argument to the bridge application, using the { }
syntax. (ignore_early_media
may not be specified on a per-leg basis, using the [ ]
syntax, as it specifically is a global variable to the originate session):
<action application="bridge" data="{ignore_early_media=true}sofia/test-int/1001@somebox,sofia/test-int/1000@somehost"/>
Setting the value to ring_ready
will work the same as ignore_early_media=true
but also send a SIP 180 to the inbound leg when the first SIP 183 is caught.
<action application="set" data="ignore_early_media=ring_ready"/>
import
string The import variable, when used before a bridge, imports the variables of the other channel on the actual channel. Implemented by mod_lcr.Usage
<action application="set" data="import=this_is_a_variable_name"/>
inbound_dialplan
stringinherit_codec
boolean If late negotiation is on, and you set inherit_codec=true on the A leg, the negotiated codec of the B leg will be forced onto the A leg.Usage
<action application="set" data="inherit_codec=true"/>
initial_callee_id_name
string Sets the callee id name during the 183. This allows the phone to see the name of the called party prior to the phone being answered.Usage
An example of setting this to the caller id name of the number being dialed:
<action application="set" data="initial_callee_id_name='${user_data(${dialed_extension}@${domain_name} var effective_caller_id_name)}'"/>
instant_ringback
boolean When set, ringback will not wait for indication before sending ringback tone to calling party.Usage
this may cause undesirable effects, like ringing for 3 seconds that turns into a busy signal.
<action application="set" data="instant_ringback=true"/>
intercept_unanswered_only
boolean If set totrue
, the leg will only be intercepted if the channel is not answered.Default: false
Usage
<action application="set" data="intercept_unanswered_only=true"/> <action application="intercept" data="myUUID"/>
intercept_unbridged_only
boolean If set to true, the leg will only be mod_dptools: intercept if the channel is not bridged to anyone.Default: false
Usage
<action application="set" data="intercept_unbridged_only=true"/> <action application="intercept" data="myUUID"/>
ip_invite_params
stringis_outbound
booleanivr_menu_status
stringivr_menu_status
is a channel variable that returns the status of the IVR menu:success
failure
timeout
ivr_menu_terminator
dtmf digit You can set to none or the dtmf chars you want to terminate input.Usage
<action application="set" data="ivr_menu_terminator=#"/>
jitterbuffer_msec
string Activates the jitter buffer. The jitter buffer has three params:length
, max length
, and max drift
.Usage
<action application="set" data="jitterbuffer_msec=60:200:20"/> <action application="answer"/>
Or to set it on the subsequent outbound call: export sets a variable on both the current channel and on any channels it creates, the nolocal:
disables setting it on the current channel and only sets it on the subsequent outbound channels.
<action application="export" data="nolocal:jitterbuffer_msec=60"/> <action application="bridge" data="sofia/default/888@conference.freeswitch.org"/>
You can also activate the jitter buffer in the bridge as follows:
<action application="bridge" data="{jitterbuffer_msec=60}sofia/gateway/$1@gateway.com"/>
This will add a jitter buffer to packets flowing from a remote gateway towards a local freeswitch user. The network would look like this:
(local sip user) -----> FreeSWITCH -----> (remote gateway)
Where the link between the freeswitch and the remote gateway has a bad, jitter causing connection, and say the local sip user has no jitter buffering on their IP-phone. This will help the voice quality for the incoming audio.
language
stringlast_app
stringlast_arg
stringlast_bridge_hangup_cause
string This is set to the hangup cause of the last bridged B leg of the call. For a list of hangup causes, see Hangup Causes.Usage
<action application="log" data="B-leg hangup cause: ${last_bridge_hangup_cause}"/>
last_bridge_proto_specific_hangup_cause
string This shows the last bridge hangup cause by SIP response code, e.g. "sip:404"last_bridge_to
stringlast_dtmf_duration
stringlast_file_position
string deprecated This is possibly deprecated.last_matching_digits
string Contains the last set of digits that the user dialed when using the "dmachine" digit-handling. This is most commonly used with the bind_digit_action dialplan application.mod_dptools: bind_digit_action
?Usage
<action application="log" data="INFO User just dialed ${last_matching_digits}"/>
last_transferred_conference
string readonly Contains the name of the last conference that this channel was connected to.Usage
<action application="log" data="INFO Last conference this person visited was [${last_transferred_conference}]"/>
lcr_auto_route
stringlcr_route_count
integerleft_hanging_extension
stringleg_delay_start
string Specifies a wait time in seconds before each leg is called in a forked dial scenario. Can be used in per-leg[]
, but not in global {}
for the dialstring.Usage
<action application="bridge" data="sofia/profile/dest1,[leg_delay_start=10]sofia/profile/dest2,[leg_delay_start=15]sofia/profile/dest3"/>
leg_progress_timeout
stringUsage
Make all bridged calls fail over to the next in 6 seconds:
<action application="export" data="leg_progress_timeout=6"/>
leg_timeout
integer Timeout for each leg in an originate dialstring. Can be used in per-leg[]
, but not in global {}
for the dialstring. For global, use originate_timeout.You can also use leg_progress_timeout to specify the maximum time we will wait before we get media (whether it's early media, ringing or answer), allowing you to avoid going to voicemail for a particular line.
If you are using group confirm then you can cancel the timeout by using the group_confirm_cancel_timeout channel variable. If leg_delay_start is also used, leg_timeout
will not start the timeout counter until after the extension starts to be bridged to.
Usage
<action application="bridge" data="[leg_timeout=15]user/hastoanswerquickly/some.domain.com,[leg_timeout=60]user/hasaminutetoanswer@some.domain.com"/>
limit_id
stringlimit_ignore_transfer
stringlimit_max
stringlimit_rate
stringlimit_realm
stringlimit_usage
stringlocal_ip_v4
string
This global variable is set dynamically by the FreeSWITCH core by asking the underlying OS for the IP address of the server on which FreeSWITCH is running. If the server has multiple IP addresses this will be set to the first one returned by the OS. In the default configuration there are many settings that use this global variable.
You cannot override the value of this global variable, because it will be reset by the FreeSWITCH core every minute. If your server has multiple IP addresses and you want to force FreeSWITCH to use a particular IP address, you can create a global variable force_local_ip_v4
and set it to the IP address you prefer. You must also set the local_ip_v4 variable to this IP address, you can do it by simply setting local_ip_v4 to use the value of force_local_ip_v4
<X-PRE-PROCESS cmd="set" data="force_local_ip_v4=1.1.1.1"/> <X-PRE-PROCESS cmd="set" data="local_ip_v4=$${force_local_ip_v4 }"/>
FreeSWITCH will not validate that the IP address you entered for force_local_ip_v4
is actually pointing to the server, it's up to you to ensure that you use a valid IP address that's routed correctly to the server.
local_ip_v6
string
This global variable is set dynamically by the FreeSWITCH core by asking the underlying OS for the IPv6 address of the server on which FreeSWITCH is running (if it supports IPv6). If the server has multiple IPv6 addresses this will be set to the first one returned by the OS. In the default configuration this variable is used for setting up IPv6 SIP and Verto Profiles.
You cannot override the value of this global variable, because it will be reset by the FreeSWITCH core every minute. If your server has multiple IPv6 addresses and you want to force FreeSWITCH to use a particular IPv6 address, you can create a global variable force_local_ip_v6 and set it to the IP address you prefer. You must also set the local_ip_v6 variable to this IP address, you can do it by simply setting local_ip_v6 to use the value of force_local_ip_v6.
<X-PRE-PROCESS cmd="set" data="force_local_ip_v4=1.1.1.1"/> <X-PRE-PROCESS cmd="set" data="local_ip_v4=$${force_local_ip_v4 }"/>
FreeSWITCH will not validate that the IPv6 address you entered for force_local_ip_v6
is actually pointing to the server, it's up to you to ensure that you use a valid IP address that's routed correctly to the server.
local_mask_v4
This global variable is set dynamically by the FreeSWITCH core by using the network mask received from the underlying OS when determining the local_ip_v4.
local_media_ip
stringlocal_media_port
stringlocal_video_ip
stringlocal_video_port
stringlog_dir
stringloopback_bowout_on_execute
boolean Set totrue
to have one-legged loopback channels "bow out" (remove the loopback legs) of the call.loopback_bowout_on_execute
is only useful to single leg calls. You never have to set it: loopback_bowout
is true
by default. It tries to remove loopback by doing uuid_bridge.
When setting loopback_bowout=false
, a bridged loopback call results in 4 legs (a-leg, loopback-a, loopback-b, b-leg).
When setting loopback_bowout=true
, a bridged loopback call results in 2 legs (a-leg, b-leg).
During the call setup phase even with loopback_bowout=true
there will always be 4 legs, however. loopback-a and loopback-b will be destroyed when a-leg and b-leg are successfully bridged.
Usage
<action application="set" data="loopback_bowout_on_execute=true"/>
loopback_export
string A list of channel variables to pass from loopback-a to loopback-b.loopback_leg
stringmax_forwards
integer Contains the currentMax-Forwards
value provided in the originating request. The Max-Forwards
value is decremented by one for each hop in a SIP call, when the Max-Forwards
value is depleted the receiving agent must not pass the call onwards.The max_forwards
variable may be set on an outbound channel, some providers such as BT IP Exchange insist on a minimum value to faithfully terminate the call, 50 in BT's case.
If the
max_forwards
value is reset it can cause potential cyclic calls between two operators who loop calls back to each other in error. Use wisely.
Usage
Bridge an incoming call to a provider requiring a minimum Max-Forwards
value:
<action application="bridge" data="{max_forwards=65}sofia/gateway/ipexchange/442920180123"/>
mduration
stringmedia_bug_answer_req
boolean Start recording only when the channel has been answered.Usage
<action application="set" data="media_bug_answer_req=true"/>
media_mix_inbound_outbound_codecs
boolean Set which list of codecs is offered to the B-leg.FreeSWITCH used to take the codecs from the inbound A-leg and offer them out to the B-leg mixed with the configured list of outbound codecs. With large lists of codecs this can exceed the MTU of the UDP message and cause call setup failures.
As of
-
FS-8321Getting issue details...
STATUS
the old behavior now requires the variable media_mix_inbound_outbound_codecs=true
as the new default behavior is to offer the exact same codecs on the outbound B-leg that were offered on the inbound A-leg.
Usage
<action application="set" data="media_mix_inbound_outbound_codecs=true"/>
media_webrtc
boolean Used to instruct FS to generate an INVITE for a WebRTC call. For example, in case you need to originate a WebRTC call but you are not calling a SIP UA that is registered with FS (if the UA is registered with FS, FS knows it should originate a WebRTC call).Usage
{media_webrtc=true}
memory_debug
booleanmin_dup_digit_spacing_ms
integer Duplicate inband DTMF that starts sooner than this time will be ignored. That is, this is the minimum gap from the end of the first digit and the start of the repeated digit required for two digits to be detected. This value is0
by default. Set this variable prior to executing spandsp_start_dtmf.Usage
<action application="set" data="min_dup_digit_spacing_ms=40"/> <action application="spandsp_start_dtmf" />
mod_dir
stringmonitor_early_media_fail
string Monitors early media for failure conditions, such as a busy signal. This allows faster processing of failed calls when ignoring early media.The syntax is a series of !
delimited early media conditions in the following format:
condition_name:number_of_hits:tone_detect_frequencies
condition_name | user defined name for the error condition |
number_of_hits | the number of times the tone must be heard before considering it a fail |
tone_detect_frequencies | the frequencies to listen for (delimited by + instead of ,). See tone_detect |
this variable only works when
ignore_early_media
is set to true.
Usage
<action application="bridge" data="{ignore_early_media=true,monitor_early_media_fail=user_busy:2:480+620!destination_out_of_order:2:1776.7}sofia/dial/string"/>
monitor_early_media_ring
string Monitors early media for a user-specific ring tone. Each time the tone is heard, the switch will increment an internal counter for that leg. Once the counter reachesmonitor_early_media_ring_total
(or this variable has not been set) then the early media will be sent.The syntax is a series of !
delimited early media conditions in the following format:
condition_name:number_of_hits:tone_detect_frequencies
condition_name | user defined name for the error condition |
number_of_hits | the number of times the tone must be heard before considering it a fail |
tone_detect_frequencies | the frequencies to listen for (delimited by |
this variable only works when
ignore_early_media
is set to true.
Usage
<action application="bridge" data="{monitor_early_media_ring_total=3,monitor_early_media_ring=usring:1:440.0+480.0!ukring:2:400+450}sofia/gateway/yourgateway/1239@conference.freeswitch.org"/>
monitor_early_media_ring_total
string Specifies the number of user defined ring tones that can be heard before failing. To be used with monitor_early_media_ring.Usage
<action application="bridge" data="{ignore_early_media=true,monitor_early_media_ring_total=3,monitor_early_media_ring=us_ring:1:440.0+480.0}sofia/dial/string"/>
monitor_fail_dispo
string This variable can be used to provide a custom originate_disposition as the result of an early media failure using monitor_early_media_fail or monitor_early_media_ring. If this variable is not set, a default value ofmonitor_early_media_fail
or monitor_early_media_ring
will be placed in originate_disposition
.Usage
<action application="bridge" data="{ignore_early_media=true,monitor_fail_dispo=strange_bleep_attack,monitor_early_media_fail=user_busy:2:1234}sofia/dial/string"/>
monitor_ring_dispo
stringmyid
stringnat_private_addr
stringIf you use auto-nat and a public IP address was detected, this variable will be set with the private IP address to which the detected public IP address is mapped.
nat_public_addr
stringIf you use auto-nat and FreeSWITCH was able to identify the public IP address pointing to your server, this variable will be set with the auto detected public IP address.
nat_type
string
If you use auto-nat FreeSWITCH will set this global variable to the type of auto nat device it detected this can be either pmp or upnp.
NDLB_support_asterisk_missing_srtp_auth
booleannew_name
stringno_throttle_limits
boolean You set this variable totrue
on your outbound calls to have them not count in spsUsage
{no_throttle_limits=true}
nonexistantvar
stringoriginal_caller_id_name
stringoriginal_caller_id_number
stringoriginal_destination_number
stringoriginate_continue_on_timeout
boolean Controls whether or not a bridge should continue after timing out. This variable resets the timeout after each|
. Default is false
: die on first timeout.Usage
<action application="set" data="originate_continue_on_timeout=true"/>
originate_delay_start
integer You can specify a wait time in milliseconds before origination. This variable can be used in Enterprise originate where the variable leg_delay_start cannot be used.Usage
<action application="bridge" data="sofia/profile/dest1:_:{originate_delay_start=10000}sofia/profile/dest2:_:{originate_delay_start=15000}sofia/profile/dest3"/>
A more complex example with breakdown and timeline (seconds in brackets):
<action application="bridge","users/1000:_:{originate_delay_start=8000}user/2302:_:{originate_delay_start=14000}sofia/gateway/flowroute/1231231234"/>
Assuming all users just let it ring:
[00] - user 1000 rings [10] - user 2302 rings [15] - user 1231231234 rings
Assuming user 1000 declines after 2 seconds, other users ring:
[00] - user 1000 rings [08] - user 2302 rings [14] - user 1231231234 rings
originate_disposition
string readonly This is the originate disposition or hangup cause that is returned. (LEG B)The value is updated after every bridge attempt, if the bridge is not successful.
originate_retries
integer Number of retries before giving up on originating a call (default is 0).originate_retry_sleep_ms
integer This will set how long FreeSWITCH is going to wait between sending invite messages to the receiving gateway.Usage
Wait 500ms between sending invite messages to the called gateway:
<action application="set" data="originate_retry_sleep_ms=500"/>
originate_timeout
integer Determines how long FreeSWITCH is going to wait for a response from the invite message sent to the gateway. In effect, it is a way to control the timeout for a bridge/originate consisting of multiple endpoints.Default Value: 60
Usage
Useful if you are using multiple gateways. In this example, FreeSWITCH will wait 2 seconds for 192.168.1.4
to respond to the invite message before trying the next gateway:
<action application="set" data="originate_timeout=2"/> <action application="bridge" data="sofia/default/$1@192.168.1.4|sofia/default/$1@192.168.1.5"/>
<action application="bridge" data="{originate_timeout=10}[leg_timeout=5]sofia/default/foo1@bar1|[leg_timeout=5]sofia/default/foo2@bar2"/>
<action application="bridge" data="{originate_timeout=24}${group_call(sales@$${domain})}"/>
originating_leg_uuid
string Shows the UUID of the originating leg on an outbound channel.Usage
In A-leg CDR:
<uuid>cb5f5b90-75a0-11e0-873b-d1cba9e0f1b8</uuid> <call_uuid>cb5f5b90-75a0-11e0-873b-d1cba9e0f1b8</call_uuid>
In B-leg CDR:
Note that the leg UUIDs are different. The
call_uuid
matches the two legs together, but the originating_leg_uuid
can do so as well.
<uuid>cb8633aa-75a0-11e0-873d-d1cba9e0f1b8</uuid> <call_uuid>cb5f5b90-75a0-11e0-873b-d1cba9e0f1b8</call_uuid> <originating_leg_uuid>cb5f5b90-75a0-11e0-873b-d1cba9e0f1b8</originating_leg_uuid>
origination_callee_id_name
string Set on the inbound leg to control what caller ID name appears in the caller phone's display. Also seeignore_diplay_updates
which affect the processing of these variables.Usage
If
set
doesn't work, try using export
instead.
<action application="bridge" data="{origination_callee_id_name=Reginald}sofia/gateway/provider/<Reginald's cellphone number>" />
origination_callee_id_number
string Set on the inbound leg to control what caller ID number appears in the caller phone's display. Also see ignore_diplay_updates which affect the processing of these variables.Usage
<action application="bridge" data="{origination_callee_id_name=Reginald,origination_callee_id_number=2332}sofia/gateway/provider/<Reginald's cellphone number>" />
origination_caller_id_name
string Sets the origination callerid name (LEG A).If you want to set the Caller ID on an origination call you should add this inside the {}
brackets before the dialstring.
Usage
<action application="set" data="origination_caller_id_name=Uncle Sam"/>
origination_caller_id_number
string Sets the origination callerid number. (LEG A)If you want to set the Caller ID on an origination call you should add this inside the {}
brackets before the dialstring.
Usage
if you want to relay the Caller ID Number of an incoming PSTN call via FXO gateway, comment out this variable.
<action application="set" data="origination_caller_id_number=9185551212"/>
origination_cancel_key
dtmf digit Used with attended transfer function. Allows you to set a DTMF key that will cancel the att_xfer and re-connect to the call on hold. It'll also cancel a bridge that hasn't been bridged as yet (and thus can't be terminated with a bridge_terminate_key). Implemented in revision 14650.Usage
<action application="set" data="origination_cancel_key=#"/>
origination_channel_name
string Set this in the{}
when doing an originate to create a custom channel name.Usage
originate {origination_channel_name='this_is_my_channel_name'}loopback/9664 9195
origination_nested_vars
stringorigination_privacy
string Sets privacy profile for caller.Options:
screen
hide_name
hide_number
Usage
<action application="set" data="origination_privacy=hide_name"/>
origination_uuid
string You can specify the uuid of an originated call usingorigination_uuid
. This way you can hang up the call before it is answered, since you know the uuid. Just remember you need to use the create_uuid
command to generate the uuid as 2 calls with the same uuid == bad! Bridge also uses the origination syntax so you can also pre-allocate the UUID for the new channel resulting from a bridge by using the
{}
/[]
syntax and specifying origination_uuid
there, too.
Usage
originate [origination_uuid=....]sofia/<profile>/<extension>
originator
string Holds the UUID of the channel that originated the call. It's used to notify a parent channel that the state of its child has changed, hence interrupting any blocking reads on the parent. It's automatically set and read by FreeSWITCH internals. Usually, the user won't want to set it.originator_codec
string Sets the codec for calls originated from LEG A (setting the codec for LEG B)Usage
<action application="set" data="originator_codec=PCMU"/>
originator_video_codec
stringother_loopback_leg_uuid
stringoutbound_redirect_fatal
boolean When doing a simultaneous call to multiple endpoints, a 302 redirect can cause all the endpoints to stop ringing and the call will follow the redirect. When this channel variable is set it causes an endpoint that sends back a 302 redirect to be removed from the call list and the other endpoints continue to ring.Usage
<action application="bridge" data="{outbound_redirect_fatal=true}${group_call(sales@$${domain})}"/>
pa_hold_file
stringpa_ring_file
stringpark_after_bridge
boolean If set totrue
, it will park the call after bridge returns. This is checked before transfer_after_bridge and hangup_after_bridge.Usage
<action application="set" data="park_after_bridge=true"/> <action application="bridge" data="sofia/gateway/myprovider/5551231234"/>
park_timeout
string When set, a parked call will disconnect after the timeout has occurred. Timeout is specified in seconds. If nopark_timeout
value is set then the parked call will be held indefinitely or until it is removed with a uuid_transfer.Usage
<action application="set" data="park_timeout=30"/> <action application="park"/>
You can also specify which hangup_cause you need when the channel is disconnected by park_timeout
.
<action application="set" data="park_timeout=30:MEDIA_TIMEOUT"/>
passthru_ptime_mismatch
boolean Ifptime
from leg A and leg B don't match and if mod_com_g729 is used, the call would normally use the codec to re-packetize the RTP stream.With this parameter, mod_com_g729 will re-packetize without decoding/encoding, as mod_g729 would do.
Usage
This has to be set in {}
before bridging. That will probably not work if set using export
before bridging.
<action application="bridge" data="{passthru_ptime_mismatch=true}sofia/gateway/trunk/$1"/>
Globally in vars.xml
<X-PRE-PROCESS cmd="set" data="passthru_ptime_mismatch=true"/>
playback_delimiter
stringmod_dptools: file_string
internally.Usage
Setting playback_delimiter
to the following:
<action application="set" data="playback_delimiter=&"/>
Permits the streaming of files foo.wav
and bar.wav
one right after the other:
<action application="playback" data="foo.wav&bar.wav"/>
playback_last_offset_pos
string Contains the file offset of the file that just played back. This can be used to resume playback at that position at a later time.playback_ms
integer Contains the number of milliseconds of the length of the audio file just played back. There is also a variable playback_seconds which stores the length in whole seconds.playback_samples
integer Contains the number of samples in the audio file just played back.playback_sleep_val
integer How long to pause after a file is played. Default is 250 milliseconds.Usage
To play a list of short files one right after the other, with no pause in between:
<action application="set" data="playback_sleep_val=0"/>
playback_terminator_used
string Contains the digit that the caller used to terminate a playback. Is undefined when a new playback is called.playback_terminators
dtmf digit0. About
Allows you to set which DTMF tones will terminate
- playback (see mod_dptools:playback or mod_dptools:play_and_detect_speech for example), or
- recording (see
uuid_record
inmod_commands
(i.e., the FreeSWITCH API commands),mod_dptools:record
, andmod_dptools:record_session
).
The default terminator is *
(star).
1. Syntax
playback_terminators=123456789*0# | any | none
none
- undefines the terminator digit, meaning no DTMF tone will interrupt playbackany
- any DTMF will interrupt playback
Digits not specified as terminators will be collected, but won't interrupt playback.
2. Modifiers
+
(plus) - includes the following terminator digit along with the other DTMF digits in the returned stringx
(letter ex) - includes the following terminator digit in the returned string and also returnsSWITCH_STATUS_RESTART
See last example below on what these modifiers do.
TODO Add use cases.
3. Examples
Make either *
(star) or #
(bar/pound/square) interrupt the subsequent playback, tone_stream
, say
, recording, etc. operation:
<action application="set" data="playback_terminators=#*"/>
If DTMF 9 is dialed during playback, it will interrupt playback and return the digit 9 along with any other dialed digits; if *
is dialed it will only interrupt playback without being included in the DTMF string returned:
<action application="set" data="playback_terminators=*+9"/>
playback_timeout_sec
integer Set timeout for playback. This is very useful if you want to play short excerpts of a file that could be very long.Usage
<action application="set" data="playback_timeout_sec=10"/>
pound_replace
stringpresence_data_cols
string You can customize the fields in FreeSWITCH's internal channels table by using the global variablepresence_data_cols
.Use :
to separate the column names in presence_data_cols
You must define the field in the channels
table first:
ALTER TABLE channels ADD COLUMN accountcode VARCHAR(256)
Usage
In conf/vars.xml
:
<X-PRE-PROCESS cmd="set" data="presence_data_cols=accountcode:domain_name"/>
presence_id
string Will instruct mod_sofia to invoke aPRESENCE_IN
event that will assert the BLF lamp for the subscribed entity. This only lasts while the channel still exists so it should not be used for persistent status (i.e. a user that is DND, or an agent logged into a queue).Usage
<action application="set" data="presence_id=${dialed_extension}@${domain_name}"/>
process_cdr
string Indicates how to process call detail records.Options:
false
- do not process the recordtrue
- process records for both legs. This is the default.a_only
- only process records on the a legb_only
- only process records on the b leg
This variable is unconditionally exported.
Usage
<action application="set" data="process_cdr=a_only"/>
profile_created_time
integer Contains the start time (in microseconds) of when the call profile was created.Usage
In the event that a call is transferred, this is the effective created_time
for that transfer. For example, if you did this call flow:
2000 > 2001 (created_time=1357138714 / profile_created_time=1357138714) transfer to 2002 (created_time=1357138714 / profile_created_time=1357138752) transfer to 2003 (created_time=1357138714 / profile_created_time=1357138766) transfer to 2004 (created_time=1357138714 / profile_created_time=1357138784)
You would still use progress_time to retrieve the progress start time, no matter if it's a transfer leg or not.
profile_start_epoch
integerprofile_start_stamp
stringprofile_start_uepoch
integerprogress_epoch
integerprogress_media_epoch
integerprogress_media_stamp
stringprogress_media_uepoch
integerprogress_mediamsec
integerprogress_mediasec
integerprogress_mediausec
integerprogress_stamp
stringprogress_time
stringprogress_timeout
integer This is the maximum time we will wait before we get media (whether it's early media, ringing or answer) e.g. maximum PDD before abandoning the route -- the time from Sending the INVITE to receiving the first ringing response for example: a SIP/2.0 180 Ringing or 183. Typical fixed lines have a PDD of under 3 seconds, and mobiles of under 8 seconds.I set my progress_timeout to 13 seconds to accommodate for slow-setup mobile connections, however, it can probably be shorter. -- Avi Marcus
Two scenarios:
- If a carrier is having issues with their platform, all calls might timeout.
- If it's not a carrier issue -- if a single carrier timed out at 13 seconds and the user actually waited, the call rarely connected via any other carrier (although they all expired at 13 seconds).
See also: Early Media
Usage
<action application="set" data="progress_timeout=20"/>
progress_uepoch
integerprogressmsec
integerprogresssec
integerprogressusec
integerproto_specific_hangup_cause
string This variable will cause FreeSWITCH to force the SIP response code to a specific setting when hanging up a call. The example below is one where all possible extensions have been tested and failed and you want FreeSWITCH to generate and respond with a specific code. (This is not a passthrough example).By the way, you'll be unable to rewrite the hangup cause for a bridge that gets a 180 or 183 packet from the gateway before getting a 4xx, 5xx or 6xx packet (because those bridges don't 'fail'). This happens with SIP providers that give a 183 Session Progress before a 404 Not Found if the PSTN number dialed doesn't exist.
Usage
<extension name="nothing_left" continue="true"> <condition break="always"> <action application="set" data="proto_specific_hangup_cause=sip:503"/> <action application="hangup"/> </condition> </extension>
Example SIP Response Map
<extension name="from_gw_to_internal"> <condition field="destination_number" expression="^(.*)$"> <action application="set" data="hangup_after_bridge=true"/> <action application="set" data="continue_on_fail=19"/> <action application="bridge" data="{sip_cid_type=none}sofia/gateway/gw/$1"/> <action application="transfer" data="480to503"/> </condition> </extension> <extension name="480to503"> <condition field="${proto_specific_hangup_cause}" expression="sip:480"> <action application="set" data="sip_ignore_remote_cause=true"/> <action application="respond" data="503"/> <action application="hangup" data="NORMAL_CIRCUIT_CONGESTION"/> </condition> </extension>
proxy_media
boolean Proxy Media mode puts Freeswitch in a "transparent proxy mode" for the RTP streams. The RTP streams still pass through freeswitch (unlike bypass media mode), however it is lighter on the CPU because freeswitch never even parses the packets or processes them in any way, it simply forwards them onwards.See also: Proxy Media
Usage
Late Negotiation () must be enabled in sip profile for this to work in the dialplan.
<action application="set" data="proxy_media=true"/>
rdnis
stringread_codec
string readonly The negotiated codec of the inbound call leg.read_rate
stringread_result
stringread_terminator_used
dtmf digit Contains the digit that the caller used to terminate a playback.RECORD_APPEND
boolean Recording is appended to file. SetRECORD_APPEND=true
on the channel and all recordings will behave this way to formats which support it (curently mod_sndfile for WAV, etc.)Usage
<action application="set" data="RECORD_APPEND=true"/>
RECORD_ARTIST
string Set prior to performing a record to store in the file header meta data (provided the file format supports meta headers).Usage
<action application="set" data="RECORD_ARTIST=Unknown"/>
RECORD_COMMENT
string Set prior to performing a record to store in the file header meta data (provided the file format supports meta headers).Usage
<action application="set" data="RECORD_COMMENT=This is a blog spot"/>
RECORD_COPYRIGHT
string Set prior to performing a record to store in the file header meta data (provided the file format supports meta headers).Usage
<action application="set" data="RECORD_COPYRIGHT=(c)2007-me"/>
RECORD_DATE
string Set prior to performing a record to store in the file header meta data (provided the file format supports meta headers).Usage
<action application="set" data="RECORD_DATE=${strftime(%Y-%m-%d %H:%M)}"/>
RECORD_DISCARDED
string readonly If a recording gets dropped or discarded then this channel variable is set totrue
. Useful for diagnostics.record_fill_cng
stringUsage
<action application="set" data="record_fill_cng=1200"/>
RECORD_HANGUP_ON_ERROR
boolean When set totrue
this channel variable will cause the call to hangup if there is an error when trying to record the call. This is not a common feature, however in cases where a call MUST be recorded it makes it impossible to have calls that are not recorded. (Useful in some business scenarios.)Usage
<action application="set" data="RECORD_HANGUP_ON_ERROR=true"/>
RECORD_MIN_SEC
integer Sets the minimum recording length. Normally a recording must be at least 3 seconds long. If a recording does not meet the minimum length, it is deleted after being recorded.Usage
<action application="set" data="RECORD_MIN_SEC=0"/>
record_ms
integer readonly Contains the length in milliseconds of the most recent recording.record_post_process_exec_api
string Executes an API for the purpose of postprocessing recorded audio. These two variables allow the postprocessing of recorded audio. The reason this is required is if the A leg hangs up first in a call, the dialplan stops being processed, and then you aren't able to take action on the file that was recorded.Usage
<action application="set" data="record_post_process_exec_api=api_here:api_arg1 api_arg2 api_arg3" />
record_post_process_exec_app
string Executes an app for the purpose of postprocessing recorded audio. The reason this is required is if the A leg hangs up first in a call, the dialplan stops being processed, and then you aren't able to take action on the file that was recorded.Usage
<action application="set" data="record_post_process_exec_app=lua::vm_test.lua" />
RECORD_READ_ONLY
boolean Record read stream only.Usage
From the perspective of FreeSWITCH looking toward the endpoint
Aleg is recording, and only incoming audio read from the channel goes into file
<action application="set" data="RECORD_READ_ONLY=true"/>
or Bleg is recording, and only incoming audio read from the channel goes into file
<action application="bridge" data="{RECORD_READ_ONLY=true}user/1000"/>
See Also:
record_restart_limit_on_dtmf
boolean When set to true it allows the person recording to press a DTMF key and extend the amount of time they have before the recording times out.Usage
<action application="set" data="record_restart_limit_on_dtmf=true"/>
record_sample_rate
integer Set the sample rate of the recording.Usage
<action application="set" data="record_sample_rate=8000"/>
TODO https://github.com/signalwire/freeswitch/blob/master/src/mod/applications/mod_dptools/mod_dptools.c refers to channel variable record_rate
but that is the entire occurrence in the entire code base; is that an error?
RECORD_SOFTWARE
string Set prior to performing a record to store in the file header meta data (provided the file format supports meta headers).Usage
<action application="set" data="RECORD_SOFTWARE=FreeSWITCH"/>
RECORD_STEREO
boolean Record leg A and leg B streams (i.e. the caller is recorded to the left channel and the reciever is recorded on right channel) into different channel in a stereo file.Usage
<action application="set" data="RECORD_STEREO=true"/>
RECORD_STEREO_SWAP
boolean Allow to invert the recording channel when RECORD_STEREO variable is set totrue
. So the caller is recorded to the right channel and the receiver is recorded on left channel.RECORD_TITLE
string Set prior to performing a record to store in the file header meta data (provided the file format supports meta headers).Usage
<action application="set" data="RECORD_TITLE=Recording ${destination_number} ${caller_id_number} ${strftime(%Y-%m-%d %H:%M)}"/>
record_waste_resources
string By default record doesn't send RTP packets. This is generally acceptable, but for longer recordings or depending on the RTP timer of your gateway, your channel may hangup with cause MEDIA_TIMEOUT. Setting this variable will 'waste' bandwidth by sending RTP even during recording. The value can betrue
, false
, or [desired silence factor]
. By default the silence factor is 1400 if you set record_waste_resources=true
.Usage
<action application="set" data="record_waste_resources=true"/>
<action application="set" data="record_waste_resources=1300"/>
RECORD_WRITE_ONLY
boolean Record write stream only.
Usage
From the perspective of FreeSWITCH looking toward the endpoint
Aleg is recording, and only outgoing audio written to the channel goes into file
<action application="set" data="RECORD_WRITE_ONLY=true"/>
or Bleg is recording, and only outgoing audio written to the channel goes into file
<action application="bridge" data="{RECORD_WRITE_ONLY=true}user/1000"/>
See Also
recording_follow_transfer
boolean Set totrue
if you want recording to continue after a transfer.Usage
<action application="set" data="recording_follow_transfer=true"/>
recordings_dir
stringrecovery_profile_name
string It's used internally so the core recovery engine knows which profile name goes with the call. The profile name to the core is just an arbitrary sub category of the call where to mod_sofia it means the sip profile name. See mailing list discussion.remote_media_ip
stringremote_media_port
integerremote_video_ip
stringremote_video_port
integerringback
string This addition lets you set artificial ringback on a channel that is waiting for an originated call to be answered. This will specify the audio to play to the A leg on unanswered aka (early media) calls.Syntax: <action application="set" data="ringback=[data]"/>
Where data
is either the full path ( must be full path!) to an audio file or teletone generation markup language.
You may also combine this with the ring_ready application. In this case the caller hears the normal ringback tone for a fraction of a second, then he hears the defined ringback media.
Since r15025 local ringback tone is generated only when there is no early media. To force local ringback despite early media use the ignore_early_media channel variable.
Ringback will not be sent unless the variable is set and there's a ringing indication from the party that is being called. See instant_ringback if you want to fake ringback even when ringing indication hasn't been received yet.
Usage
Using the French ring tone defined in vars.xml
:
<action application="set" data="ringback=${fr-ring}"/>
US ring tone:
<action application="set" data="ringback=%(2000,4000,440.0,480.0)"/>
You can send ringback after the call is answered:
def handler(uuid): session = PySession(uuid) session.answer() session.speak("Hello, connecting your call to the first available agent") session.execute("set","call_timeout=30") session.execute("set","continue_on_fail=true") session.execute("set","hangup_after_bridge=true") session.execute("set","ringback=%(2000,4000,440.0,480.0)") session.execute("bridge","sofia/foo/bar@test.com,sofia/foo/baz@test2.com:5070") session.speak("doh!")
rss_alt_config
stringrtcp_audio_interval_msec
integer Channel variable to set the interval in msec between each RTCP SR packet. setting the rtp_timer_name to
none
will create all sorts of undesired side effects with RTCP (packets not sent, RTCP autoadjust failing, etc.).
rtcp_mux
boolean Channel variable to force rtcp-mux to be used on the outgoing INVITE.rtcp_octet_count
integer Contains number of RTCP octets collected during the call.rtcp_packet_count
integer Contains number of RTCP packets collected during the call.rtp_adv_audio_ip
string This channel variable explicitly sets the IP address in SDP on a one-off basis. The "right" way to do this isext-rtp-ip
in the sofia profile.Usage
<action application="set" data="rtp_adv_audio_ip=127.0.0.1" />
rtp_append_audio_sdp
string This may be used to append audio parameters to the SDP sent to B-leg.It should/must be set before bridging.
Usage
<action application="export" data="rtp_append_audio_sdp=a=fmtp:18 annexb=no"/>
rtp_assume_rtcp
boolean Channel variable to force freeswitch to assume rtcp is at rtp port + 1 all the time.rtp_autoflush
boolean When set totrue
(default if not present), it will skip timer waits when the socket already has data on read. When set to false
, it will always sleep one timer interval. When a packet is too late with this setting, it would be saved for next time in the udp stack and we would place a filler packet into the core to keep it moving that is flagged as CNG so you know there is no audio in it. If you have it set to false, you end up with delay if the other side is sending the audio at a different speed (can be tiny difference but it would build up).It is worth it to set to true
if you have crappy network conditions where you are hearing hiccups it's related to jitter. Sometimes you have the other side sending audio too fast, then this option set to false will smooth it out but if you have it set to false
in jitter conditions it tricks it into moving too fast.
rtp_disable_hold
boolean When set totrue
the user may not put the call on hold.Usage
<action application="set" data="rtp_disable_hold=true"/>
rtp_disable_vad_in
booleanrtp_disable_vad_out
booleanrtp_enable_vad_in
booleanrtp_enable_vad_out
booleanrtp_force_audio_fmtp
string Set the audio fmtp.rtp_hold_timeout_sec
integerrtp_jitter_buffer_during_bridge
booleanUsage
<action application="set" data="rtp_jitter_buffer_during_bridge=true"/>
<action application="set" data="rtp_jitter_buffer_during_bridge=false"/>
rtp_manual_rtp_bugs
stringUsage
<action application="set" data="rtp_manual_rtp_bugs=cisco_skip_mark_bit_2833"/>
rtp_negotiate_near_match
boolean Setting this to true will cause FreeSWITCH to consider codec PTIME on inbound codec negotiation as well. If you receive a call with PCMU@30i and only have PCMU@20i on the list, it will prefer anything else that matches codec and ptime by default. This changes behavior and matches PCMU@30i despite the PTIME mismatch. This is only valid if you have other matching codecs on the endpoints lists, of course.Usage
<action application="set" data="rtp_negotiate_near_match=true"/>
rtp_rewrite_timestamps
booleanrtp_sdes_suites
stringrtp_secure_media
stringSyntax: rtp_secure_media=<permission>[:<list of encryption suites>]
sip_secure_media
is no longer implemented
permission:
mandatory
- Accept/Offer SAVP negotiation ONLYoptional
- Accept/Offer SAVP/AVP with SAVP preferredforbidden
- More useful for inbound to deny SAVP negotiation- deprecated
false
- implies forbidden - deprecated
true
- implies mandatory default
- accept SAVP inbound if offered
encryption suites:
AEAD_AES_256_GCM_8
AEAD_AES_128_GCM_8
AES_CM_256_HMAC_SHA1_80
AES_CM_192_HMAC_SHA1_80
AES_CM_128_HMAC_SHA1_80
AES_CM_256_HMAC_SHA1_32
AES_CM_192_HMAC_SHA1_32
AES_CM_128_HMAC_SHA1_32
AES_CM_128_NULL_AUTH
Examples:
rtp_secure_media=mandatory:AES_CM_256_HMAC_SHA1_80,AES_CM_256_HMAC_SHA1_32
rtp_secure_media=true:AES_CM_256_HMAC_SHA1_80,AES_CM_256_HMAC_SHA1_32
rtp_secure_media=optional:AES_CM_256_HMAC_SHA1_80
rtp_secure_media=true:AES_CM_256_HMAC_SHA1_80
rtp_secure_media_inbound
stringSame syntax as rtp_secure_media: rtp_secure_media_inbound=<permission>[:<list of encryption suites>]
Examples:
rtp_secure_media_inbound=true:AEAD_AES_256_GCM_8,AES_CM_256_HMAC_SHA1_80,AES_CM_256_HMAC_SHA1_32
rtp_secure_media_inbound=mandatory:AEAD_AES_256_GCM_8
rtp_secure_media_outbound
stringSame syntax as rtp_secure_media: rtp_secure_media_outbound=<permission>[:<list of encryption suites>]
Examples:
rtp_secure_media_outbound=true:AEAD_AES_128_GCM_8
rtp_secure_media_outbound=optional:AEAD_AES_128_GCM_8
rtp_secure_media_suites
string An alternative, optional variable that specifies a comma-separated list of available encryption suites. If this is specified, then rtp_secure_media need only specify the permission flag without the list of suites.Syntax: rtp_secure_media_suites=<list of encryption suites>
rtp_stun_ping
stringrtp_timeout_sec
integerrtp_timer_name
stringrun_dir
stringscript_dir
stringsdp_m_per_ptime
boolean Adds a newm=
line for each distinct ptime in codec list.When this variable is not set:
- When mixing codecs with various ptime in a codec list, they will now be allowed to co-exist in the sdp but it will send no ptime attr. This means the ptime preferences on the offer will be ignored when mixing codecs with various ptimes. When receiving a codec list with no ptime attr, the ptime will be chosen from local preference instead of assuming 20ms. This means if offer contains PCMU with no ptime and FS has PCMU@40i
- Dynamic payloads will now start at 98 and increment per additional dynamic codec per call. So now you can add CELT@32000h,CELT@48000h and each one will be auto-assigned a dynamic payload type.
Is now implied to be true
, if you don't like this set it to false
but it's going to be undefined behaviour. This basically means if you call in with ptime 30 then you have a bunch of ptime 20 codecs in your outbound list that there will be one m= line with 30 and the original inbound codec and more m=
lines for each discinct ptime in your list. This is, of course, will depend on disable_transcoding or absolute_codec_string as well.
Usage
<action application="set" data="sdp_m_per_ptime=true"/>
sdp_secure_savp_only
string Whenrtp_secure_media=true
FreeSWITCH will offer both AVP and SAVP in the SDP. Setting sdp_secure_savp_only=true
(in addition to rtp_secure_media=true
) will cause FreeSWITCH to offer only SAVP in the SDP.Usage
<action application="export" data="sdp_secure_savp_only=true"/>
send_silence_when_idle
string Intended for 1-leg calls, such as those terminating in an IVR menu or voice mail.0
, this variable tells FreeSWITCH to transmit comfort noise when idle. The value of this variable is set to the divisor of the silence generating function. 400
or 1400
are common values set, but you may experiment with other choices to pick one that sounds best.When true
, FreeSWITCH will pick a default comfort noise value.
When -1
, FreeSWITCH will transmit silence without comfort noise.
Usage
<action application="set" data="send_silence_when_idle=400"/>
session_in_hangup_hook
boolean Allows channel variables to be accessible in the api_hangup_hook that gets executed for the channel. See Lua env object for an example.Usage
<action application="set" data="session_in_hangup_hook=true"/>
signal_bond
string UUID of the channel this channel is bridged/bonded to. Not present on a one-legged call.signal_bridge_to
stringsip
stringsip_acl_authed_by
string readonly Contains the name of the ACL node that authorized this call.sip_acl_token
string readonly Contains the ACL auth token for the current call.sip_auth_method
string The request method used to authenticate with.Known values:
REGISTER
sip_auth_password
string For mod_sofia use with sip_auth_username to answer auth challenges without defining a full gateway.Usage
originate {sip_auth_username=<your_user_name>,sip_auth_password=<your_password>}sofia/external/1xxxxxxx@12.34.56.78 &echo
sip_auth_realm
string This should contain the domain/realm of the authenticated user that has triggered the event, if applicable.Usage
originate {sip_auth_username=<your_user_name>,sip_auth_password=<your_password>}sofia/external/1xxxxxxx@12.34.56.78 &echo
Depending on how your FreeSWITCH instance is configured, you may experience problems with this variable being incorrect or blank after calling the 'bridge' application. If this happens, you may want to force the channel variable:
<action application="bridge" data="{sip_auth_realm=${sip_auth_realm}}sofia/gateway/external/2000"/>
sip_auth_username
string For mod_sofia answer auth challenges without defining a full gateway. Used in tandem withsip_auth_password
. Also indicates the SIP username a device successfully registered to FreeSWITCH with.Usage
originate {sip_auth_username=<your_user_name>,sip_auth_password=<your_password>}sofia/external/1xxxxxxx@12.34.56.78 &echo
sip_authorized
string Indicates whether the SIP device accessing the dialplan is authorized to FreeSWITCH or not. The SIP device can be authorized either via an ACL or via digest authentication.sip_auto_answer
boolean Tells the SIP phone to auto-answer the call, if supported. Can be used for intercom support.Usage
<action application="export" data="sip_auto_answer=true"/>
sip_auto_answer_detected
stringsip_auto_answer_notify
stringsip_auto_answer_suppress_notify
stringsip_auto_simplify
boolean When set, this directs FreeSWITCH to remove itself from the SIP signaling path if it can safely do so.Usage
<action application="set" data="sip_auto_simplify=true"/>
sip_call_id
string SIP headerCall-ID
.sip_callee_id_name
string deprecated Set on the inbound leg to control what caller ID number appears in the caller phone's display.Usage
If you find that
set
doesn't work, try using export
instead.
<action application="set" data="sip_callee_id_name=Reginald" /> <action application="set" data="sip_callee_id_number=2332" /> <action application="bridge" data="sofia/gateway/provider/<Reginald's cellphone number>" />
sip_cid_in_1xx
boolean Prevents FreeSWITCH when it receives 183 from leg-B to automatically insert RPID before sending 183 to leg-A. This can be defined profile-wide with:pass-callee-id=false
.Usage
<action application="set" data="sip_cid_in_1xx=false"/>
sip_cid_type
string Modify how the Caller ID will show up in SIP header of the outbound leg. privacy on the inbound leg controls the remaining contents of RPID and Privacy headers.Usage
Send no extra caller id info (Caller ID will be in the SIP From
):
this will not work for gateways. You must set
caller-id-in-from=true
in the gateway settings.
{sip_cid_type=none}sofia/default/user@example.com
Send Remote-Party-ID
(default):
{sip_cid_type=rpid}sofia/default/user@example.com
Send P-Asserted-Identity
:
you must set privacy flag, otherwise
P-Preferred-Identity
will be inserted instead of P-Asserted-Identity
.
{sip_cid_type=pid}sofia/default/user@example.com
Send RPID with chosen content and privacy flags (+
delimited, none
to clear all flags):
{sip_cid_type=rpid,origination_caller_id_name=test,origination_caller_id_number=1234,origination_privacy=screen+hide_name+hide_number}sofia/default/user@example.com
Send Remote-Party-ID
with chosen content:
{sip_cid_type=rpid,origination_caller_id_name=test,origination_caller_id_number=1234}sofia/default/user@example.com
sip_codec_negotiation
stringsip_codec_negotiation
is basically a channel variable equivalent of inbound-codec-negotiation.Options:
generous
scrooge
greedy
Before 74a0cfd1e101413a3941c41d04ee01d8df2ae418, sip_codec_negotiation
will always be overwritten by the sofia profile configuration param sip-codec-negotiation
. As of this revision, the codec negotiation can be changed on a per-call basis.
Usage
<action application="set" data="sip_codec_negotiation=greedy"/>
sip_contact_host
string Hostname part of theContact
SIP header.Usage
If your request header contains:
Contact: <sip:gw+test@server.example.com:5060;transport=udp;gw=test>
Then the value for this field would be:
server.example.com
sip_contact_port
integer Port part of theContact
SIP header.Usage
If your request header contains:
Contact: <sip:gw+test@server.example.com:5060;transport=udp;gw=test>
Then the value for this field would be:
5060
sip_contact_user
string Username part from theContact
SIP header.Usage
If your request header contains:
Contact: <sip:gw+test@server.example.com:5060;transport=udp;gw=test>
Then the value for this field would be:
gw+test
sip_copy_custom_headers
boolean To pass some custom X-headers from B-leg to A-leg, add{sip_copy_custom_headers=true}
to the dial string of the B-leg.Usage
Set it to false
to disable sending custom X- headers to your SIP gateway provider:
<action application="set" data="sip_copy_custom_headers=false"/>
sip_copy_multipart
boolean FreeSWITCH supports onlyINVITE
s with multipart bodies. FreeSWITCH does not support response messages such as 183 Session Progress
or 200 Ok
with multipart bodies. Typically SIP bodies only have one MIME part with an SDP using MIME type application/sdp
. The SIP spec allows for multiple bodies defined with MIME type multipart/mixed
. In this case FreeSWITCH will do it's best to find the MIME part with the SDP and parse that as it normally does. However, you can change FreeSWITCH behavior with multipart bodies and bridge using this variable. FreeSWITCH will "do the right thing" and attach an application/sdp type generated by FreeSWITCH (per your settings) for the B leg as it normally would. The other non-SDP MIME parts just pass through.
Usage
To have FreeSWITCH keep the multiple MIME parts intact when using bridge (default):
<action application="set" data="sip_copy_multipart=true"/>
To have FreeSWITCH strip the multiple MIME parts when using bridge:
<action application="set" data="sip_copy_multipart=false"/>
sip_destination_url
stringsip_enable_soa
boolean For per call basis which can be set tofalse
to disable SIP SOA from sofia and most likely result in untouched exchange of SDP.Usage
<action application="set" data="bypass_media=true"/> <action application="export" data="sip_enable_soa=false"/>
sip_exclude_contact
stringsip_execute_on_image
string Execute an application as soon as you get a T.38 invite. This variable is similar to execute_on_answer. You can run t38_gateway or rxfax etc when you get a T.38 re-invite but no CNG tone, or you want to ignore the tone and only react when getting a T.38 re-invite.sip_force_audio_fmtp
string Set the audio fmtp.sip_force_full_from
stringsip_force_full_to
stringsip_force_video_fmtp
booleansip_from_comment
stringsip_from_display
string The 'User' element of the SIP From: lineUsage
Clear the user part of the SIP message sent to the Leg B call:
<action application="bridge" data="{sip_from_display=_undef_}user/1001"/>
sip_from_host
string Hostname part of theFrom
SIP header.Usage
If your request header contains:
From: <sip:1000@server.example.com>;tag=0e70ba56
Then the value for this field would be:
server.example.com
sip_from_port
integer Port part of theFrom
SIP header.Usage
If your request header contains:
From: <sip:1000@server.example.com:5661>;tag=0e70ba56
Then the value for this field would be:
5661
However, if your request header does not contain a port, then the value for this field would be your default SIP port (usually 5060) - for example:
From: <sip:1000@server.example.com>;tag=0e70ba56
sip_from_uri
string The SIP URI of the endpoint sending the INVITE.Usage
<action application="export" data="sip_from_uri=${sip_from_uri}"/>
Some SIP providers insist on handling caller ID in a non-normal way. In most cases you can use effective_caller_id_name and effective_caller_id_number to set the caller ID on the outbound (B leg) of a bridged call. In some cases the SIP provider doesn't like that and may just show "anonymous" or some other default caller ID information.
The above example takes the From URI of an incoming SIP call and exports that value to the B leg. This is handy when you have a scenario like this:
Alice ==> FreeSWITCH bridge ==> Bob
You want Alice's caller ID information to be sent to Bob instead of FreeSWITCH's caller ID information. Usually this "just works" but if it doesn't you can try exporting sip_from_uri as above.
sip_from_user
string Username part of theFrom
SIP header.Usage
If your request header contains:
From: <sip:1000@server.example.com>;tag=0e70ba56
Then the value for this field would be:
1000
sip_from_user_stripped
string This is the same as sip_from_user, but has the+
sign stripped from it.sip_gateway
stringsip_gateway_name
string If your call is outbound, and Leg B is routed via a gateway, then this variable will contain the gateway name.Usage
Call from user on internal profile, routed out via gateway "ntl":
sip_profile_name=gateway sip_gateway_name=ntl sofia_profile_name=internal
sip_h_Referred-By
string This is the lineReferred-By
in the SIP message. It may be set on a transfer to a number, which then bridges somewhere else.Usage
<action application="set" data="sip_h_referred-by=000@domain.com"/>
If you wish to unset it, you can use:
<action application="unset" data="sip_h_referred-by"/>
sip_handle_full_from
stringsip_handle_full_to
stringsip_hangup_disposition
string This variable contains the value of who sent the SIP BYE message. Some examples from XML CDRs:<sip_hangup_disposition>send_bye</sip_hangup_disposition> <sip_hangup_disposition>recv_bye</sip_hangup_disposition> <sip_hangup_disposition>send_refuse</sip_hangup_disposition> <sip_hangup_disposition>send_cancel</sip_hangup_disposition>
Interpretation of these values differs on incoming and outgoing calls since FreeSWITCH is at different ends of the session:
Value | Incoming | Outgoing |
---|---|---|
send_bye | FS sent BYE to the caller (we hung up) | FS sent BYE to the endpoint (we hung up) |
recv_bye | FS received BYE from the caller (they hung up) | FS received BYE from the endpoint (they hung up) |
send_refuse | FS rejected the call (e.g. 4xx or 5xx) | Endpoint rejected the call (e.g. 4xx or 5xx) |
send_cancel | n/a | FS aborted the call (we sent CANCEL) |
sip_header_name
stringsip_history_info
stringsip_ignore_183nosdp
string Ignoring 183 without SDP. This option is not for normal basic call flow.Usage
<action application="set" data="sip_ignore_183nosdp=true"/>
sip_ignore_reinvites
boolean Tells FreeSWITCH to accept/ignore re-INVITEs from remote end.Usage
Don't allow any re-INVITEs once bridged:
<action application="set" data="sip_ignore_reinvites=true"/>
sip_ignore_remote_cause
booleansip_invite_call_id
string SIPCall-ID
to use when originating a call.Usage
<action application="set" data="sip_invite_call_id=mycustomcallid"/>
sip_invite_contact_params
stringsip_invite_domain
string Set the from domain in leg (B).Usage
<action application="bridge" data="{sip_invite_domain=${sip_from_host}}sofia/gateway/gw1/$1@domain.org"/>
sip_invite_from_params
string Sets the from parameters on the B-leg of the call. The from parameters come afteruser@host:port
and before. The initial semi-colon is added after the port.Usage
{sip_invite_from_params=otg=mytrunk}sofia/gateway/sonus/$1
Returns:
From: <sip:5552345678@sonus:5060;otg=mytrunk>;tag=blah
sip_invite_from_uri
stringsip_invite_full_from
stringsip_invite_full_to
stringsip_invite_params
stringsip_invite_record_route
stringsip_invite_req_uri
string Sets the URI in the headerRequest-Line INVITE
when calling bridge or originate. RFC 3261 specifies that compliant endpoints SHOULD route based on the Request URI, not the URI in
To:
Usage
<action application="bridge" data="{sip_invite_req_uri=sip:11112222@test1.com}sofia/external/33334444%192.168.4.6"/>
Result:
INVITE sip:11112222@test1.com SIP/2.0 From: "" <sip:0000000000@192.168.2.7>;tag=N6K579y4g6j0D To: <sip:33334444@192.168.4.6>
sip_invite_route_uri
string Sets the URI in the headerRoute
when calling bridge or originate.Usage
originate {sip_invite_route_uri=<sip:+48399999999@10.0.0.51:5080;lr;orig>,origination_caller_id_number=399999000}sofia/internal/+48399999999@domain.com &echo
Result:
INVITE sip:+48399999999@domain.com SIP/2.0 Via: SIP/2.0/UDP 10.0.0.51;rport;branch=z9hG4bKpmFv4aXv4tKcK Route: <sip:+48399999999@10.0.0.51:5080;lr;orig>
sip_invite_tel_params
string Tel URI parameters (npdi, rn) appearing in SIP URI on outbound calls.Usage
To produce INVITE sip:555000002;npdi=yes;rn=5555550001@1.2.3.4;user=phone SIP/2.0
:
<action application="bridge" data="{sip_invite_tel_params=npdi=yes;rn=555000001,sip_invite_params=user=phone}sofia/gateway/test_gw/555000002"/>
sip_invite_to_params
stringsip_invite_to_uri
string Sets the URI in the headerTo
when calling bridge or originate.Usage
originate {sip_invite_to_uri=<sip:11112222@test1.com>}sofia/internal/33334444@192.168.4.6 &park
Result:
INVITE sip:33334444@192.168.4.6 SIP/2.0 From: "" <sip:0000000000@192.168.2.7>;tag=N6K579y4g6j0D To: <sip:11112222@test1.com>
Alternatively, if you need to set just the username in the header To
, you can pass it at the end of the dial string:
originate sofia/internal/33334444@192.168.4.6^11112222 &park
Result:
INVITE sip:33334444@192.168.4.6 SIP/2.0 From: "" <sip:0000000000@192.168.2.7>;tag=Qr6pB00BBrZ5m To: <sip:11112222@@192.168.4.6>
sip_jitter_buffer_plc
boolean Enables/disables packet loss concealment (PLC) when using the jitter buffer. PLC is enabled by default when the jitter buffer is enabled. Set this variable before enabling the jitter buffer for it to have an effect.Usage
<action application="set" data="sip_jitter_buffer_plc=true"/>
<action application="set" data="sip_jitter_buffer_plc=false"/>
sip_local_sdp_str
stringsip_local_url
stringsip_looped_call
booleantrue
if the call has been authenticated via means other than an ACL and the current request IP/port matches the profile IP/port (see src/mod/endpoints/mod_sofia/sofia.c).Usage
In conf/dialplan/public.xml
:
<condition field="${sip_looped_call}" expression="^true$">
<extension name="unloop"> <condition field="${unroll_loops}" expression="^true$"/> <condition field="${sip_looped_call}" expression="^true$"> <action application="deflect" data="${destination_number}"/> </condition> </extension>
sip_mirror_remote_audio_codec_payload
boolean To tell sip to break the rfc and expect the codec payload the other side replies with rather than the one it offered which is the correct behavior. This variable can be set globally or per channel.
sip_nat_detected
stringsip_network_destination
string It is intended for use with devices registering behind a NAT where theRequest-URI
should contain the contact that was bound to the AOR during the registration request while the request itself should be sent to the public IP and port number of the NAT "pinhole". It does not add a Route
header field to the request like the ;fs_path=
or the sip_route_uri options do.Usage
<action application="bridge" data="{sip_network_destination=sip:5551234567@66.243.109.243:10005}sofia/external/5551234567@172.16.110.45:5060"/>
sip_p_rtp_stat
stringsip_profile
string Name of the SIP profile which the request was received on.sip_profile_name
string If your call is outbound, then this variable will contain the profile name used for the outbound channel (Leg B)If the outbound channel is a gateway, then this variable will be set to gateway
, and you'd need to look at sip_gateway_name
to get the name of the gateway.
If the outbound channel is another profile, then this variable will be set to the name of that profile.
This should NOT be confused with sofia_profile_name, which is the name of the profile for Leg A.
Usage
Call from user on internal profile, routed out via gateway "ntl":
sip_profile_name=gateway sip_gateway_name=ntl sofia_profile_name=internal
Call from user on internal profile, routed out via internal profile:
sip_profile_name=internal sip_gateway_name= sofia_profile_name=internal
Call from user on external profile, routed out via internal profile:
sip_profile_name=internal sip_gateway_name= sofia_profile_name=external
sip_received_ip
stringsip_received_port
integersip_recover_contact
stringsip_recover_via
stringsip_recovery_break_rfc
string To NOT reverse the from and to on UAS Re-INVITEs. This breaks RFC. This variable can be set globally or per channel
sip_refer_reply
stringsip_referred_by_cid
stringsip_referred_by_user_stripped
stringsip_renegotiate_codec_on_reinvite
boolean Allow SDP codec change with re-INVITE.Usage
<action application="bridge" data="{sip_renegotiate_codec_on_reinvite=true}sofia/gateway/trunk/$1"/>
Globally in vars.xml
:
<X-PRE-PROCESS cmd="set" data="sip_renegotiate_codec_on_reinvite=true"/>
In a SIP profile:
<param name="renegotiate-codec-on-reinvite" value="true"/>
sip_reply_host
stringsip_request_host
string Hostname part of the SIP header.Usage
If your request header starts with:
REGISTER sip:172.16.44.8 SIP/2.0
Then the value of this field would be:
172.16.44.8
sip_request_port
string Port part of the SIP header.Usage
If your request header starts with:
REGISTER sip:172.16.44.8:5061 SIP/2.0
Then the value of this field would be:
5061
However, if your request header does not contain a port, then the value for this field would be your default SIP port (usually 5060):
REGISTER sip:172.16.44.8 SIP/2.0
sip_require_timer
boolean FS requires timer by default on session refresh unless its t.38 re-invite. To disable the require timer on session refresh, set it tofalse
.Usage
<action application="set" data="sip_require_timer=false"/>
sip_route_uri
string This sets where the INVITE packet should actually be sent to.This should normally be needed in situations where the TO field contains a hostname which points back at itself, and would cause an endless loop if this variable is not set.
See also: - FS-5349Getting issue details... STATUS
Usage
Very simple usage, set during bridge immediately before the endpoint to bridge to:
bridge {sip_route_uri=sip:USER@HOSTNAME.or.IP.ADDRESS}
A real-life example where this was needed. It changes the Request-URI
and sends the INVITE packet to the correct destination by looking up the contact details for the registered endpoint. This is used to send an incoming call to a registered endpoint (PBX in this case) but set a Request-URI
so the call can be routed by the receiving party. Without the sip_route_uri
variable set, the call would loop back to FreeSWITCH endlessly until the originating party cancels the call. The incoming number routes to another extension, and exports the original dialled DDI (as dialled_ddi) so this can be used with this bridge command.
bridge {sip_route_uri=sip:${sofia_contact(${dialed_extension}@${domain_name})},sip_invite_req_uri=sip:${dialled_ddi}@${domain_name}}user/${user_data(${dialed_extension}@${domain_name} attr id)}@${domain_name}
sip_rtp_rxstat
stringsip_rtp_txstat
stringsip_sticky_contact
stringsip_subject
stringsip_term_cause
stringsip_term_status
stringsip_to_comment
stringsip_to_host
string Hostname part of theTo
SIP header.Usage
If your request header contains:
To: <sip:1000@server.example.com>;tag=0e70ba56
Then the value for this field would be:
server.example.com
sip_to_port
string Port part of theTo
SIP header.Usage
If your request header contains:
To: <sip:1000@server.example.com:5661>;tag=0e70ba56
Then the value for this field would be:
5661
However, if your request header does not contain a port, then the value for this field would be your default SIP port (usually 5060):
To: <sip:1000@server.example.com>;tag=0e70ba56
sip_to_uri
stringsip_to_user
string Username part of theTo
SIP header.Usage
To set manually, use:
<action application="set" data="sip_to_user=whatevah" />
Then the value for this field would be:
1000
As options you can make call:
bridge(sofia/external/333@biloxi.com^1234)
or make call:
bridge(sofia/external/333^1234@biloxi.com)
sip_transport
stringsip_use_gateway
stringsip_user_agent
string User agent part of the SIP header.Usage
If your request header contains:
User-Agent: FreeSWITCH-mod_sofia/1.2.0-rc2+git~20120713T162602Z~0afd7318bd+unclean~20120713T184029Z
Then the value of this field would be:
FreeSWITCH-mod_sofia/1.2.0-rc2+git~20120713T162602Z~0afd7318bd+unclean~20120713T184029Z
sip_via_host
stringsip_via_port
integersip_via_protocol
stringsip_via_rport
stringsip_video_fmtp
stringsip_video_pt
stringsip_wait_for_aleg_ack
string When you set the variablesip_wait_for_aleg_ack
on the b leg in the {}
for the outbound call, this should make the B leg delay sending the ACK
until it sees that the A leg has recv'd an ack.Usage
<action application="bridge" data="{sip_wait_for_aleg_ack=true}sofia/internal/foo@bar.com"/>
skeleton
string This is an example of how to create a channel variable page. This section is the description of the variable. Put the description information here and then the usage example below.Usage
<action application="set" data="skeleton=foo"/>
skip_cdr_causes
string This is a list of call hangup causes that should not trigger CDR processing.sleep_eat_digits
boolean When set totrue
, the sleep application will consume DTMFs which will, for example, prevent a caller from exiting out of an IVR. The default behavior is not to eat DTMF digits. This variable was added in SVN rev 14102. this is a change in default behavior as the sleep application previously ate DTMFs without exception. Be sure to set
sleep_eat_digits
to true
in order to preserve the previous behavior.
Usage
<action application="set" data="sleep_eat_digits=true"/>
socket_host
stringsocket_path
stringSOFIA_CRYPTO_MANDATORY_VARIABLE
stringSOFIA_HAS_CRYPTO_VARIABLE
stringsofia_profile_domain_name
stringsofia_profile_name
string The name of the profile of which the call originated (Leg A). This should NOT be confused with sip_profile_name.
Usage
Call from user on external profile
sofia_profile_name=external
Call from user on internal profile
sofia_profile_name=internal
sofia_record_file
stringSOFIA_REFER_TO_VARIABLE
stringSOFIA_REPLACES_HEADER
stringSOFIA_SECURE_MEDIA_CONFIRMED_VARIABLE
stringSOFIA_SECURE_MEDIA_VARIABLE
stringSOFIA_SESSION_TIMEOUT
stringsound_prefix
string Directory prefix where the sounds for phrase macros live, and where recordings are saved by default. Seemod_dptools:record
, mod_dptools:record_session
, and mod_commands
's (the FreeSWITCH API) uuid_record
.See Variables on how to check the values of local and global variables.
sounds_dir
stringspandsp_dtmf_rx_filter_dialtone
boolean Sets the filter dialtone parameter in the spandsp DTMF detector. Dialtone filtering is disabled by default. Set this variable prior to executing spandsp_start_dtmf.Usage
<action application="set" data="spandsp_dtmf_rx_filter_dialtone=true"/> <action application="spandsp_start_dtmf" />
spandsp_dtmf_rx_reverse_twist
integer Sets the reverse twist setting in the spandsp DTMF detector. Reverse twist is set to 4 dB by default. This value can be safely increased up to 6 or 7 without a significant increase in talk-off to allow DTMFs that exceed this threshold to be detected. Set this variable prior to executing spandsp_start_dtmf.Usage
<action application="set" data="spandsp_dtmf_rx_reverse_twist=6"/> <action application="spandsp_start_dtmf" />
spandsp_dtmf_rx_threshold
integer Sets the threshold parameter in the spandsp DTMF detector. Threshold is set to -42 dBm0 by default. Set this variable prior to executing spandsp_start_dtmf.Usage
<action application="set" data="spandsp_dtmf_rx_threshold=-42"/> <action application="spandsp_start_dtmf" />
spandsp_dtmf_rx_twist
dtmf digit Sets the twist parameter in the spandsp DTMF detector. Twist is set to 8 dB by default. Set this variable prior to executing spandsp_start_dtmf.Usage
<action application="set" data="spandsp_dtmf_rx_twist=8"/> <action application="spandsp_start_dtmf" />
star_replace
stringstart_epoch
integerstart_stamp
stringstart_uepoch
integerstorage_dir
stringstream_prebuffer
stringsuppress_cng
boolean Setsa=silenceSupp: off
in the SDP to disable silence suppression while making an outbound call.Usage
<action application="set" data="suppress_cng=true"/>
switch_m_sdp
string readonly The B-leg remote SDP. It is used to store the remote SDP used by the other leg/channel of a call. (In the A-leg that will be the remote SDP of the B-leg). This variable is set, but never used by FreeSWITCH.SWITCH_PLAYBACK_TERMINATOR_USED
stringswitch_r_sdp
string readonly This variable holds the remote SDP for the current leg/channel.Usage
Don't add a carriage return after
"set">
or you'll end up writing a variable with a different name, leaving switch_r_sdp
with the same value.
<action application="set"><![CDATA[switch_r_sdp=(sdp here) ]]> </action>
switch_serial
stringSWITCH_UUID_BRIDGE
string
temp_dir
stringtemp_hold_music
string This variable specifies a hold music value that gets played to a caller only until they get transferred. After the transfer, thehold_music
variable will apply.Usage
<action application="set" data="temp_hold_music=local_stream://alternate_moh"/>
timer_name
string If set will make playback and speak use a timer to clock the audio instead of the read.Usage
<action application="set" data="timer_name=soft"/>
timezone
string Sets the timezone for this particular call. Can be used, e.g., to set the timezone for a caller who is checking his/her voicemail. The value is expressed in Linux timezone format (ex. America/New_York -- see/usr/share/zoneinfo/zone.tab
for the standard list of Linux timezones). this variable must actually be set before the comparison, so either set it inline, transfer, or set it in the user directory.
See also: Time of Day and Holiday Routing.
Usage
You can set the time zone globally for Freeswitch in /conf/vars.xml
<X-PRE-PROCESS cmd="set" data="timezone=America/Toronto"/>
Specify the timezone in the dialplan:
<action application="set" data="timezone=Asia/Seoul"/>
<action application="set" data="timezone=GMT0"/>
<action application="set" data="timezone=America/New_York"/>
In the directory:
<param name="timezone" value="America/New_York"/>
tod_tz_offset
integer Sets the GMT offset to be used on this call for time of day conditions. this variable must actually be set before the comparison, so either set it inline, transfer, or set it in the user directory.
Usage
To set the offset global in conf/vars.xml
:
<X-PRE-PROCESS cmd="set" data="tod_tz_offset=5"/>
<action application="set" data="tod_tz_offset=5"/>
tone_detect_expires
stringtone_detect_sleep
stringtransfer_after_bridge
string This variable can control what happens when a call is hang up. This can be used in conjunction with mod_fifo to control the "agent", possibly sending them back to an agent queue. This is checked after park_after_bridge and before hangup_after_bridge. Variable gets cleaned after bridge is destroyed and leg is transferred to the specified dialplan.
Usage
<action application="set" data="transfer_after_bridge=1000"/>
Note the
:
separator
<action application="set" data="transfer_after_bridge=1000:XML:default"/>
transfer_fallback_extension
string It's an extension the channel falls back to on failed transfer. Set it before the transfer. For example, if you transfer to some invalid or unavailable ext, it will then "fall back" to the ext set in the var.transfer_history
stringtransfer_on_fail
string Allows you to transfer call flow when a called party can not be reached for specific reasons (unallocated_number, etc). you must also set failure_causes
Argument syntax: hangupcauses destination dialplan context
Usage
<action application="set" data="failure_causes=UNALLOCATED_NUMBER"/> <action application="set" data="transfer_on_fail=UNALLOCATED_NUMBER"/>
<action application="set" data="transfer_on_fail=1"/>
transfer_ringback
string This is the sound that will play if a call has already been answered, and it is then transferred to another endpoint. The syntax is the same as ringback.Usage
<action application="set" data="transfer_ringback=${fr-ring}"/>
transfer_source
stringtransfer_to
stringtts_engine
value |
---|
tts_commandline |
flite |
unimrcp:mrcp_server_name |
See Also
tts_voice
stringuduration
integerUNIQUEID
stringuser_context
stringuser_name
stringuuid_bridge_continue_on_cancel
boolean When set totrue
causes the system to move on in the dialplan if it hits a bad b-leg. Default is false
because this behavior is probably not recommended. You may find this variable useful when implementing Dialplan FollowMe.Usage
<action application="set" data="uuid_bridge_continue_on_cancel=true"/>
verbose_presence
stringverbose_sdp
boolean The RFCs require an rtpmap for IANA dynamic payload types. An rtpmap with codec name and payload type is not required for well known static payloads - (PCMU, PCMA, G729, etc).By default FreeSWITCH sets verbose_sdp=false
which doesn't include an rtpmap for static payload types. If your equipment doesn't support this (shame on them) set verbose_sdp=true
which will include rtpmaps for any static payload types (previous default behavior).
video_logo_path
stringView more details about this in the mod_conference page
video_mirror_input
boolean If set totrue
, mirrors the output resolution to match the input resolution of the caller, applies to calls or conferences.video_possible
stringvideo_read_codec
stringvideo_read_rate
stringvideo_write_codec
stringvideo_write_rate
stringvm_cc
stringvm_message_ext
string Determines in which format the voicemail message is saved. Can also be set using the paramvm-message-ext
.This variable is set in the dial plan.
Default available options:
mp3
wav
Usage
<action application="set" data="vm_message_ext=mp3"/>
vmd_detect
stringvname
stringvoicemail_account
stringvoicemail_alternate_greet_id
string Overrides the ID the voicemail application reads back i.e. to say a phone number instead of the user ID.Usage
<user id="johnsmith" number-alias="1000"> <variables> <variable name="mailbox" value="1000"/> <variable name="effective_caller_id_name" value="1000"/> <variable name="effective_caller_id_number" value="1000"/> <variable name="voicemail_alternate_greet_id" value="1000"/> </variables> </user>
voicemail_authorized
stringvoicemail_caller_id_name
stringvoicemail_caller_id_number
stringvoicemail_current_folder
stringvoicemail_domain
string Sets the domain name in the sender email address when mod_voicemail emails a voicemail message.Usage
From conf/directory/default/1010.xml
:
<include> <user id="1010" mailbox="1010"> <params> <param name="password" value="password"/> <param name="vm-password" value="1010"/> </params> <variables> <variable name="voicemail_domain" value="speakblast.com"/> </variables> </user> </include>
voicemail_domain_name
stringvoicemail_email
stringvoicemail_file_path
stringvoicemail_greeting_number
stringvoicemail_greeting_path
stringvoicemail_id
stringvoicemail_message_len
integervoicemail_priority
stringvoicemail_profile_name
stringvoicemail_read_flags
stringvoicemail_time
stringvoicemail_total_new_messages
integervoicemail_total_saved_messages
integervoicemail_urgent_new_messages
integervoicemail_urgent_saved_messages
integerwaitmsec
integerwaitsec
integerwaitusec
integerwrite_codec
string readonly The negotiated codec of the outbound call leg.write_rate
stringxfer_uuids
string
xml_cdr_base
stringzrtp_enabled
stringThis global variable is set by the FreeSWITCH core to the value of the global rtp-enable-zrtp setting in switch.conf.xml. For more information see the SIP TLS page.