Channel Variables

From FreeSWITCH Wiki
Revision as of 04:10, 28 October 2010 by Nikko (Talk | contribs)

Jump to: navigation, search



There are a number of channel variables that can be set in the dialplan or your application to effect the progress or settings for a call. Channel variables can also be set in dialstrings (see below).

Channel Variables in the XML Dialplan

Channel variables are set, appropriately enough, with the set application like this:

<action application="set" data="var_name=var value"/>

Accessing channel variables requires the ${} syntax:

<action application="log" data="INFO The value in the var_name chan var is ${var_name}"/>

Channel Variables in Dial strings

The syntax of using { } versus [] is explained below.

{foo=bar} is *only* valid at the beginning of the dial string. It will set the same variables on every 
[foo=bar] goes before every individual dial string and will set the variable values specified for only 
this user's dial string channel.

The following example sets the foo variable for all channels implemented and chan=1 is specific to blah, while chan=2 is specific to blah2


Setting multiple variables can be accomplished by comma delimiting.


If you would like to have variables in [] override the same variables set in {}, you may set 'local_var_clobber=true' inside {}. For example:


In this example, the legs for and would be set to offer SRTP (RTP/SAVP) while would not receive an SRTP offer (she would see RTP/AVP instead).

Exporting Channel Variables in Bridge Operations

You can export a variable from one call leg (A) to the other call leg (B) by using the 'export_vars' variable which is a comma separated list of variables that you wish to propagate across calls. Usage:

<action application="set" data="export_vars=myvar,myvar2,foo,bar"/>

You can also set a variable on the (A) leg and add it to the export list in one step with the export application:

<action application="export" data="myvar=true"/>

Using Channel Variables in Dialplan Condition Statements

Channel variables can be used in conditions:

  • See this page for specifics.
  • Keep in mind that some channel variables may not be set during the dialplan parsing phase. See inline actions section of Dialplan_XML for more information.

Custom Channel Variables

Additionally, you may set any number of unique channel variables for your own purposes and even elect to log them to the CDR records. In order to set any channel variable, use the application "set" to effect the setting. You can also set channel variables on the command issued via XML-RPC or Event Socket by adding {myvar=myval,myvar1=myval1} ie

originate {ignore_early_media=true}sofia/ 15555551212

If the value you are setting has a space in it then you will need to enclose the value in quotes. An example of this is

originate {fax_ident=1231231234,fax_header='Fax Test'}sofia/gateway/outbound.fax/1004 &txfax(/tmp/fax.tiff)

Channel Variable Manipulation

Channel variables can be maniuplated for varied results. For example, you can trim bits and pieces of a channel variable, perhaps to get the first three digits of a phone number. See Manipulating Channel Variables for more information.

Info Application Variable Names (variable_xxxx)

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

