Skip to main content

Variables Master List

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!

Click here to expand Table of Contents

Error rendering macro 'toc'

null

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 in cdr_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 an Alert-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

integer

answer_stamp

string

answer_uepoch

integer

answermsec

integer

answersec

integer

answerusec

integer

api_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:

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

string

api_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

string

api_on_pre_originate

string

api_on_ring

string

api_on_sip_extra_headers

string

api_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

string

asr_intercept_dtmf

string

auto_answer_destination

string In an inbound call, the remote side may send a SIP 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 Setting auto_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

string

This defines the base directory for most other directory settings

billmsec

integer

billsec

integer

billusec

integer

bind_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

string

bridge_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

integer

bridge_export_vars

string bridge_export_vars lists variables to be exported to the other leg upon bridge.

bridge_filter_dtmf

boolean Setting this variable to true 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 have continue_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.

(warning) this is executed AFTER the call is setup but BEFORE the media (audio) is bridged

bridge_pre_execute_aleg_data

string Arguments to be used with bridge_pre_execute_aleg_app.

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.

(warning) 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

string

bridge_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

string

bridge_uepoch

integer

bridge_uuid

string

bypass_keep_codec

boolean By doing export bypass_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 Overview

Usage

<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

string

cache_speech_handles

string

call_clientcode

string This is used by SNOM phones. When FreeSWITCH receives a SIP INFO message with x-clientcode header, this variable is set to the value of that header.

call_timeout (deprecated)

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

string

callee_id_number

string

caller_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 fallback

campon_fallback_dialplan

string Optional dialplan name where the call is transferred for fallback

campon_fallback_exten

string Extention number where the call is transferred for fallback

campon_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 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="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

string

CHANNEL

string

channel_name

string

codec_string

string Sets the base codec string to use.

Usage

<action application="set" data="codec_string=PCMU,GSM"/>

conf_dir

string

conference_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 of conference_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.

This variable controls how long the outbound call will ring. Thus, if you do not ignore early media it will likely never get a chance to increment.

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.

(info) 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

string

Usage

<action application="set" data="conference_exit_sound=silence_stream://10"/>

conference_input_buffer_flush_msec

If the input buffer (audio from this member into the conference) builds up to longer than x milliseconds, then clear the buffer. Default is 500. Added in FreeSWITCH Enterprise v20.23.2

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 the conference_member_id value for any conference to which the channel may be connected.

conference_moderator

boolean Is true if the channel is connected to a conference as a moderator.

conference_output_buffer_flush_msec

If the output buffer (audio from the conference to this member) builds up to longer than x milliseconds, then clear the buffer. Default is 500. This will log Flushing output buffer (getting behind) mux_used=%d flush_len=%d at DEBUG level when the limit is hit. Added in FreeSWITCH Enterprise v20.23.2

conference_output_discard_low_energy

If the packet's energy level is less than this value and there are more than 2 packets waiting in the output buffer (audio from the conference to this member) then drop this packet. A few low energy packets must be sent first before any are dropped to avoid totally truncating silence. To discard the standard comfort noise in a conference, set this to 15 or higher. Default is 0 (don't discard low energy packets). Added in FreeSWITCH Enterprise v20.23.2

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). If true 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 named b_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

string

created_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

string

current_application_data

string

current_application_response

string

data

string

db_dir

string

default_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 to true 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

See also Variables Master List (although this variable is also listed there without any descriptions).

detect_speech_result

string readonly The result of play_and_detect_speech.

dialed_domain

string

dialed_group

string

dialed_user

string

digits_dialed

string

Notes

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

boolean

disable_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

boolean

disable_radius_stop

boolean

disable_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 to true 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

string

dl_from_host

string

dl_from_user

string

dl_host

string

dl_user

string

domain_name

string

drop_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-4769 -Authenticate to see issue details 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 If drop_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 If drop_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 is false. Set this variable prior to executing spandsp_start_dtmf.

Usage

<action application="set" data="dtmf_verbose=true"/>
<action application="spandsp_start_dtmf" />

duration

integer

easy_acctcode

string

easy_destnum

string

easy_dialstring

string

easy_group

string

easy_limit

string

eavesdrop_annnounce_macro

