Channel Variables

From FreeSWITCH Wiki
Jump to: navigation, search

Contents

Introduction

There are a number of channel variables that can be set in the dialplan or your application to affect 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}"/>
<condition field="${var_name}" expression="some text">

Scoped Variables

- Channel variables used to be global to the session.
- With Scoped variables, you can now set variables that only exist for the duration of that single application execution and any subsequent applications under it.
- Applications can leverage this concept to use named input params

As of June 15 (git commit b2c3199f) you may now have scoped variables that will stay in effect only for the duration of a given dialplan application. Example:

<action application="log" data="INFO myvar is '${myvar}'"/>
<action application="log" data="%[myvar=Hello]INFO myvar is '${myvar}'"/>
<action application="log" data="INFO myvar is '${myvar}'"/>
<action application=”myapp” data=”%[var1=val1,var2=val2]mydata”/>

Channel Variables in Dial strings

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

  • {foo=bar} is only valid at the beginning of the dial string. It will set the same variables on every channel, but does not do so for enterprise bridging/originate.
  • <foo=bar> is only valid at the beginning of the dial string. It will set the same variables on every channel, including all those in an enterprise bridging/originate.
  • [foo=bar] goes before each individual dial string and will set the variable values specified for only this 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
{foo=bar}[chan=1]sofia/default/blah@baz.com,[chan=2]sofia/default/blah2@baz.com
  • Setting multiple variables can be accomplished by comma delimiting:
[var1=abc,var2=def,var3=ghi]sofia/default/blah@baz.com
  • If you would like to have variables in [] override the same variables set in {}, you may set 'local_var_clobber=true' inside {}. For example:
{local_var_clobber=true,sip_secure_media=true}sofia/default/blah1@baz.com|sofia/default/johndoe@example.com|[sip_secure_media=false]sofia/default/janedoe@acme.com

You must also set this local_var_clobber variable to true when you want to override channel variables that have been exported to your b-legs in your dialplan.

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

Handling Variables With Commas

Since commas are the default delimiter inside of {} and [] it is necessary to have an alternate means of delimiting values that actually contain commas.

To set a variable with a "," inside of it (e.g. the absolute_codec_string), you must tell FreeSWITCH what delimiter to use instead for THIS value.

The syntax is to put a prefix of ^^: at the start of the value and replace the commas in the value with ":". Then, FreeSWITCH will substitute commas back in when setting the value for the channel.

You can use (almost) any character you like though, it uses the one after the initial "^^"

{absolute_codec_string=^^:PCMA@8000h@20i@64000b:PCMU@8000h@20i@64000b:G729@8000h@20i@8000b,leg_time_out=10,process_cdr=b_only}

This approach however does not work when you are setting sip_h_, sip_rh_ and sip_ph headers. If you want to pass a comma into the contents of a private header then you must escape the comma with a preceding backslash:

{sip_h_X-My-Header=one\,two\,three,leg_time_out=10,process_cdr=b_only}

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:

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. 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} e.g.

originate {ignore_early_media=true}sofia/mydomain.com/18005551212@1.2.3.4 15555551212

If the value you are setting has a space in it then you will need to enclose the value in quotes. For example:

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

Channel Variable Manipulation

Channel variables can be manipulated 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.

Channel Variable Scope w/ Example

Consider the following example that shows where each application sets it's variable :

  <extension name="test" continue="false">
     <condition field="destination_number" expression="^test([0-9]+)$">
       <action application="set" data="fruit=tomato" /> <!-- Set variable in local channel -->
       <action application="export" data="veggie=tomato" /> <!-- Set variable in local channel and export it to new channels we bridge to -->
       <action application="bridge" data="{meat=tomato},sofia/gateway/testaccount/1234" /><!-- bridge new channel and set variable only in new channel -->
     </condition>
   </extension>

Leg A ( the channel that called the dial plan ) will have the following variables set :

fruit: tomato
veggie: tomato

Leg B ( the channel created with sofia/gateway/testaccount/1234 ) will have the following variables set :