Info variable name channel variable name Description
Channel-State state Current state of the call
Channel-State-Number state_number Integer
Channel-Name channel_name Channel name
Unique-ID uuid uuid of this channel's call leg
Call-Direction direction Inbound or Outbound
Answer-State state .
Channel-Read-Codec-Name read_codec the read codec variable mean the source codec
Channel-Read-Codec-Rate read_rate the source rate
Channel-Write-Codec-Name write_codec the destination codec same to write_codec if not transcoded
Channel-Write-Codec-Rate write_rate destination rate same to read rate if not transcoded
Caller-Username username .
Caller-Dialplan dialplan user dialplan like xml, lua, enum, lcr
Caller-Caller-ID-Name caller_id_name .
Caller-Caller-ID-Number caller_id_number .
Caller-ANI ani ANI of caller, frequently the same as caller ID number
Caller-ANI-II aniii ANI II Digits (OLI - Originating Line Information), if available. Refer to:
Caller-Network-Addr network_addr IP address of calling party
Caller-Destination-Number destination_number Destination (dialed) number
Caller-Unique-ID uuid This channel's uuid
Caller-Source source Source module, i.e. mod_sofia, mod_openzap, etc.
Caller-Context context Dialplan context
Caller-RDNIS rdnis Redirected DNIS info. See transfer application
Caller-Channel-Name channel_name .
Caller-Profile-Index profile_index .
Caller-Channel-Created-Time created_time .
Caller-Channel-Answered-Time answered_time .
Caller-Channel-Hangup-Time hangup_time .
Caller-Channel-Transfer-Time transfer_time .
Caller-Screen-Bit screen_bit .
Caller-Privacy-Hide-Name privacy_hide_name .
Caller-Privacy-Hide-Number privacy_hide_number This variable tells you if the inbound call is asking for CLIR (either with anonymous method or Privacy:id method)
variable_sip_received_ip sip_received_ip .
variable_sip_received_port sip_received_port .
variable_sip_authorized sip_authorized .
variable_sip_mailbox sip_mailbox .
variable_sip_auth_username sip_auth_username .
variable_sip_auth_realm sip_auth_realm .
variable_mailbox mailbox .
variable_user_name user_name .
variable_domain_name domain_name .
variable_record_stereo record_stereo .
variable_accountcode accountcode Accountcode for the call. This is an arbitrary value. It can be defined in the user variables in the directory, or it can be set/modified from dialplan. The accountcode may be used to force a specific CDR CSV template for the call.
variable_user_context user_context .
variable_effective_caller_id_name effective_caller_id_name .
variable_effective_caller_id_number effective_caller_id_number .
variable_caller_domain caller_domain .
variable_sip_from_user sip_from_user .
variable_sip_from_uri sip_from_uri .
variable_sip_from_host sip_from_host .
variable_sip_from_user_stripped sip_from_user_stripped .
variable_sip_from_tag sip_from_tag .
variable_sofia_profile_name sofia_profile_name .
variable_sofia_profile_domain_name sofia_profile_domain_name .
variable_sip_req_params sip_req_params .
variable_sip_req_user sip_req_user .
variable_sip_req_uri sip_req_uri .
variable_sip_req_host sip_req_host .
variable_sip_to_params sip_to_params .
variable_sip_to_user sip_to_user .
variable_sip_to_uri sip_to_uri .
variable_sip_to_host sip_to_host .
variable_sip_contact_params sip_contact_params .
variable_sip_contact_user sip_contact_user .
variable_sip_contact_port sip_contact_port .
variable_sip_contact_uri sip_contact_uri .
variable_sip_contact_host sip_contact_host .
variable_sip_invite_domain sip_invite_domain .
variable_channel_name channel_name .
variable_sip_call_id sip_call_id .
variable_sip_user_agent sip_user_agent .
variable_sip_via_host sip_via_host .
variable_sip_via_port sip_via_port .
variable_sip_via_rport sip_via_rport .
variable_presence_id presence_id .
variable_sip_h_P-Key-Flags sip_h_p-key-flags This will contain the optional P-Key-Flags header(s) that may be received from calling endpoint.
variable_switch_r_sdp switch_r_sdp The whole SDP received from calling endpoint.
variable_remote_media_ip remote_media_ip .
variable_remote_media_port remote_media_port .
variable_write_codec write_codec .
variable_write_rate write_rate .
variable_endpoint_disposition endpoint_disposition .
variable_dialed_ext dialed_ext .
variable_transfer_ringback transfer_ringback .
variable_call_timeout call_timeout .
variable_hangup_after_bridge hangup_after_bridge .
variable_continue_on_fail continue_on_fail .
variable_dialed_user dialed_user .
variable_dialed_domain dialed_domain .
variable_sip_redirect_contact_user_0 sip_redirect_contact_user_0 .
variable_sip_redirect_contact_host_0 sip_redirect_contact_host_0 .
variable_sip_h_Referred-By sip_h_referred-by .
variable_sip_refer_to sip_refer_to .
variable_max_forwards max_forwards .
variable_originate_disposition originate_disposition .
variable_read_codec read_codec .
variable_read_rate read_rate .
variable_open open .
variable_use_profile use_profile .
variable_current_application current_application .
variable_ep_codec_string ep_codec_string This variable is only available if late negotiation is enabled on the profile. It's a readable string containing all the codecs proposed by the calling endpoint. This can be easily parsed in the dialplan.
variable_disable_hold disable_hold This variable when set will disable the hold feature of the phone.
variable_sip_acl_authed_by sip_acl_authed_by This variable holds what ACL rule allowed the call.

${variable} vs. $${variable}

${variables} are channel variables that may be set in the dialplan, application or directory that effect progress or settings for the call.

$${variables} are expanded when the master freeswitch.xml is compiled. This happens when you start FreeSWITCH, or when reloadxml is called.

