Skip to main content

Switch core variables

About​

This is a list of channel variables defined in FreeSWITCH core.

Timestamp variables​

The following variables are set by FreeSWITCH after the channel is hung up, and contain timestamps for various state changes for a channel.

State changeVariable (epoch seconds)Variable (epoch microseconds)Variable (Date and time)
caller profile createdprofile_start_epochprofile_start_uepochprofile_start_stamp
startedstart_epochstart_uepochstart_stamp
answeredanswer_epochanswer_uepochanswer_stamp
bridgedbridge_epochbridge_uepochbridge_stamp
last_holdlast_hold_epochlast_hold_uepochhold_stamp
resurrectedresurrect_epochresurrect_uepochresurrect_stamp
progressprogress_epochprogress_uepochprogress_stamp
progress_mediaprogress_media_epochprogress_media_uepochprogress_media_stamp
hungupend_epochend_uepochend_stamp

Accumulated timers​

The following variables display various time-related information after the channel is hung up, in different formats:

ValueVariable (seconds)Variable (milliseconds)Variable (microseconds)
call duration (from channel creation to hangup)durationmdurationuduration
wait (from creation to bridged state)waitsecwaitmsecwaitusec
total hold timehold_accum_secondshold_accum_mshold_accum_usec
billing duration (from answered to hungup)billsecbillmsecbillusec
leg billing duration (from created to hungup)flow_billsecflow_billmsecflow_billusec
answer waiting (from creation to answered)answersecanswermsecanswerusec
call progress waiting (from creation to progress)progresssecprogressmsecprogressusec
media progress waiting (from creation to progress_media)progress_mediasecprogress_mediamsecprogress_mediausec

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

Per-leg Dialstring:

<action application="bridge" data=[leg_timeout=60,origination_caller_id_number=918039251,
absolute_codec_string=^^:PCMA:PCMU]sofia/gateway/gateway1/${destination_number}|[leg_timeout=60,
absolute_codec_string=PCMA]sofia/gateway/gateway2/${destination_number}"/>

Global Dialstring:

<action application="bridge" data="{absolute_codec_string=PCMA}sofia/gateway/gateway2/${destination_number}"/>

api_after_bridge​

Execute an API command after bridge.

Usage:

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

Execute an API command on hangup.

Usage:

<action application="set" data="api_hangup_hook=jsrun cleanup.js ${uuid}"/>

See also:

  • session_in_hangup_hook
  • api_reporting_hook - like api_hangup_hook but after reporting state (both honor session_in_hangup_hook)

api_on_answer​

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

Or,

<action application="bridge" data="{api_on_answer='uuid_broadcast ${uuid} beep.wav both'}sofia/gateway/provider/5551231234"/>

api_on_media​

Execute a FreeSWITCH API 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}"/>

api_on_startup​

Execute an api (not an application) when the switch starts up.

Usage:

<X-PRE-PROCESS cmd="set" data="api_on_startup=sofia recover"/>

asr_intercept_dtmf​

If set to true, DTMF input is interpreted alongside the automatic speech recognition.

bind_meta_key​

Selects the meta key to use with the mod_dptools: bind_meta_app dialplan application (or any other application that utilizes switch_ivr_bind_dtmf_meta_session core function for binding application calls to DTMF input).

Usage:

<action application="set" data="bind_meta_key=#"/>

bridge_answer_timeout​

Timeout in seconds how long to tolerate a bridge that is in early media without being answered (can be set on either leg). Useful when you want to pass early media from b-leg to a-leg but also use ${call_timeout}. This will consider the bridge failed if a 200 OK is not received before the bridge_answer_timeout.

Usage:

<action application="set" data="bridge_answer_timeout=20"/>

bridge_channel​

Upon a successful bridge, FreeSWITCH sets bridge_channel variable on both legs to indicate the other leg's channel name.

bridge_early_media​

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

Usage:

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

bridge_filter_dtmf​

Setting this variable to true will prevent DTMF digits received on this channel when bridged from being sent to the other channel.

Usage:

You can set this variable in the dialplan before answering or inline as part of a dialstring.

Example dialplan usage:

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

Example dialstring usage:

{bridge_filter_dtmf=true}sofia/default/blah@baz.com

bridge_generate_comfort_noise​

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.

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​

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​

