Skip to main content

FS Channel Variables

See Channel Variables

This duplicate page is being merged with __Channel Variables . Please refer to that page.

About

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

Click here to expand Table of Contents

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:

  • See dialplan conditions for specifics. <MISSING LINK>
  • 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. <MISSING LINK>

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

Channel Variable Scope with 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 dialplan) will have the following variable 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 namechannel variable nameDescription
Channel-StatestateCurrent state of the call
Channel-State-Numberstate_numberInteger
Channel-Namechannel_nameChannel name
Unique-IDuuiduuid of this channel's call leg
Call-DirectiondirectionInbound or Outbound
Answer-Statestate.
Channel-Read-Codec-Nameread_codecthe read codec variable mean the source codec
Channel-Read-Codec-Rateread_ratethe source rate
Channel-Write-Codec-Namewrite_codecthe destination codec same to write_codec if not transcoded
Channel-Write-Codec-Ratewrite_ratedestination rate same to read rate if not transcoded
Caller-Usernameusername.
Caller-Dialplandialplanuser dialplan like xml, lua, enum, lcr
Caller-Caller-ID-Namecaller_id_name.
Caller-Caller-ID-Numbercaller_id_number.
Caller-ANIaniANI of caller, frequently the same as caller ID number
Caller-ANI-IIaniiiANI II Digits (OLI - Originating Line Information), if available. Refer to:http://www.nanpa.com/number%5Fresource%5Finfo/ani%5Fii%5Fdigits.html
Caller-Network-Addrnetwork_addrIP address of calling party
Caller-Destination-Numberdestination_numberDestination (dialed) number
Caller-Unique-IDuuidThis channel's uuid
Caller-SourcesourceSource module, i.e. mod_sofia, mod_openzap, etc.
Caller-ContextcontextDialplan context
Caller-RDNISrdnisRedirected DNIS info. See transfer application
Caller-Channel-Namechannel_name.
Caller-Profile-Indexprofile_index.
Caller-Channel-Created-Timecreated_time.
Caller-Channel-Answered-Timeanswered_time.
Caller-Channel-Hangup-Timehangup_time.
Caller-Channel-Transfer-Timetransfer_time.
Caller-Screen-Bitscreen_bit.
Caller-Privacy-Hide-Nameprivacy_hide_name.
Caller-Privacy-Hide-Numberprivacy_hide_numberThis 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_ipsip_received_ip.
variable_sip_received_portsip_received_port.
variable_sip_authorizedsip_authorized.
variable_sip_mailboxsip_mailbox.
variable_sip_auth_usernamesip_auth_username.
variable_sip_auth_realmsip_auth_realm.
variable_mailboxmailbox.
variable_user_nameuser_name.
variable_domain_namedomain_name.
variable_record_stereorecord_stereo.
variable_accountcodeaccountcodeAccountcode 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_contextuser_context.
variable_effective_caller_id_nameeffective_caller_id_name.
variable_effective_caller_id_numbereffective_caller_id_number.
variable_caller_domaincaller_domain.
variable_sip_from_usersip_from_user.
variable_sip_from_urisip_from_uri.
variable_sip_from_hostsip_from_host.
variable_sip_from_user_strippedsip_from_user_stripped.
variable_sip_from_tagsip_from_tag.
variable_sofia_profile_namesofia_profile_name.
variable_sofia_profile_domain_namesofia_profile_domain_name.
variable_sip_full_routesip_full_routeThe complete contents of the Route: header.
variable_sip_full_viasip_full_viaThe complete contents of the Via: header.
variable_sip_full_fromsip_full_fromThe complete contents of the From: header.
variable_sip_full_tosip_full_toThe complete contents of the To: header.
variable_sip_req_paramssip_req_params.
variable_sip_req_usersip_req_user.
variable_sip_req_urisip_req_uri.
variable_sip_req_hostsip_req_host.
variable_sip_to_paramssip_to_params.
variable_sip_to_tagsip_to_tag.
variable_sip_to_usersip_to_user.
variable_sip_to_urisip_to_uri.
variable_sip_to_hostsip_to_host.
variable_sip_contact_paramssip_contact_params.
variable_sip_contact_usersip_contact_user.
variable_sip_contact_portsip_contact_port.
variable_sip_contact_urisip_contact_uri.
variable_sip_contact_hostsip_contact_host.
variable_sip_invite_domainsip_invite_domain.
variable_channel_namechannel_name.
variable_sip_call_idsip_call_id.
variable_sip_user_agentsip_user_agent.
variable_sip_via_hostsip_via_host.
variable_sip_via_portsip_via_port.
variable_sip_via_rportsip_via_rport.
variable_presence_idpresence_id.
variable_sip_h_P-Key-Flagssip_h_p-key-flagsThis will contain the optional P-Key-Flags header(s) that may be received from calling endpoint.
variable_switch_r_sdpswitch_r_sdpThe whole SDP received from calling endpoint.
variable_remote_media_ipremote_media_ip.
variable_remote_media_portremote_media_port.
variable_write_codecwrite_codec.
variable_write_ratewrite_rate.
variable_endpoint_dispositionendpoint_disposition.
variable_dialed_extdialed_ext.
variable_transfer_ringbacktransfer_ringback.
variable_call_timeoutcall_timeout.
variable_hangup_after_bridgehangup_after_bridge.
variable_continue_on_failcontinue_on_fail.
variable_dialed_userdialed_user.
variable_dialed_domaindialed_domain.
variable_sip_redirect_contact_user_0sip_redirect_contact_user_0.
variable_sip_redirect_contact_host_0sip_redirect_contact_host_0.
variable_sip_h_Referred-Bysip_h_referred-by.
variable_sip_refer_tosip_refer_toThe full SIP URI received from a SIP Refer-To: response
variable_max_forwardsmax_forwards.
variable_originate_dispositionoriginate_disposition.
variable_read_codecread_codec.
variable_read_rateread_rate.
variable_openopen.
variable_use_profileuse_profile.
variable_current_applicationcurrent_application.
variable_ep_codec_stringep_codec_stringThis 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_holddisable_holdThis variable when set will disable the hold feature of the phone.
variable_sip_acl_authed_bysip_acl_authed_byThis variable holds what ACL rule allowed the call.
variable_curl_response_datacurl_response_dataThis variable stores the output from the last curl made.
variable_drop_dtmfdrop_dtmfSet on a channel to drop DTMF events on the way out.
sip_codec_negotiationsip_codec_negotiationsip_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-Timeprofile_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-Timeprofile_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).

<multiple missing links, remove maybe?>

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_crd_causes

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

transfer_to

<missing description>

Example:

<missing example>

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_causes

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