Using Variables in Asterisk Dialplans

Asterisk can make use of global and channel-specific variables for arguments to commands. Variables are referenced in the dialplan (extensions.conf) using the syntax

${foo}

where foo is the name of the variable. A variable name may be any alphanumeric string beginning with a letter. User-defined variable names are not case sensitive — ${FOO} and ${Foo} refer to the same variable — but Asterisk-defined variables are case-sensitive — ${EXTEN} works, but ${exten} doesn't.

There are three types of variables: global variables, channel variables, and environment variables.

Global variables can be set either in the [globals] category of extensions.conf or by using the SetGlobalVar command. Once defined, they can be referenced by any channel at any time.
Channel variables are set using the SetVar command. Each channel gets its own variable space, so there is no chance of collisions between different calls, and the variable is automatically trashed when the channel is hungup.
Environment variables provide a means to access unix environment variables from within Asterisk. There's a list further down this page.

If you define a channel variable with the same name as a global variable (and remember: user-defined variable names are not case sensitive), references to that variable name will return the value of the channel variable. For example, let us say that you define a context "FooTest" with a single extension, 100, with the following definition:

   [FooTest]
   exten => 100,1,SetGlobalVar(FOO=5)
   exten => 100,2,NoOp(${FOO})
   exten => 100,3,NoOp(${foo})
   exten => 100,4,SetVar(foo=8)
   exten => 100,5,NoOp(${FOO})
   exten => 100,6,NoOp(${foo})

(Note the use of the NoOp command to assist in debugging.) If you dial extension 100 in context FooTest, and you have Asterisk running with a verbose console, you will see output similar to the following:

   — Executing SetGlobalVar("Zap/1-1", "FOO=5") in new stack
   — Setting global variable 'FOO' to '5'
   — Executing NoOp("Zap/1-1", "5") in new stack
   — Executing NoOp("Zap/1-1", "5") in new stack
   — Executing SetVar("Zap/1-1", "foo=8") in new stack
   — Executing NoOp("Zap/1-1", "8") in new stack
   — Executing NoOp("Zap/1-1", "8") in new stack

We discover that after the call to SetGlobalVar, ${FOO} and ${foo} returned the value of the global variable, giving the value 5. After the call to SetVar, the global variable "foo" was obscured by the channel variable "foo"; ${FOO} and ${foo} both gave the value 8. The value of the global variable remains unchanged at 5, however, and any other channels that refer to the global variable ${foo} would still get the value 5.

Predefined Channel Variables

There are some channel variables set by Asterisk that you can refer to in your dialplan definitions. Asterisk-defined variables, in contrast to user-defined variables, are case sensitive.

${CONTEXT}: The name of the current context
${DATETIME}: Current date time in the format: YYYY-MM-DD_HH:MM:SS
${TIMESTAMP}: Current date time in the format: YYYYMMDD-HHMMSS
${EPOCH}: The current UNIX-style epoch (number of seconds since 1 Jan 1970)
${EXTEN}: The current extension
${INVALID_EXTEN}: The extension asked for when redirected to the i (invalid) extension
${LANGUAGE}: The current language setting. See Asterisk multi-language
${PRIORITY}: The current priority
${CALLERID}: The current Caller ID (name and number)
${CALLERIDNAME}: The current Caller ID name
${CALLERIDNUM}: The current Caller ID number
${CHANNEL}: Current channel name
${RDNIS}: The current redirecting DNIS, Caller ID that redirected the call. See RDNIS
${SIPDOMAIN}: SIP destination domain of an inbound call (if appropriate)
${SIP_CODEC}: Used to set the SIP codec for a call
${SIPCALLID}: The SIP dialog Call-ID: header
${SIPUSERAGENT}: The SIP user agent header
${UNIQUEID}: Current SIP call unique ID
${HANGUPCAUSE}: The last hangup return code on a Zap channel connected to a PRI interface
${DNID}: Dialed Number Identifier
${ACCOUNTCODE}: Account code, if specified - see Asterisk billing

Application-specific variables

Some applications take extra input or provide output using channel variables.

ChanIsAvail returns ${AVAILCHAN}: The first available channel
Dial takes input from ${VXML_URL}: Send XML Url to Cisco 7960
Dial takes input from ${ALERT_INFO}: Set ring cadence for Cisco phones
Dial returns ${CAUSECODE}: If the dial failed, this is the errormessage
EnumLookup returns ${ENUM}: The result of the lookup
TXTLookup returns ${TXTCIDNAME}: The result of the DNS lookup
MeetMe takes input from {MEETME_AGI_BACKGROUND}: An AGI script to run
MeetMe returns ${MEETMESECS}: The number of seconds the user was in a conference

Macro-specific variables

When in a macro context, extra channel variables are available.

${ARG1}: The first argument passed to the macro
${ARG2}: The second argument passed to the macro (and so on)
${MACRO_CONTEXT}: The context of the extension that triggered this macro
${MACRO_EXTEN}: The extension that triggered this macro
${MACRO_PRIORITY}: The priority in the extension where this macro was triggered
${MACRO_OFFSET}: Set by a macro to influence the priority where execution will continue after exiting the macro

Environment Variables

You may access unix environment variables using the syntax:

${ENV(foo)}

${ENV(ASTERISK_PROMPT)}: the current Asterisk CLI prompt.
${ENV(RECORDED_FILE)}: the filename of the last file saved by the Record command (available in CVS > 2004-03-21)

String Handling Functions

String Length

   ${LEN(foo)}

returns the length of the string foo. For example,

   exten => 100,1,SetVar(Fruit=pear)
   exten => 100,2,NoOp(${LEN(Fruit)})
   exten => 100,3,NoOp(${LEN(${Fruit})})

The first NoOp would show a value of 5 (the length of the string "fruit"). The second NoOp would show a value of 4 (the length of the string "pear").

Substrings

${foo:offset:length}

returns a substring of the string foo, beginning at offset offset and returning the next length characters.

If offset is negative, it is taken leftwards from the right hand end of the string.
If length is omitted or is negative, then all the rest of the string beginning at offset is returned.

Examples:

   ${123456789:1}        - returns the string 23456789
   ${123456789:-4}       - returns the string 6789
   ${123456789:0:3}      - returns the string 123
   ${123456789:2:3}      - returns the string 345
   ${123456789:-4:3}     - returns the string 678

Examples of use:

   exten => _NXX.,1,SetVar(areacode=${EXTEN:0:3})   - get the first 3 digits of ${EXTEN}
   exten => _516XXXXXXX,1,Dial(${EXTEN:3})          - get all but the first 3 digits of ${EXTEN}
   exten => 100,1,SetVar(whichVowel=4)
   exten => 100,2,SetVar(foo=AEIOU:${whichVowel}:1) - sets ${foo} to the single letter 'U'

See also

Cut: Extract a substring based on a field delimiter

String Concatenation

To concatenate two strings, simply write them together:

   ${foo}${bar}
   555{$theNumber}
   ${longDistancePrefix}555{$theNumber}