About

Channel variables are used to manipulate dialplan execution, to control call progress, and to provide options to applications. They play a pervasive role, as FreeSWITCH™ frequently consults channel variables as a way to customize processing prior to a channel’s creation, during call progress, and after the channel hangs up.  Click here to expand Table of Contents

Variable Expansion

We rely on variable expansion to create flexible, reusable dialplans:

• $${variable} is expanded once when FreeSWITCH™ first parses the configuration on startup or after invoking reloadxml. It is suitable for variables that do not change, such as the domain of a single-tenant FreeSWITCH™ server. That is why $${domain} is referenced so frequently in the vanilla dialplan examples. 
• ${variable} is expanded during each pass through the dialplan, so it is used for variables that are expected to change, such as the ${destination_number} or ${sip_to_user} fields.

Channel Variables in the XML Dialplan

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

Reading channel variables requires the ${} syntax:

Scoped Variables

Channel variables used to be global to the session. As of b2c3199f, it is possible to set variables that only exist within a single application execution and any subsequent applications under it. For example, applications can use scoped variables for named input params:

Channel Variables in Dial Strings

The variable assignment syntax for dial strings differs depending on which scope they should apply to:

• {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 a dial string. It will set the same variables on every channel, including all thos in an enterprise bridging/originate.
• [foo=bar] goes before each individual dial string and will set the variable values specified for only this channel.

ExamplesSet foo variable for all channels implemented and chan=1 will only be set for blah, while chan=2 will only be set for blah2:

Set multiple variables by delimiting with commas:

To have variables in [] override variables in {}, set local_var_clobber=true inside {}. You must also set local_var_clobber=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):

Escaping/Redefining Delimiters

Commas are the default delimiter inside variable assignment tags. In some cases (like in absolute_codec_string), we may need to define variables whose values contain literal commas that should not be interpreted as delimiters. We can redefine the delimiter for a variable using ^^ followed by the desired delimiter:

To set absolute_codec_string=PCMA@8000h@20i@64000b,PCMU@8000h@20i@64000b,G729@8000h@20i@8000b in a dial string:

This approach does not work when setting sip_h_, sip_rh_, and sip_ph headers. To pass a comma into the contents of a private header, escape the comma with a backslash:

Exporting Channel Variables in Bridge Operations

Variables from one call leg (A) can be exported to the other call leg (B) by using the export_vars variable. Its value is a comma separated list of variables that should propagate across calls.

To set a variable on the A-leg and add it to the export list, use the export application:

Using Channel Variables in Dialplan Condition Statements

Channel variables can be used in conditions, refer to XML Dialplan Conditions for more information. Some channel variables may not be set during the dialplan parsing phrase. See Inline Actions.

Custom Channel Variables

We are not constrained to the channel variables that FreeSWITCH™, its modules, and applications define. It is possible to set any number of unique channel variables for any purpose. They can also be logged in CDR. The set application can be used to set any channel variable:

In a command issued via mod_xml_rpc or mod_event_socket:

Values with spaces must be enclosed by quotes:

Channel Variable Manipulation

Channel variables can be manipulated for varied results. For example, a channel variable could be trimmed to get the first three digits of a phone number. Manipulating Channel Variables discusses this in detail.

Channel Variable Scope Example

Consider this example:

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

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

Accessing Channel Variables in Other Environments

In addition to the dialplan, channel variables can be set in other environments as well.In a  FreeSWITCH™ module, written in C:

In the console (or fs_cli, implemented in mod_commands): 

Alternatively, call uuid_dump to get all the variables, or use the eval command, adding the prefix variable_ to the key:

In an event socket, just extend the above with the api prefix:

In Lua, there are several ways to interact with variables. In the freeswitch.Session() invocation that creates a new Session object, variables go in square brackets:

With the new Session object s:

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: