Difference between revisions of "Channel Variables"

From FreeSWITCH Wiki
Jump to: navigation, search
(clarifying ring_ready value for ignore_early_media based on feedback from anthm)
(Call Recording Related)
Line 801: Line 801:
 
=== RECORD_HANGUP_ON_ERROR ===
 
=== RECORD_HANGUP_ON_ERROR ===
  
 
+
===record_post_process_exec_api===
 +
and
 +
===record_post_process_exec_api===
 +
These two variables allow the postprocessing of recorded audio.  The reason this is required is if the A leg hangs up first in a call, the dialplan stops being processed, and then you aren't able to take action on the file that was recorded.  These variables take the form of:
 +
<action application="set" data="record_post_process_exec_api=some_api_app:api_app args" />
  
 
== Codec Related ==
 
== Codec Related ==

Revision as of 03:10, 28 October 2010

Contents

Introduction

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

Channel Variables in the XML Dialplan

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

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

Accessing channel variables requires the ${} syntax:

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

Channel Variables in Dial strings

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

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

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

{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

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

Exporting Channel Variables in Bridge Operations

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

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

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

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

Using Channel Variables in Dialplan Condition Statements

Channel variables can be used in conditions:

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

Custom Channel Variables

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

originate {ignore_early_media=true}sofia/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. An example of this is

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

Channel Variable Manipulation

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

Info Application Variable Names (variable_xxxx)

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

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

${variable} vs. $${variable}

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

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

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

CDR related

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


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.


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


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


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


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


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


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


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


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:



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_member_id

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


Code Execution Related

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


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_ring

Execute a command when the called party rings.


Usage:

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


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


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


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


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




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)


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.


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


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

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

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

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.


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


Call Recording Related

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

RECORD_TITLE

RECORD_COPYRIGHT

RECORD_SOFTWARE

RECORD_ARTIST

RECORD_COMMENT

RECORD_DATE

RECORD_STEREO

RECORD_HANGUP_ON_ERROR

record_post_process_exec_api

and

record_post_process_exec_api

These two variables allow the postprocessing of recorded audio. The reason this is required is if the A leg hangs up first in a call, the dialplan stops being processed, and then you aren't able to take action on the file that was recorded. These variables take the form of:

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

Codec Related

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.


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)


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


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

SDP Manipulation

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

switch_r_sdp

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

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

  • "B-leg" remote SDP
  • Known as SWITCH_B_SDP_VARIABLE in mod_sofia and the core switch code.
  • Used to store the remote SDP used by the other leg/channel of a call. (In the A-leg that will be the remote SDP of the B-leg.)
  • This variable is set, but never used, by FreeSwitch. ("read-only")

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

FIFO related variables

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)


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


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.

playback_samples

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

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.

Originate related variables

originate_retries

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

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.

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

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

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

Usage:

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

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

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.

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

Bridge also uses the origination syntax so you can also pre-allocate the UUID for the new channel resulting from a bridge by using the {}/[] syntax and specifying origination_uuid there, too.

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

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.

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 (wether its early media, ringing or answer)

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 set the 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 definte 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"/>

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