The key is that $${variables} are evaluated once by the preprocessor, and ${variables} are evaluated fresh each time they are executed (for example when a call connects).

CDR related


Indicates how to process CDR records.

Can be undefined or set to "false", "true", "a_only", "b_only"

  • false - indicates to not process the record.
  • true - or undefined indicates the default behavior which is to process all CDR records.
  • a_only - indicates to only process CDR records on the inbound leg of a call.
  • b_only - indicates to only process CDR records on the outbound leg of a call.

This variable is unconditionally exported


<action application="set" data="process_cdr=a_only"/>


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.


<action application="set" data="accountcode=custom"/>

Hangup Causes


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.


<action application="log" data="1 B-leg hangup cause: ${bridge_hangup_cause}"/>


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.


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


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.


<action application="log" data="1 A-leg hangup cause: ${hangup_cause}"/>


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.


<action application="log" data="1 A-leg hangup Q850 cause: ${hangup_cause_q850}"/>


This variable contains the value of who sent the SIP BYE message. Some examples from XML CDRs:


Interpretation of these values differs on incoming and outgoing calls since FreeSWITCH is at different ends of the session.

Value Incoming Outgoing
send_bye FS sent BYE to the caller (we hung up) FS sent BYE to the endpoint (we hung up)
recv_bye FS received BYE from the caller (they hung up) FS received BYE from the endpoint (they hung up)
send_refuse FS rejected the call (e.g. 4xx or 5xx) Endpoint rejected the call (e.g. 4xx or 5xx)
send_cancel n/a FS aborted the call (we sent CANCEL)


Look in CDR for the value; only valid after call has ended.

DTMF Related


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

Note: this has no effect when bypass_media or proxy_media is set.


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


For inband DTMF, Misc. Dialplan Tools start_dtmf must be used in the dialplan.


<action application="set" data="dtmf_type=info"/>


<action application="set" data="dtmf_type=rfc2833"/>


<action application="set" data="dtmf_type=none"/>

Media Handling


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:



user defined name for the error condition


the number of times the tone must be heard before considering it a fail


the frequencies to listen for (delimited by + instead of ,). See tone_detect

NOTE: this variable only works when ignore_early_media is set to true.


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


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:



Optional? user-defined name for the error condition


the number frequencies for the tone detector to find before considering it a hit. 1:400.0+480.0 means the ring count is incremented if 400hz OR 480hz is detected. 2:400.0+480.0 means the ring count is incremented if 400 hz AND 480 hz are detected.


the frequencies to listen for (delimited by + instead of ,). Examples are 400.0+480.0 [for a US Ring] See tone_detect

NOTE: this variable only works when ignore_early_media is not present.


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

Timeout Related


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


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


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


<action application="bridge" data="[leg_timeout=15]user/hastoanswerquickly/,[leg_timeout=60]user/"/>


Controls wether or not a bridge should continue after timing out. Default value is false. This variable resets the timeout after each | default is to die on first timeout


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

Locale Related


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.


<action application="set" data="default_language=fr"/>


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/ for the standard list of Linux timezones).

Note that this channel variable is only respected by the phrase layer -- ie, if you're using the 'say' application to announce times, this will work fine.