veggie: tomato
meat: tomato

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 FreeSWITCH. 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: http://www.nanpa.com/number_resource_info/ani_ii_digits.html
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[Calling Line ID presentation Restriction] (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_full_route sip_full_route The complete contents of the Route: header.
variable_sip_full_via sip_full_via The complete contents of the Via: header.
variable_sip_full_from sip_full_from The complete contents of the From: header.
variable_sip_full_to sip_full_to The complete contents of the To: header.
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_tag sip_to_tag .
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 The full SIP URI received from a SIP Refer-To: response
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_curl_response_data curl_response_data This variable stores the output from the last curl made.
variable_drop_dtmf drop_dtmf Set on a channel to drop DTMF events on the way out.
sip_codec_negotiation sip_codec_negotiation sip_codec_negotiation is basically a channel variable equivalent of inbound-codec-negotiation.
sip_codec_negotiation accepts "scrooge" & "greedy" as values.
This means you can change codec negotiation on a per call basis.
Caller-Callee-ID-Name - -
Caller-Callee-ID-Number - -
Caller-Channel-Progress-Media-Time - -
Caller-Channel-Progress-Time - -
Caller-Direction - -
Caller-Profile-Created-Time profile_created -
Caller-Transfer-Source - -
Channel-Call-State - -
Channel-Call-UUID - -
Channel-HIT-Dialplan - -
Channel-Read-Codec-Bit-Rate - -
Channel-Write-Codec-Bit-Rate - -
Core-UUID - -
Event-Calling-File - -
Event-Calling-Function - -
Event-Calling-Line-Number - -
Event-Date-GMT - -
Event-Date-Local - -
Event-Date-Timestamp - -
Event-Name - -
Event-Sequence - -
FreeSWITCH-Hostname - -
FreeSWITCH-IPv4 - -
FreeSWITCH-IPv6 - -
FreeSWITCH-Switchname - -
Hunt-ANI - -
Hunt-Callee-ID-Name - -
Hunt-Callee-ID-Number - -
Hunt-Caller-ID-Name - -
Hunt-Caller-ID-Number - -
Hunt-Channel-Answered-Time - -
Hunt-Channel-Created-Time - -
Hunt-Channel-Hangup-Time - -
Hunt-Channel-Name - -
Hunt-Channel-Progress-Media-Time - -
Hunt-Channel-Progress-Time - -
Hunt-Channel-Transfer-Time - -
Hunt-Context - -
Hunt-Destination-Number - -
Hunt-Dialplan - -
Hunt-Direction - -
Hunt-Network-Addr - -
Hunt-Privacy-Hide-Name - -
Hunt-Privacy-Hide-Number - -
Hunt-Profile-Created-Time profile_created -
Hunt-Profile-Index - -
Hunt-RDNIS - -
Hunt-Screen-Bit - -
Hunt-Source - -
Hunt-Transfer-Source - -
Hunt-Unique-ID - -
Hunt-Username - -
Presence-Call-Direction - -
variable_DIALSTATUS - -
variable_absolute_codec_string - -
variable_advertised_media_ip - -
variable_bridge_channel - -
variable_bridge_hangup_cause - -
variable_bridge_uuid - -
variable_call_uuid - -
variable_current_application_response - -
variable_direction - -
variable_inherit_codec - -
variable_is_outbound - -
variable_last_bridge_to - -
variable_last_sent_callee_id_name - -
variable_last_sent_callee_id_number - -
variable_local_media_ip - -
variable_local_media_port - -
variable_number_alias - -
variable_originate_early_media - -
variable_originating_leg_uuid - -
variable_originator - -
variable_originator_codec - -
variable_outbound_caller_id_number - -
variable_recovery_profile_name - -
variable_rtp_use_ssrc - -
variable_session_id - -
variable_sip_2833_recv_payload - -
variable_sip_2833_send_payload - -
variable_sip_P-Asserted-Identity - -
variable_sip_Privacy - -
variable_sip_audio_recv_pt - -
variable_sip_cid_type - -
variable_sip_cseq - -
variable_sip_destination_url - -
variable_sip_from_display - -
variable_sip_from_port - -
variable_sip_gateway - -
variable_sip_gateway_name - -
variable_sip_h_P-Charging-Vector - -
variable_sip_local_network_addr - -
variable_sip_local_sdp_str - -
variable_sip_network_ip - -
variable_sip_network_port - -
variable_sip_number_alias - -
variable_sip_outgoing_contact_uri - -
variable_sip_ph_P-Charging-Vector - -
variable_sip_profile_name - -
variable_sip_recover_contact - -
variable_sip_recover_via - -
variable_sip_reply_host - -
variable_sip_reply_port - -
variable_sip_req_port - -
variable_sip_to_port - -
variable_sip_use_codec_name - -
variable_sip_use_codec_ptime - -
variable_sip_use_codec_rate - -
variable_sip_use_pt - -
variable_sip_via_protocol - -
variable_switch_m_sdp - -
variable_transfer_history - -
variable_transfer_source - -
variable_uuid - -

${variable} vs. $${variable}

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

$${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 pre-processor, and ${variables} are evaluated fresh each time they are executed (for example when a call connects).

CDR related

process_cdr

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


Usage:

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


accountcode

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


hold_events

It's a variable that display start and stop times for each hold.


Example:

This CDR shows that the phone was put on hold twice with hold start and stop time.

variable_hold_events: [{{1347487292379229,1347487293856872},{1347487288539686,1347487290757780}}]


hangup_complete_with_xml

Variable hangup complete with xml

skip_cdr_causes

This is a list of call hangup causes that should not trigger cdr processing.


transfer_to

Description needed


Example: Example needed


Hangup Causes

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


disable_q850_reason

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


hangup_cause

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

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


sip_hangup_disposition

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

<sip_hangup_disposition>send_bye</sip_hangup_disposition>
<sip_hangup_disposition>recv_bye</sip_hangup_disposition>
<sip_hangup_disposition>send_refuse</sip_hangup_disposition>
<sip_hangup_disposition>send_cancel</sip_hangup_disposition>

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

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

Usage:

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


proto_specific_hangup_cause

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 dialled 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="<a href="sip:480">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>


last_bridge_hangup_cause

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

This shows the last bride hangup cause by SIP response code, e.g. "sip:404"



DTMF Related

pass_rfc2833

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.


Usage:

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


dtmf_type

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


Usage:

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

or,

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

or,

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


drop_dtmf

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 Jira issue FS-4769. Commit 60f7849cbe72.


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


Media Handling

monitor_early_media_fail

Monitors early media for failure conditions, such as a busy signal. This allows faster processing of failed calls when ignoring early media.

The syntax is a series of ! delimited early media conditions in the following format:

condition_name:number_of_hits:tone_detect_frequencies

condition_name

user defined name for the error condition

number_of_hits

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

tone_detect_frequencies

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

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

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_name

Optional? user-defined name for the error condition

number_of_hits

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.

tone_detect_frequencies

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.


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


Timeout Related

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


leg_timeout

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.


Usage:

<action application="bridge" data="[leg_timeout=15]user/hastoanswerquickly/some.domain.com,[leg_timeout=60]user/hasaminutetoanswer@some.domain.com"/>


originate_continue_on_timeout

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


Usage:

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


park_timeout

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.

Usage: <action application="set" data="park_timeout=30:MEDIA_TIMEOUT"/>


Music On Hold Related

hold_music

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


Usage:

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

or,

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


temp_hold_music

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


Locale Related

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


timezone

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

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

Usage:

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

or,

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


tod_tz_offset

Sets the GMT offset to be used on this call for tod based conditions.

NOTE: the variable must actually be set before the comparison, so either set it inline, transfer, or set it in the user directory.


You can set the offset Globally for Freeswitch in /conf/vars.xml by adding this line: <X-PRE-PROCESS cmd="set" data="tod_tz_offset=5"/> (of course replace the '5' with your GMT offset.

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

Finally you can set the variable for a particular extension in /conf/directory/default/'extension'.xml

Usage:

<action application="set" data="tod_tz_offset=5"/>


Bridge Related

api_after_bridge

Execute an API command after bridge.


Usage:

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


auto_hunt

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

Example:

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


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


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_terminate_key

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


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


transfer_on_fail

Allows you to tranfer call flow when a called party can not be reached for specific reasons ( unallocated_number, etc )


Usage:

<action application="set" data="transfer_on_fail= UNALLOCATED_NUMBER"/>

in this example, if you were to attempt a bridge that resulted in "UNALLOCATED_NUMBER" , the call flow would be "transferred" to the "UNALLOCATED_NUMBER" destination in your current dialplan ( probably default xml dialplan )

or,

<action application="set" data="transfer_on_fail=<hangupcauses> <destination> <dialplan> <context>"/>

or,

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


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; http://lists.freeswitch.org/pipermail/freeswitch-users/2012-April/082835.html



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


failure_causes

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

or Q.850 cause codes,

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


force_transfer_context

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

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

Usage:

Example needed! Please contribute one.


hangup_after_bridge

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.


Usage:

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


hold_hangup_xfer_exten

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


last_bridge_to

Variable last bridge to

loopback_bowout_on_execute

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


Usage:

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


loopback_export

A list of channel variables to pass from loopback-a to loopback-b.


Usage:


outbound_redirect_fatal

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="set" data="outbound_redirect_fatal=true"/> 


originate_timeout

Determines how long a bridge or originate action action will stay in the "originate" state. In effect, it is a way to control the timeout for a bridge/originate consisting of multiple endpoints. Default value is 60.


Usage:

<action application="bridge" data="{originate_timeout=10}[leg_timeout=5]sofia/default/foo1@bar1|[leg_timeout=5]sofia/default/foo2@bar2"/>


Example

<action application="bridge" data="{originate_timeout=24}${group_call(sales@$${domain})}"/>

park_after_bridge

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

Usage:

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


signal_bond

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

Usage:

Example needed! Please contribute one.

See also:



no_throttle_limits

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

Usage:

{no_throttle_limits=true}

See also:



sip_jitter_buffer_during_bridge

Enables/disables the jitter buffer during bridge.


Usage:

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

or,

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


uuid_bridge_continue_on_cancel

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


Usage:

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


Conference Related

conference_auto_outcall_announce

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

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

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

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_prefix

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_timeout

Originate timeout to use when joining a member to a conference via conference_set_auto_outcall.

Usage:

<action application="set" data="conference_auto_outcall_timeout=60"/>


conference_auto_outcall_maxwait

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_controls

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.

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

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_last_matching_digits

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


last_transferred_conference

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


conference_member_id

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


conference_uuid

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.


hangup_after_conference

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


Code Execution Related

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)


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.


Usage:

Example needed! Please contribute one.


bridge_pre_execute_aleg_data

Arguments to be used with bridge_pre_execute_aleg_app.


Usage:

Example needed! Please contribute one.


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


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


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


exec_after_bridge_app

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

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


origination_nested_vars

Variable origination nested vars

The execute_on family

The execute_on_xx variables will execute dialplan applications on various conditions. As of April 1, 2011 these variables support a new syntax that 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"/>

Note: please be careful not to abuse this feature! There are cases where you could end up blocking the session thread and bad things could happen. If you find that you are trying to do lots and lots of things with these then consider using an execute_extension app and doing your stuff in a dialplan extension.

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>


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

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

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

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

Execute a command when the called party rings.


Usage:

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


execute_on_sip_reinvite

Execute a command when SIP Reinvite.


Usage:


The api_on family

The api_on_xx variables will execute FreeSWITCH APIs on various conditions.

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_originate

Variable api on originate

api_on_post_originate

Variable api on post originate

api_on_pre_answer

Variable api on pre answer

api_on_pre_originate

Variable api on pre originate

api_on_ring

Variable api on ring

api_on_sip_extra_headers

Variable api on sip extra headers

api_on_tone_detect

Variable api on tone detect

failed_xml_cdr_prefix

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


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




intercept_unbridged_only

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

Default: false

Usage:

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


intercept_unanswered_only

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


session_in_hangup_hook

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

Usage:

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


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


Caller ID Related

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.


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

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


 


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


sip_cid_type

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

Examples:

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

{sip_cid_type=none}sofia/default/user@example.com

Note: for gateways (rather than sip calls on a profile), this will not work. You need caller-id-in-from=true in the gateway settings.

Send Remote-Party-ID (default)

{sip_cid_type=rpid}sofia/default/user@example.com

Send P-Asserted-Identity

{sip_cid_type=pid}sofia/default/user@example.com

Note: you must set privacy flag, otherwise will be inserted P-Preferred-Identity instead of P-Asserted-Identity

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

Also the privacy app on the inbound leg controls the remaining contents of the RPID and Privacy headers.

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

effective_sip_cid_in_1xx

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


Callee ID Related

origination_callee_id_name

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:

<action application="bridge" data="{origination_callee_id_name=Reginald}sofia/gateway/provider/<Reginald's cellphone number>" />

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

origination_callee_id_number

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

Call Recording Related

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

Audio File Metadata

RECORD_TITLE

RECORD_COPYRIGHT

RECORD_SOFTWARE

RECORD_ARTIST

RECORD_COMMENT

RECORD_DATE

RECORD_STEREO

record_fill_cng

Description need please.

Usage:

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


RECORD_HANGUP_ON_ERROR

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_DISCARDED

If a recording gets dropped or discarded then this channel variable is set to true. Useful for diagnostics.

Usage:

N/A


record_post_process_exec_api

and

record_post_process_exec_app

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

Example usage:

<action application="set" data="record_post_process_exec_api=api_here:api_arg1 api_arg2 api_arg3" />

record_restart_limit_on_dtmf

Record restart limit on dtmf

record_sample_rate

Specify the sampling rate of the recorded file.

Usage:

<action application="set" data="record_sample_rate=8000"/>


record_waste_resources

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


recording_follow_transfer

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

Example

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

Codec Related

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


codec_string

Sets the base codec string to use.


Usage:

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


inherit_codec

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


read_codec

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


write_codec

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


passthru_ptime_mismatch

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

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


sip_renegotiate_codec_on_reinvite

Allow SDP codec change with re-INVITE


Usage:

<action application="bridge" data="{sip_renegotiate_codec_on_reinvite=true}sofia/gateway/trunk/$1"/>

Note: It may also be set globally in vars.xml or set it in sip profiles (<param name="renegotiate-codec-on-reinvite" value="true"/>)


conference_enforce_security

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)


suppress-cng

Sets a=silenceSupp: off in the sdp to disable silence suppression while making an outbound call.

Usage:

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


IVR related

ivr_menu_terminator

You can set to none or the dtmf chars you want to terminate input.


Usage:

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


detect_speech_result

The result of play_and_detect_speech.

Usage:

This value is read-only.



SIP related variables

disable_hold

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


Usage:

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


sip_acl_authed_by

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


Usage:

None.


sip_acl_token

Contains the ACL auth token for the current call.


Usage:

N/A


sip_copy_multipart

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.


Usage:

To have FreeSWITCH keep the multiple MIME parts intact when using bridge (default):

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

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

To have FreeSWITCH strip the multiple MIME parts when using bridge:

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


sip_invite_params

Description needed! Please contribute one.

Usage:

Example needed! Please contribute one.


sip_invite_domain

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_from_display

sip_from_display

Description needed! Please contribute one.

Usage:

Example needed! Please contribute one.

See also:


Implemented By:

Module Name Source FileLast Revised
mod_sofiasofia_glue.c 12566

sip_invite_from_params

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

Result:

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


sip_invite_to_params

Description needed! Please contribute one.

Usage:

Example needed! Please contribute one.


sip_invite_contact_params

Description needed! Please contribute one.

Usage:

Example needed! Please contribute one.


sip_invite_tel_params

Tel URI parameters (npdi, rn) appearing in SIP URI on outbound calls.

Usage:

<action application="bridge" data="{sip_invite_tel_params=npdi=yes;rn=555000001,sip_invite_params=user=phone}sofia/gateway/test_gw/555000002"/>

Result:

INVITE sip:555000002;npdi=yes;rn=5555550001@1.2.3.4;user=phone SIP/2.0


sip_network_destination

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_auth_username

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_auth_password

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_auto_simplify

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_callee_id_name

Error

DEPRECATED. Use variable origination_callee_id_name instead


sip_callee_id_number

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


Usage:

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


sip_force_audio_fmtp

Set the audio fmtp.

Usage:

Please add example if you have one.


sip_invite_req_uri

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:

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_record_route

Variable sip invite record route

sip_invite_route_uri

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_full_from

Variable sip invite full from

sip_invite_full_to

Variable sip invite full to

sip_handle_full_from

Variable sip handle full from

sip_handle_full_to

Variable sip handle full to

sip_force_full_from

Variable sip force full from

sip_force_full_to

Variable sip force full to

sip_recover_contact

Variable sip recover contact

sip_recover_via

Variable sip recover via

sip_invite_from_uri

Variable sip invite from uri

sip_invite_to_uri

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_ignore_reinvites

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_has_crypto

Variable sip has crypto

sip_secure_media

Variable sip secure media

sip_wait_for_aleg_ack

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


timer_name

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



ignore_display_updates

See link

deny_refer_requests

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.

SDP Manipulation

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

sdp_m_per_ptime

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 its 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_trancoding or absolute_codec_string as well

Usage:

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


switch_r_sdp

Read only. This variable holds the remote SDP for the current leg/channel.


Usage:

Rewriting SDP:

<action application="set"><![CDATA[switch_r_sdp=(sdp here)
]]>
</action>

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


switch_l_sdp

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

switch_m_sdp

The B-leg remote SDP.


Usage:

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


sip_append_audio_sdp

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="sip_append_audio_sdp=a=fmtp:18 annexb=no"/>

sip_ignore_183nosdp

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

Usage:

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

verbose_sdp

The RFCs require an rtpmap for IANA dynamic payload types. An rtpmap with codec name and payload type is not required for well known static payloads - (PCMU, PCMA, G729, etc).

By default FreeSWITCH sets verbose_sdp=false which doesn't include an rtpmap for static payload types. If your equipment doesn't support this (shame on them) set verbose_sdp=true which will include rtpmaps for any static payload types (previous default behavior).

sip_local_sdp_str

Description goes here


Usage:

Example needed.


sip_recovery_break_rfc

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


Usage:

Examples needed!!!

Note: This variable can be set globally or per channel.


sip_mirror_remote_audio_codec_payload

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.


Usage:

Examples needed!!!

Note: This variable can be set globally or per channel.


sip_enable_soa

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


sdp_secure_savp_only

When sip_secure_media=true FreeSWITCH will offer both AVP and SAVP in the SDP. Setting sdp_secure_savp_only=true (in addition to sip_secure_media=true) will cause FreeSWITCH to offer only SAVP in the SDP.

Usage:

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


FIFO related variables

fifo_bridged

Description goes here


Usage:

Example needed


fifo_caller_consumer_import

Import list of variables from the caller to the consumer.


Usage:

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


fifo_consumer_caller_import

Import list of variables from the consumer to the caller

Usage:

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


fifo_manual_bridged

Description goes here


Usage:

Example needed


fifo_position

Description goes here


Usage:

Example needed


fifo_role

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


Usage:

None


transfer_after_bridge

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.

Usage:

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

or,

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

(Note the : separator)


Playback related variables

playback_terminators

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=#*"/>

sound_prefix

Directory prefix where the sounds lives.

playback_terminator_used

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

playback_ms

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

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

playback_last_offset_pos

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_sleep_val

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

playback_delimiter

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

sleep_eat_digits

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.

playback_timeout_sec

Set timeout for playback. This is very useful if you want to play short excerpts of a file that could be very long.

 <action application="set" data="playback_timeout_sec=10"/>

Originate related variables

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


leg_delay_start

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

originate_disposition

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

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

originate_retry_sleep_ms

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.

originate_timeout

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@192.168.1.4|sofia/default/$1@192.168.1.5"/>

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

originating_leg_uuid

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:

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

Note that the leg uuid's are different. The call_uuid matches the two legs together, but the originating_leg_uuid can do so as well.


origination_channel_name

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_caller_id_name

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

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:

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

origination_cancel_key

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)