string

eavesdrop_announce_id

string

eavesdrop_group

string

eavesdrop_indicate_failed

string

eavesdrop_indicate_idle

string

eavesdrop_indicate_new

string

eavesdrop_require_group

string

effective_ani

string

effective_aniii

string

effective_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 to true 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 discussion

Usage

<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

boolean

end_epoch

integer

end_stamp

string

end_uepoch

integer

endpoint_disposition

string

ep_codec_prefer_sdp

string ep_codec_prefer_sdp contains the "endpoint" codec string on the A leg. The order of preference is chosen by the A leg

ep_codec_string

string ep_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.

(info) 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

string

execute_on_fax_failure

string

execute_on_fax_result

string

execute_on_fax_success

string

execute_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

string

Execute 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

This will execute after the call has been answered and media is being exchanged. Use this instead of execute_on_answer if for example, the REFER commands blocks for 10 seconds in your dialplan extension.

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

string export_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.

(info) This is useful to transfer information from a-leg (INVITE) to the future b-leg of REFER.

EXTEN

string

fail_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 unless continue_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

string

fax_disable_v17

boolean fax_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

integer

fax_document_transferred_pages

integer

fax_ecm_requested

boolean

fax_ecm_used

boolean

fax_end_page

string

fax_filename

string

fax_force_caller

boolean

fax_header

string

fax_ident

string

fax_image_resolution

string

fax_image_size

string

fax_local_station_id

string

fax_prefix

string

fax_remote_station_id

string

fax_result_code

string

Result CodeMessage
0OK
2Timed out waiting for initial communication
3Timed out waiting for the first message
5The HDLC carrier did not stop in a timely manner
6Failed to train with any of the compatible modems
13Unexpected message received
14Received bad response to DCS or training
15Received a DCN from remote after sending a page
17Received a DCN while waiting for a DIS
20Received no response to DCS or TCF
23Invalid ECM response received from transmitter
31Timer T2 expired while waiting for fax page
32Timer T2 expired while waiting for next fax page
48Disconnected after permitted retries
49The call dropped prematurely

fax_result_text

string

fax_start_page

string

fax_success

boolean

fax_transfer_rate

string

fax_use_ecm

boolean

fax_v17_disabled

boolean

fax_verbose

boolean

fifo_announce

string If you invoke fifo without providing an announce file as an argument, mod_fifo will fall back to the value of fifo_announce.

fifo_bridged

boolean mod_fifo sets fifo_bridged to true when manually tracking a call.

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 in fifo_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 When fifo_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 in wait 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 pressing 0. 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 to true when a manually tracking a call.

fifo_member_wait

string If this variable is set to wait, 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

string

fifo_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

string

Syntax: 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_outbound_uuid

string Used by mod_fifo to track manual calls.

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_position

integer readonly mod_fifo writes the caller's position to this variable.

fifo_priority

string

fifo_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

string

fifo_serviced_uuid

string

fifo_status

string The status of the consumer or caller. Usually WAITING or TALKING.

fifo_strategy

string

fifo_target

string

fifo_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

integer

flow_billsec

integer

flow_billusec

integer

force_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

string

grammar_dir

string

group_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:

  1. Call is ringing.
  2. Call is answered, waiting to be confirmed.
  3. 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 with group_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" />

See Also

group_confirm_key — Specify a DTMF to bridge leg-A to leg-B

answer confirmation

group_confirm_key

dtmf digit In the group_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" />

See Also

group_confirm_file — Specify a sound file to play to leg-B to prompt to dial a confirmation key

answer confirmation

group_context

string