Command or API to be executed on the A leg before bridging the two channels.

Note: this is executed AFTER the call is setup but BEFORE the media (audio) is bridged.

bridge_pre_execute_aleg_data​

Arguments to be used with bridge_pre_execute_aleg_app.

bridge_pre_execute_bleg_app​

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 wake-up call.

Can also be used to bind a DTMF event to an app on the B leg of a call so that it can survive a transfer.

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

Arguments to be used with bridge_pre_execute_bleg_app.

bridge_terminate_key​

Allows you to bind a key and the bridge will terminate if the dtmf matches

bridge_to​

When a bridge is initiated, this variable is set on both legs to indicate the other leg's channel UUID.

bridge_uuid​

Upon a successful bridge, FreeSWITCH sets bridge_uuid variable on both legs to indicate the other leg's channel UUID.

bypass_media​

When set to true, all the media address of the far end of the originating leg will be passed to the far end of the new call leg and vice versa, so the signaling goes through FreeSWITCH, but the media is point-to-point.

Usage:

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

bypass_media_after_bridge​

This is useful for bypassing media after bridging has happened.

Verto note

bypass_media_after_bridge is not implemented in Verto.

Usage:

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

It could be useful for an already established channel and doing a later bypass.

 uuid_setvar <uuid> bypass_media_after_bridge true
 uuid_broadcast <uuid> bridge::<endpoint>

cache_speech_handles​

If set to true, the TTS engine handle is cached for subsequent use instead of being re-created again on every use.

call_timeout​

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.

Default Value: 60

Usage:

<action application="set" data="call_timeout=20"/>

Notes:

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

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.

caller_id​

After the call is hung up, FreeSWITCH sets this variable to reflect the caller ID number or a combination of caller name and the number.

caller_id_name​

The caller id name set by the inbound call, not a real variable. Practically it is read only.

caller_id_number​

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.

channel_name​

This variable is set by various modules and contains a string that non-uniquely describes the channel. It can also be changed by set_name dialplan application.

codec_string​

Sets the base codec string to use.

Usage:

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

continue_on_fail​

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

or,

<action application="set" data="continue_on_fail=NORMAL_TEMPORARY_FAILURE,USER_BUSY,NO_ANSWER,NO_ROUTE_DESTINATION"/>

or Q.850 cause codes,

<action application="set" data="continue_on_fail=3,17,18,27"/>

copy_json_cdr​

Copies the B leg's JSON CDR into A leg's variable named b_leg_cdr as an URL-encoded string. 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_json_cdr=true} user/${dialed_extension}@${domain_name}"/>

See also:

copy_xml_cdr​

Copies the B leg's XML CDR into A leg's variable named b_leg_cdr as an URL-encoded string. 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}"/>

See also:

current_application​

The name of an application that is currently being executed on the channel.

current_application_data​

The arguments of a currently executed application

current_application_response​

Response string returned by the last executed application.

default_language​

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

destination_number​

This variable indicates the call destination string.

dialed_domain​

This variable is set by several commands and applications, such as bridge and originate, when the call is targeted to a directory user. It contains the domain name that is associated with the user.

dialed_user​

Analogous to dialed_domain, dialed_user contains the user name when the call is connected too a directory user.

digits_dialed​

After the channel is hung up, this variable contains DTMF digits which were dialed during the call, or "none" if no digits were dialed. The variable digits_dialed_filter may define a regexp filter that would be applied to the dialed digits.

digits_dialed_filter​

This variable defines a regexp filter that is applied to dialed DTMF digits before they are exposed in digits_dialed variable.

direction​

This variable is set to "inbound" or "outbound", depending on the direction of the call leg.

disable_app_log​

By default, each executed application is stored in the session object, and written into XML CDR or JSON CDR at the end of a call. This variable, if set to "true", disables this behavior.

rtp_disable_hold​

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

disable_rtp_auto_adjust​

Disable rtp auto adjust if it not behaves 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 (port?) 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 (port?).

DISPLACE_HANGUP_ON_ERROR​

When set to "true", this channel variable will cause the call to hangup if there is an error when trying to uuid_displace the call. The default is "false".

domain_name​

In an inbound channel from an authenticated user, domain_name and user_name are reflecting the domain and the user names from the directory, respectively.

