Channel Variables

From FreeSWITCH Wiki

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.

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

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

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

Contents 1 variable_xxxx 2 ${variable} vs. $${variable} 3 process_cdr 4 bypass_media 5 proxy_media 6 pass_rfc2833 7 call_timeout 8 progress_timeout 9 default_language 10 hangup_after_bridge 11 continue_on_fail 12 api_hangup_hook 13 execute_on_answer 14 execute_on_ring 15 fail_on_single_reject 16 ignore_early_media 17 caller_id_name 18 caller_id_number 19 effective_caller_id_name 20 effective_caller_id_number 21 hold_music 22 originate_disposition 23 origination_caller_id_name 24 origination_caller_id_number 25 originator_codec 26 absolute_codec_string 27 codec_string 28 ringback 29 transfer_ringback 30 read_codec 31 write_codec 32 ring_ready 33 Recording related variables 33.1 record_rate 33.2 RECORD_ANSWER_REQ 33.3 RECORD_STEREO 33.4 Recording Meta Data 34 timer_name 35 SDP Manipulation 35.1 switch_r_sdp 35.2 switch_l_sdp 35.3 switch_m_sdp 36 Playback related variables 36.1 playback_terminators 37 Unknown Functionality 37.1 bridge_pre_execute_aleg_app 37.2 bridge_pre_execute_aleg_data 37.3 bridge_pre_execute_bleg_app 37.4 bridge_pre_execute_bleg_data 37.5 fire_asr_events 37.6 sound_prefix 37.7 bridge_to 37.8 signal_bridge_to 37.9 originator 37.10 local_media_ip 37.11 local_media_port 37.12 remote_media_ip 37.13 remote_media_port 37.14 max_forwards 37.15 _sofia_replaces_ 37.16 alert_info 37.17 group_confirm_file 37.18 group_confirm_key 37.19 originate_retries 37.20 originate_timeout 37.21 originate_retry_sleep_ms 37.22 import

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_type' in FS. To access that variable, you should strip off the variable_, and just do ${sip_type}

${variable} vs. $${variable}

$${variables} are expanded when the master freeswitch.xml is compiled. This happens when you start freeswitch. ${variables} are channel variables that may be set in the dialplan, application or directory that effect progress or settings for the call.

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

bypass_media

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

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

See also: Bypass Media Overview

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

pass_rfc2833

If set it passes rfc2833 dtmf's from one side of a bridge to the other untouched. If unset, it decodes and reencodes them before passing them on.

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

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

call_timeout

Controls how long (in seconds) to ring the B leg of a call when using the bridge application. You can only have a global timeout.. you can't set one on a per leg basis.

Usage:

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

progress_timeout

This needs a proper explanation. Is the timeout for how long we can get early media before the call is answered or the max time we will wait before early media?

Usage

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

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

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.

Usage:

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

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

Usage:

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

See also: Hangup causes

api_hangup_hook

Execute an API command on hangup. Example:

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

execute_on_answer

Execute a command when the called party answer. Example:

<action application="set" data="execute_on_answer=lua incrInUse.lua ${uuid}"/>

execute_on_ring

(not avalaible for FS 1.0.0, but introduced in the next release, 1.0.X)

Execute a command when the called party rings. Example:

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

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. For example:

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

The default setting is FALSE, meaning a single rejection will not terminate the bridging attempt.

Usage:

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

ignore_early_media

Controls if the call returns on early media or not. Default is false. (used to be noanswer_early_media)

Usage:

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

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.

effective_caller_id_name

Sets the effective callerid name. Automatically exported to originated channels. It is a var set on a channel in case it becomes the A leg of a bridge - it will use this callerid name on the B leg outbound call.

Usage:

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

effective_caller_id_number

Sets the effective callerid number. Automatically exported to originated channels. It is a var set on a channel in case it becomes the A leg of a bridge - it will use this callerid number on the B leg outbound call.

Usage:

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

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

originate_disposition

This is the originate disposition aka hangup cause returned. (LEG B)

It is also redefined after every bridge attempts if the bridge is not successful.

origination_caller_id_name

Sets the origination callerid name. (LEG A)

Usage:

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

origination_caller_id_number

Sets the origination callerid number. (LEG A)

Usage:

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

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

absolute_codec_string

Sets the absolute codec to use

codec_string

Sets the codec to add to the list of codecs.

ringback

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

Usage:

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

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 ~/autoload_configs/switch.conf.xml

Usage:

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

read_codec

The negotiated codec of the inbound call leg.

write_codec

The negotiated codec of the outbound call leg.

ring_ready

Causes to send "180 Ringing" to the caller/originating endpoint.

Usage:

<action application="ring_ready"/>

Recording related variables

record_rate

Set the sample rate of the recording.

Usage: <action application="set" data="record_rate=11025"/>

RECORD_ANSWER_REQ

Start recording only when the channel has been answered.

Usage:

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

RECORD_STEREO

Record leg A and leg B streams into different channel in a stereo file.

Usage:

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

Recording Meta Data

The following are set prior to performing a record to set the file header meta data provided the file format supports meta headers.

• RECORD_TITLE
• RECORD_COPYRIGHT
• RECORD_SOFTWARE
• RECORD_ARTIST
• RECORD_COMMENT
• RECORD_DATE

Usage:

<action application="set" data="RECORD_TITLE=MegaMusic"/>
<action application="set" data="RECORD_COPYRIGHT=(c)2007-me"/>
<action application="set" data="RECORD_SOFTWARE=FreeSwitch"/>
<action application="set" data="RECORD_ARTIST=Unknown"/>
<action application="set" data="RECORD_COMMENT=This is a blog spot"/>
<action application="set" data="RECORD_DATE=2007-01-16"/>

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

SDP Manipulation

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

switch_r_sdp

• Remote SDP

switch_l_sdp

• Local SDP

switch_m_sdp

• Merged? SDP

Playback related variables

playback_terminators

Allows you to set which DTMF tones, if pressed during the playback of a file, will stop it.

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

Unknown Functionality

bridge_pre_execute_aleg_app

bridge_pre_execute_aleg_data

bridge_pre_execute_bleg_app

bridge_pre_execute_bleg_data

fire_asr_events

sound_prefix

bridge_to

signal_bridge_to

originator

local_media_ip

local_media_port

remote_media_ip

remote_media_port

max_forwards

_sofia_replaces_

alert_info

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

group_confirm_key

see group_confirm_file

originate_retries

Missing docs

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.

import

(should be) The import variable, when used before a bridge, imports the variables of the other channel on the actual channel.

Usage:

<action application="set" data="import=this_is_a_variable_name"/>