boolean Controls what happens to a calling (A) party when in a bridge state, and the called (B) party hangs up. If true 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). If true (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. The hold_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 signaling through to the far-end via 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

string

hostname

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

string

id

string

ignore_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 is false.

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

string

inherit_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

(warning) 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 to true, 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

string

is_outbound

boolean

ivr_menu_status

string ivr_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

Channel variable. Activates the jitter buffer. The jitter buffer has three params: length, max length, and max drift.

Usage

jitterbuffer_msec=buffer length:maximum buffer length:maximum drift

The three arguments specify the size of the jitter buffer either in units of milliseconds when only numerals are used or in the count of packets when the suffix 'p' is appended to the number.

buffer length – beginning length of jitter buffer

max length – maximum size to which the jitter buffer is allowed to grow

max drift – maximum delay the jitter buffer will tolerate before dropping frames to make up ground

Examples

Numeric time example

<action application="set" data="jitterbuffer_msec=60:200:20"/>
<action application="answer"/>

Packet count example

<action application="set" data="jitterbuffer_msec=2p:25p:4p"/>
<action application="answer"/>

Or to set it only on the subsequent outbound (Leg B) call: the export dialplan app sets a variable on both the current channel and on any channels it creates, while the 'nolocal:' directive disables setting it on the current (Leg A) channel and only sets it on the subsequent outbound channels.

Leg B only with nolocal:

<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:

jb in bridge app

<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 FreeSWITCH and the remote gateway has jitter, 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

string

last_app

string

last_arg

string

last_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

string

last_dtmf_duration

string

last_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.

TODO What is dmachine ? Source search on the source.

TODO Does this only work with 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

string

lcr_route_count

integer

left_hanging_extension

string

leg_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

string

Usage

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

string

limit_ignore_transfer

string

limit_max

string

limit_rate

string

limit_realm

string

limit_usage

string

local_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

Example: 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.

Example: 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

string

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

string

local_media_port

string

local_video_ip

string

local_video_port

string

log_dir

string

loopback_bowout_on_execute

boolean Set to true 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

string

max_forwards

integer Contains the current Max-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.

(warning) 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

string

media_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-8321 -Authenticate to see issue details 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

boolean

min_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 is 0 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

string

monitor_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_nameuser defined name for the error condition
number_of_hitsthe number of times the tone must be heard before considering it a fail
tone_detect_frequenciesthe frequencies to listen for (delimited by + instead of ,). See tone_detect

(warning) 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 reaches monitor_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_nameuser defined name for the error condition
number_of_hitsthe number of times the tone must be heard before considering it a fail
tone_detect_frequenciesthe frequencies to listen for (delimited by + instead of ,). See tone_detect

(warning) 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 of monitor_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

string

myid

string

nat_private_addr

string

If 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

string

If 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

boolean

new_name

string

no_throttle_limits

boolean You set this variable to true on your outbound calls to have them not count in sps

Usage

{no_throttle_limits=true}

nonexistantvar

string

original_caller_id_name

string

original_caller_id_number

string

original_destination_number

string

originate_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:

(info) 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 see ignore_diplay_updates which affect the processing of these variables.

Usage

(info) 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

(warning) 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

string

origination_privacy

string Sets privacy profile for caller.

Options:

  • screen
  • hide_name
  • hide_number

Usage

<action application="set" data="origination_privacy=hide_name"/>

origination_timeout

string deprecated Use originate_timeout.

origination_uuid

string You can specify the uuid of an originated call using origination_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!

(info) 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

string

other_loopback_leg_uuid

string

outbound_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

string

pa_ring_file

string

park_after_bridge

boolean If set to true, 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 no park_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"/>

See Also

pass_rfc2833

boolean If set, it passes RFC 2833 DTMF digits from one side of a bridge to the other, untouched. If unset, it decodes and re-encodes them before passing them on.

TODO RFC 2833 is obsoleted by RFC 4733.

Usage

<action application="set" data="pass_rfc2833=true"/>

passthru_ptime_mismatch

boolean If ptime 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

string

When set, allows playback of multiple files in sequence, which are separated by the specified delimiter.

Uses mod_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 digit

0. About

Allows you to set which DTMF tones will terminate

The default terminator is * (star).

1. Syntax

Syntax

playback_terminators=123456789*0# | any | none
  • none - undefines the terminator digit, meaning no DTMF tone will interrupt playback
  • any - 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 string
  • x (letter ex) - includes the following terminator digit in the returned string and also returns SWITCH_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

string

presence_data_cols

string You can customize the fields in FreeSWITCH's internal channels table by using the global variable presence_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 a PRESENCE_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 record
  • true - process records for both legs. This is the default.
  • a_only - only process records on the a leg
  • b_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

integer

profile_start_stamp

string

profile_start_uepoch

integer

progress_epoch

integer

progress_media_epoch

integer

progress_media_stamp

string

progress_media_uepoch

integer

progress_mediamsec

integer

progress_mediasec

integer

progress_mediausec

integer

progress_stamp

string

progress_time

string

progress_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:

  1. If a carrier is having issues with their platform, all calls might timeout.
  2. 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

integer

progressmsec

integer

progresssec

integer

progressusec

integer

proto_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

(info) Late Negotiation () must be enabled in sip profile for this to work in the dialplan.

<action application="set" data="proxy_media=true"/>

rdnis

string

read_codec

string readonly The negotiated codec of the inbound call leg.

read_rate

string

read_result

string

read_terminator_used

dtmf digit Contains the digit that the caller used to terminate a playback.

RECORD_APPEND

boolean Recording is appended to file. Set RECORD_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_BRIDGE_REQ

boolean Record session only when the channel is bridged. See FS-5127 -Authenticate to see issue details

Usage

<action application="set" data="RECORD_BRIDGE_REQ=true"/>

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"/>

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 to true. Useful for diagnostics.

record_fill_cng

string

Usage

<action application="set" data="record_fill_cng=1200"/>

RECORD_HANGUP_ON_ERROR

boolean When set to true 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_WRITE_ONLY

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%5Fdptools/mod%5Fdptools.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 to true. 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 be true, 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

RECORD_READ_ONLY

recording_follow_transfer

boolean Set to true if you want recording to continue after a transfer.

Usage

<action application="set" data="recording_follow_transfer=true"/>

recordings_dir

string

recovery_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

string

Returns the IP address of the remote media server.

remote_media_port

integer

remote_video_ip

string

remote_video_port

integer

ringback

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 ((warning) 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.

(info) 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.

(info) 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

string

rtcp_audio_interval_msec

integer Channel variable to set the interval in msec between each RTCP SR packet.

(warning) 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 is ext-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 to true (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_autoflush_during_bridge

boolean The same as rtp_autoflush, but is set during the bridge.

rtp_disable_hold

boolean When set to true the user may not put the call on hold.

Usage

<action application="set" data="rtp_disable_hold=true"/>

rtp_disable_vad_in

boolean

rtp_disable_vad_out

boolean

rtp_enable_vad_in

boolean

rtp_enable_vad_out

boolean

rtp_force_audio_fmtp

string Set the audio fmtp.

rtp_hold_timeout_sec

integer

rtp_jitter_buffer_during_bridge

boolean

Usage

<action application="set" data="rtp_jitter_buffer_during_bridge=true"/>
<action application="set" data="rtp_jitter_buffer_during_bridge=false"/>

rtp_manual_rtp_bugs

string

Usage

<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

boolean

rtp_sdes_suites

string

rtp_secure_media

string

Syntax: rtp_secure_media=<permission>[:<colon separated list of encryption suites>]

sip_secure_media is no longer implemented

permission:

  • mandatory - Accept/Offer SAVP negotiation ONLY
  • optional - Accept/Offer SAVP/AVP with SAVP preferred
  • forbidden - More useful for inbound to deny SAVP negotiation
  • deprecatedfalse - implies forbidden
  • deprecatedtrue - 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

string

Same syntax as rtp_secure_media: rtp_secure_media_inbound=<permission>[:<colon separated 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

string

Same syntax as rtp_secure_media: rtp_secure_media_outbound=<permission>[:<colon separated 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 colon-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

string

rtp_timeout_sec

integer

rtp_timer_name

string

run_dir

string

script_dir

string

sdp_m_per_ptime

boolean Adds a new m= 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 When rtp_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.

When greater than 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

string

sip

string

sip_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 with sip_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

string

sip_auto_answer_notify

string

sip_auto_answer_suppress_notify

string

sip_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 header Call-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

(info) 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):

(warning) 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:

(warning) 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

string sip_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 the Contact 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 the Contact 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 the Contact 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 only INVITEs 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.

(info) 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

string

sip_enable_soa

boolean For per call basis which can be set to false 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

string

sip_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

string

sip_force_full_to

string

sip_force_video_fmtp

boolean

sip_from_comment

string

sip_from_display

string The 'User' element of the SIP From: line

Usage

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 the From 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 the From 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 the From 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

string

sip_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 line Referred-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

string

sip_handle_full_to

string

sip_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:

ValueIncomingOutgoing
send_byeFS sent BYE to the caller (we hung up)FS sent BYE to the endpoint (we hung up)
recv_byeFS received BYE from the caller (they hung up)FS received BYE from the endpoint (they hung up)
send_refuseFS rejected the call (e.g. 4xx or 5xx)Endpoint rejected the call (e.g. 4xx or 5xx)
send_canceln/aFS aborted the call (we sent CANCEL)

sip_has_crypto

string deprecated Use rtp_has_crypto instead.

sip_header_name

string

sip_history_info

string

sip_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

boolean

sip_invite_call_id

string SIP Call-ID to use when originating a call.

Usage

<action application="set" data="sip_invite_call_id=mycustomcallid"/>

sip_invite_contact_params

string

sip_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 after user@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

string

sip_invite_full_from

string

sip_invite_full_to

string

sip_invite_params

string

sip_invite_record_route

string

sip_invite_req_uri

string Sets the URI in the header Request-Line INVITE when calling bridge or originate.

(warning) 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 header Route 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

string

sip_invite_to_uri

string Sets the URI in the header To 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

string

sip_local_url

string

sip_looped_call

boolean true 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.

(info) This variable can be set globally or per channel.

sip_nat_detected

string

sip_network_destination

string It is intended for use with devices registering behind a NAT where the Request-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_outgoing_call_id

string deprecated Replaced by sip_invite_call_id.

sip_p_rtp_stat

string

sip_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.

(warning) 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

string

sip_received_port

integer

sip_recover_contact

string

sip_recover_via

string

sip_recovery_break_rfc

string To NOT reverse the from and to on UAS Re-INVITEs. This breaks RFC.

(info) This variable can be set globally or per channel

sip_refer_reply

string

sip_referred_by_cid

string

sip_referred_by_user_stripped

string

sip_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

string

sip_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 to false.

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-5349 -Authenticate to see issue details

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

string

sip_rtp_txstat

string

sip_secure_media

string deprecated No longer implemented. Use rtp_secure_media instead.

sip_sticky_contact

string

sip_subject

string

sip_term_cause

string

sip_term_status

string

sip_to_comment

string

sip_to_host

string Hostname part of the To 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 the To 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

string

sip_to_user

string Username part of the To 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

string

sip_use_gateway

string

sip_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

string

sip_via_port

integer

sip_via_protocol

string

sip_via_rport

string

sip_video_fmtp

string

sip_video_pt

string

sip_wait_for_aleg_ack

string When you set the variable sip_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 to true, 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.

(warning) 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

string

socket_path

string

SOFIA_CRYPTO_MANDATORY_VARIABLE

string

SOFIA_HAS_CRYPTO_VARIABLE

string

sofia_profile_domain_name

string

sofia_profile_name

string The name of the profile of which the call originated (Leg A).

(warning) 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

string

SOFIA_REFER_TO_VARIABLE

string

SOFIA_REPLACES_HEADER

string

SOFIA_SECURE_MEDIA_CONFIRMED_VARIABLE

string

SOFIA_SECURE_MEDIA_VARIABLE

string

SOFIA_SESSION_TIMEOUT

string

sound_prefix

string Directory prefix where the sounds for phrase macros live, and where recordings are saved by default. See mod_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

string

spandsp_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

string

start_epoch

integer

start_stamp

string

start_uepoch

integer

storage_dir

string

stream_prebuffer

string

suppress_cng

boolean Sets a=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

string

switch_r_sdp

string readonly This variable holds the remote SDP for the current leg/channel.

Usage

(warning) 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

string

SWITCH_UUID_BRIDGE

string

temp_dir

string

temp_hold_music

string This variable specifies a hold music value that gets played to a caller only until they get transferred. After the transfer, the hold_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).

(warning) 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.

(warning) 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

string

tone_detect_sleep

string

transfer_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.

(info) Variable gets cleaned after bridge is destroyed and leg is transferred to the specified dialplan.

Usage

<action application="set