drop_dtmf​

Set this on an inbound channel before answer or on an outbound channel before bridge or originate in order to prevent DTMF events from being sent to the channel.

Usage:

<action application="set" data="drop_dtmf=true"/>
<action application="answer"/>

or,

<action application="export" data="nolocal:drop_dtmf=true"/>
<action application="bridge" data="sofia/internal/100@1.2.3.4"/>

or,

<action application="bridge" data="{drop_dtmf=true}sofia/internal/100@1.2.3.4"/>

drop_dtmf_masking_file​

If drop_dtmf is set to "true", drop_dtmf_masking_file may point to a playback string which will be played instead of DTMF on the other leg.

drop_dtmf_masking_digits​

If drop_dtmf is set to "true", drop_dtmf_masking_digits may contain a string of digits which will be played instead of each DTMF tone on the other leg.

dtmf_type​

Sets the way DTMF is transmitted into the channel. For inband DTMF, Misc. Dialplan Tools start_dtmf must be used in the dialplan.

Accepted values: "rfc2833", "info", "none"

eavesdrop_announce_id, eavesdrop_announce_macro​

In eavesdrop application, as well as in other applications that use eavesdrop (spy, three_way, and some others), if the variable eavesdrop_announce_id is defined in the joining channel, the announcement macro is played into the eavesdropped session before the third party joins in. By default, the phrase macro eavesdrop_announce is played with the value of eavesdrop_announce_id variable as the input argument. The name of the macro can be changed by defining the variable eavesdrop_announce_macro in the joining channel.

eavesdrop_group, eavesdrop_require_group​

In eavesdrop application, as well as in other applications that use eavesdrop, if eavesdrop_require_group is specified, eavesdrop only works with channels that have an eavesdrop_group channel variable set to the same name.

effective_caller_id_name​

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

For Snom 370/820 users:

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​

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

enable_file_write_buffering​

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

Related 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, heartbeat_fire_on_set, heartbeat_use_scheduler​

These variables control the firing of SESSION_HEARTBEAT events for a given session.

enable_heartbeat_events can have an integer value or "true". The integer value defines the frequency of heartbeat events. If set to "true", the frequency is set to 60 seconds.

If heartbeat_fire_on_set is set to "true", the heartbeat event is fired immediately after answering or after receiving media.. Otherwise, it's scheduled for one period in the future.

If heartbeat_use_scheduler is set to "true", the heartbeat is forced to use the scheduler rather than the media stream and also make it auto-change between modes when going in and out of the media path in FS core.

ep_codec_prefer_sdp​

If set to true, the B leg prefers the codecs proposed by the A leg

ep_codec_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 enable on the SIP profile.
NOTE: 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, exec_after_bridge_arg​

Execute an application command after the bridge has been terminated. The application is specified by exec_after_bridge_app, and exec_after_bridge_arg specifies the arguments. 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"/>

See also:

execute_on_answer​

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

or, 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>

If you need to set multiple execute_on_answers, the following syntax allows multiple applications for a single condition. Example:

<action application="set" data="execute_on_answer_1=app1 arg"/>
<action application="set" data="execute_on_answer_2=app2 arg"/>
<action application="set" data="execute_on_answer_3=app3 arg"/>

execute_on_media​

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

execute_on_media_timeout​

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​

Executes code on successful origination. Use the '<app> <arg>' format to execute in the origination thread or use '<app>::<arg>' to execute asynchronously.

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_pre_answer​

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

execute_on_ring​

Execute a command when the called party rings.
Usage:

<action application="set" data="nolocal:execute_on_ring=lua markring ${uuid}"/>

export_vars​

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. Note: This is useful to transfer information from a-leg (INVITE) to the future b-leg of REFER.

See also:

fail_on_single_reject​

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.

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

or,

<action application="set" data="fail_on_single_reject=USER_BUSY"/>

or,

<action application="set" data="fail_on_single_reject=!NORMAL_CIRCUIT_CONGESTION"/>

or to use a list,

<action application="set" data="fail_on_single_reject=^^:CALL_REJECTED:NORMAL_CLEARING:USER_BUSY"/>

or for negated list,

<action application="set" data="fail_on_single_reject=!^^:ALLOTTED_TIMEOUT:NETWORK_OUT_OF_ORDER"/>