You can set the time zone Globally for Freeswitch in /conf/vars.xml by adding this line: <X-PRE-PROCESS cmd="set" data="timezone=America/Toronto"/> (of course replace the 'America/Toronto' with your own time zone.

If you would like to specify the time zone in the dialplan add <action application="set" data="timezone=America/Toronto"/> to your dialplan. (again replace with the proper timezone)

Finally you can specify a time zone for a particular extension in /conf/directory/default/'extension'.xml


<action application="set" data="timezone=GMT0"/>


<action application="set" data="timezone=America/New_York"/>

Bridge Related


Execute an API command after bridge.


Paging to PA System via Portaudio (w/ chime before and after announcement) [1]


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.

In the example below, there is no way to reach extension 333 without auto_hunt.

Usage: In 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"/>

<extension name="333">
  <condition field="destination_number" expression="^333$">
    <action application="info"/>


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: Set bridge_early_media before the bridge, or in the dial string for the bridge.


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

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


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.


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

or Q.850 cause codes,

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


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;


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


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.


<action application="set" data="failure_causes=USER_BUSY,NO_ANSWER"/>

or Q.850 cause codes,

<action application="set" data="failure_causes=487"/>


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


<action application="bridge" data="{force_transfer_context=some_context}sofia/gateway/gw_name/12345"/>


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


Example needed! Please contribute one.


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.


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


Set to true to have one-legged loopback channels "bow out" of the call.


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


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.


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


If set to true, it will park the call after bridge returns. This is checked before transfer_after_bridge and hangup_after_bridge.

Default: false


<action application="set" data="park_after_bridge=true"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


UUID of the channel this channel is bridged/bonded to. Not present on a one-legged call.


Example needed! Please contribute one.

See also:


When set to true causes the system to move on in the dialplan if it hits a bad b-leg. Default is false because this behavior is probably not recommended.

You may find this variable useful when implementing Dialplan_FollowMe


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

Conference Related


Contains the conference_member_id value for any conference to which the channel may be connected.

Code Execution Related


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


<action application="set" data="exec_after_bridge_app=transfer"/>
<action application="set" data="exec_after_bridge_arg=2102"/>


Argument passed to exec_after_bridge_app.


<action application="set" data="exec_after_bridge_app=transfer"/>
<action application="set" data="exec_after_bridge_arg=2102"/>


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


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


Execute a command when the called party rings.


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


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.


Example needed! Please contribute one.


Arguments to be used with bridge_pre_execute_aleg_app.


Example needed! Please contribute one.


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.

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


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


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.


<action application="set" data="failed_xml_cdr_prefix=failinggw" />	


Arguments to be used with bridge_pre_execute_bleg_app


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


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


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

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


Execute an API command on hangup.


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


Allows channel variables to be accessible in the api_hangup_hook that gets executed for the channel.


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

See Lua#Special_Case:_env_object for an example of how to use this.


If set to true, the leg will only be intercepted if the channel is not bridged to anyone.

Default: false


<action application="set" data="intercept_unbridged_only=true"/>
<action application="intercept" data="myUUID"/>

Caller ID Related


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


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.


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

Informational Tip

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



<action application="set" data="effective_caller_id_name=Bob Smith"/>


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


<action application="set" data="effective_caller_id_number=9185551212"/>


  • Modify how the Caller ID will show up in SIP header of the outbound leg.


Send no extra caller id info (Caller ID will be in the SIP From):


Send Remote-Party-ID (default)


Send P-Asserted-Identity


Send Remote-Party-ID with chosen content



Prevents FreeSWITCH when it receives 183 from leg-B to automatically insert RPID before sending 183 to leg-A.


<action application="set" data="sip_cid_in_1xx=false"/>

Callee ID Related



DEPRECATED. Use variable origination_callee_id_name instead


Set on the inbound leg to control what caller ID number appears in the caller phone's display.


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

If you find using set doesn't work, try using export instead.


Per-channel hold music. Supports all audio formats and audio streams. The hold_music variable can also be set globally at vars.xml.


<action application="set" data="hold_music=/sounds/holdmusic.wav" />

You can also set your hold_music to the special value "indicate_hold" instead of a music source and it will pass the hold req through but not the SDP.


<action application="set" data="hold_music=silence" />

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

Call Recording Related

These variables all relate to call recording. See also Misc._Dialplan_Tools_record_session












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. These variables take the form of:

<action application="set" data="record_post_process_exec_api=some_api_app:api_app args" />

Codec Related


Sets the absolute codec string to use (nothing will be appended).


<action application="set" data="absolute_codec_string=PCMU,GSM"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


Sets the base codec string to use.


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


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.


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


Read only. The negotiated codec of the inbound call leg.


Read only. The negotiated codec of the outbound call leg.


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.


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

Note: It may also be set globally in vars.xml.


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.



<action application="set" data="conference_enforce_security=false"/>
<action application="conference" data="3000"/>


originate {conference_enforce_security=true}sofia/internal/1001 &conference(3000)

SIP related variables


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


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


Contains the name of the ACL node that authorized this call.




Contains the ACL auth token for the current call.




Set the from domain in leg (B).


<action application="bridge" data="{sip_invite_domain=${sip_from_host}}sofia/gateway/gw1/$"/>


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.




From: <sip:5552345678@sonus:5060;otg=mytrunk>;tag=blah


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.


<action application="bridge" data="{sip_network_destination=sip:5551234567@}sofia/external/5551234567@"/>


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.


originate {sip_auth_username=<your_user_name>,sip_auth_password=<your_password>}sofia/external/1xxxxxxx@ &echo


For mod_sofia use with sip_auth_username to answer auth challenges without defining a full gateway.


originate {sip_auth_username=<your_user_name>,sip_auth_password=<your_password>}sofia/external/1xxxxxxx@ &echo



DEPRECATED. Use variable origination_callee_id_name instead


Set on the inbound leg to control what caller ID number appears in the caller phone's display.


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

If you find using set doesn't work, try using export instead.


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

NOTE: RFC 3261 specifies that compliant endpoints SHOULD route based on the Request URI, not the URI in To:


<action application="bridge" data="{}sofia/external/33334444%"/>


 From: "" <sip:0000000000@>;tag=N6K579y4g6j0D
 To: <sip:33334444@>


Sets the uri in the header To when calling bridge or originate.


 originate {sip_invite_to_uri=<>}sofia/internal/33334444@ &park


 INVITE sip:33334444@ SIP/2.0
 From: "" <sip:0000000000@>;tag=N6K579y4g6j0D
 To: <>

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@^11112222 &park


 INVITE sip:33334444@ SIP/2.0
 From: "" <sip:0000000000@>;tag=Qr6pB00BBrZ5m
 To: <sip:11112222@@>


When set, this directs FreeSWITCH to remove itself from the SIP signaling path if it can safely do so.


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


If set will make playback and speak use a timer to clock the audio instead of the read.


<action application="set" data="timer_name=soft"/>


See link

SDP Manipulation

When set, these variable change the SDP headers. (not for the faint of heart)


  • Remote SDP (for the current leg/channel)
  • Rewriting SDP:
<action application="set">
<![CDATA[switch_r_sdp=(sdp here)


  • (Local SDP)
  • Although this variable is defined in switch_types.h it is not used anywhere in the FreeSwitch code. (It should be removed for the source and from this page.)


  • "B-leg" remote SDP
  • Known as SWITCH_B_SDP_VARIABLE in mod_sofia and the core switch code.
  • 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. ("read-only")


This may be used to append audio parameters to the SDP sent to B-leg.

It should/must be set before bridging.


<action application="export" data="sip_append_audio_sdp=a=fmtp:18 annexb=no"/>


Ignoring 183 w/o SDP. This option is not for normal basic call flow.


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

FIFO related variables


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.


<action application="set" data="transfer_after_bridge=1000"/>


<action application="set" data="transfer_after_bridge=1000:XML:default"/>

(Note the : separator)


Import list of variables from the caller to the consumer.


<action application="set" data="fifo_caller_consumer_import=var1,var2"/>


Import list of variables from the consumer to the caller


<action application="set" data="fifo_consumer_caller_import=var1,var2"/>


Description goes here


Example needed


For reporting purposes, i.e. in the CDRs, the variable will contain "consumer" or "caller" depending upon the call leg.



Playback related variables


Allows you to set which DTMF tones, if pressed during the playback of a file, will stop it. The default terminator is *. Keyword 'none' disables on-key termination.

 <action application="set" data="playback_terminators=#*"/>


Directory prefix where the sounds lives.


Contains the digit that the caller used to terminate a playback. Is undef when a new playback is called.


Contains the number of milliseconds of the length of the audio file just played back.


Contains the number of samples in the audio file just played back.


How long to pause after a file is played. Default is 250 milliseconds.

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


When set allows playback of multiple files in sequence, by separating them with the delimiter.

For example, 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"/>


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

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

This variable was added in SVN rev 14102.

Originate related variables


Number of retries before giving up on originating a call (default is 0).


Determines how long FreeSWITCH is going to wait for a response from the invite message sent to the gateway.

<action application="set" data="originate_timeout=2"/>

This is very useful if you are using multiple gateways within your dial plan.. so if your dial string is:

<action application="bridge" data="sofia/default/$1@|sofia/default/$1@"/>

In this example FreeSWITCH will wait 2 seconds for the to respond to the invite message before trying the next gateway.


This will set how long FreeSWITCH is going to wait between sending invite messages to the receiving gateway.

<action application="set" data="originate_retry_sleep_ms=500"/>

Using the value of 500 FreeSWITCH will wait 500ms between sending invite messages to the called gateway.


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.


Implemented in revision 14650 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)


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


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.


<action application="set" data="origination_caller_id_name=Uncle Sam"/>


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.


<action application="set" data="origination_caller_id_number=9185551212"/>

But, if you want to relay the Caller ID Number of an incoming PSTN call via FXO gateway, comment out this variable.


Sets privacy profile for caller. Options are "screen", "hide_name", "hide_number".


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


Sets the codec for calls originated from LEG A (setting the codec for LEG B)


<action application="set" data="originator_codec=PCMU"/>


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.


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!

originate [origination_uuid=....]sofia/blah/blah

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.


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.

<action application="bridge" data="sofia/profile/dest1,[leg_delay_start=10]sofia/profile/dest2,[leg_delay_start=15]sofia/profile/dest3"/>

RTP/media related variables


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.

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

See also: Bypass Media Overview


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.


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.

Note: Late negotiation (<param name="inbound-late-negotiation" value="true"/> ) must be enabled in sip profile for this to work in the dialplan

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

See also: Proxy Media


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.


The same as rpt_autoflush, but is set during the bridge.


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


Add {disable_rtp_auto_adjust=true} in your dial string.


This is the maximum time we will wait before we get media (wether its early media, ringing or answer)


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

See also Early_media


  • Introduced in build 15057

Timeout in seconds how long to tolerate a bridge that is in early media without being answered (can be set on either leg)


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

See also Early_media


Controls if the call returns on early media or not. Default is false.


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

See also Early_media


This will set the unanswered aka (early media) calls. The following example uses the US ring tone defined in ~/vars.xml


<action application="set" data="ringback=$${us-ring}"/>


When set, ringback will not wait for indication before sending ringback tone to calling party


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


This will set the ring tone for answered calls. This is any call that has been setup. One example would be the tone to play during transfer. The following example uses the French ringtone definte in ~/vars.xml


<action application="set" data="transfer_ringback=$${fr-ring}"/>


This is the channel variable for disable-hold.



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

Camp-on related variables

Camping is used when bridging a call. It will basically park (aka camp) your channel to music on hold while it attempts to bridge the call.


Controls whether camping is enabled or not.

Default: false


<action application="set" data="campon=true"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


Controls how many times the bridge will be retried while camping.

Default: 100


<action application="set" data="campon=true"/>
<action application="set" data="campon_retries=13"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


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


<action application="set" data="campon=true"/>
<action application="set" data="campon_timeout=20"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


Controls how long to wait before starting a retry.

Default: 10


<action application="set" data="campon=true"/>
<action application="set" data="campon_sleep=30"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


Controls camping during bridge app (testing needed)


<action application="set" data="campon"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


Controls camping during bridge app (testing needed)


<action application="set" data="campon"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


Controls camping during bridge app (testing needed)


<action application="set" data="campon"/>
<action application="bridge" data="sofia/gateway/myprovider/5551231234"/>


If you don't set the hold_music variable, this variable controls hold music while camping.


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


DTMF digit that breaks the campon loop and skips directly to fallback extension

Default: none


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


File to play back after the first bridge fails (rg to announce what key to press to skip to fallback extension)

Default: none


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

Answer confirmation variables


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

<action application="set" data="group_confirm_file=/usr/local/freeswitch/sounds/take_call_question.wav" />
<action application="set" data="group_confirm_key=1" />

Through this is the standard usage of these variables (group_confirm_key and group_confirm_file), they can be used in a more flexible manner. Please see Freeswitch_IVR_Originate#Answer_confirmation.


see group_confirm_file


If set, cancels a leg timeout after the call is answered.

More detail:

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

Normally, a timeout on the leg will apply to phases 1 and 2.

However, if you do

 <action application="set" data="group_confirm_cancel_timeout=1"/>

then the timeout will only apply to phase 1. So, once the phase 1 is crossed, leg_timeout counter stops.

See Also:

Voicemail Related Variables










If set, fire an event when speech is detected.

System Related Variables


This variable is used to leverage the installation directory in order to avoid hard-coding it the xml.


<action application="system" data="$${base_dir}/scripts/"/>

OpenZap Related Variables


openzap span number


openzap channel number