Usage:

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

origination_privacy

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

Usage:

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

origination_uuid

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/<profile>/<extension>

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.

originator

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

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

Usage:

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

RTP/media related variables

bypass_media

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

bypass_media_after_bridge

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.

bypass_keep_codec

By doing export bypass_keep_codec=true to force re-invite with the same codec it was using previously.

proxy_media

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

rtp_autoflush

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

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

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

progress_timeout

This is the maximum time we will wait before we get media (whether its 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.

Avi Marcus: I set my progress_timeout to 13 seconds to accommodate for slow-setup mobile connections, however, it can probably be shorter.

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


Usage

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

See also Early Media

bridge_answer_timeout

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

Usage

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

See also Early Media

ignore_early_media

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

See also Early Media

ringback

This will specify the audio to play to the A leg on unanswered aka (early media) calls. The following example uses the US ring tone defined in ~/vars.xml

Usage:

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

instant_ringback

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

Usage:

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

transfer_ringback

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 defined in ~/vars.xml

Usage:

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

disable_hold

This is the channel variable for disable-hold.

See http://wiki.freeswitch.org/wiki/Sofia.conf.xml#disable-hold.

Usage:

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

rtp_negotiate_near_match

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

RTCP Related

rtcp_packet_count

Contains number of RTCP packets collected during the call.

Usage:

N/A


rtcp_octet_count

Contains number of RTCP octets collected during the call.

Usage:

N/A


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.

campon

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_retries

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

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_timeout

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


campon_sleep

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_fallback_exten

Controls camping during bridge app (testing needed)


Usage:

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


campon_fallback_dialplan

Controls camping during bridge app (testing needed)


Usage:

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


campon_fallback_context

Controls camping during bridge app (testing needed)


Usage:

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


campon_hold_music

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


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_stop_key

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_announce_sound

File to play back after the first bridge fails (rg 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"/>


Answer confirmation variables

group_confirm_file

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.

group_confirm_key

see group_confirm_file

group_confirm_cancel_timeout

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

voicemail_alternate_greet_id

voicemail_greeting_number

vm_message_ext

vm_cc

skip_greeting

skip_instructions

voicemail_authorized

Events

fire_asr_events

If set, fire an event when speech is detected.

System Related Variables

base_dir

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

Usage:

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


OpenZap Related Variables

openzap_span_number

openzap span number

openzap_chan_number

openzap channel number