Tuesday, August 5, 2008

Asterisk Detailed Variable List

Asterisk standard channel variables

There are a number of variables that are defined or read
by Asterisk. Here is a list of them. More information is
available in each application's help text. All these variables
are in UPPER CASE only.

Variables marked with a * are builtin functions and can't be set,
only read in the dialplan. Writes to such variables are silently

${ACCOUNTCODE} * Account code (if specified) (Deprecated; use ${CDR(accountcode)})
${BLINDTRANSFER} The name of the channel on the other side of a blind transfer
${BRIDGEPEER} Bridged peer
${CALLERANI} * Caller ANI (PRI channels) (Deprecated; use ${CALLERID(ani)})
${CALLERID} * Caller ID (Deprecated; use ${CALLERID(all)})
${CALLERIDNAME} * Caller ID Name only (Deprecated; use ${CALLERID(name)})
${CALLERIDNUM} * Caller ID Number only (Deprecated; use ${CALLERID(num)})
${CALLINGANI2} * Caller ANI2 (PRI channels)
${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels)
${CALLINGTNS} * Transit Network Selector (PRI channels)
${CALLINGTON} * Caller Type of Number (PRI channels)
${CHANNEL} * Current channel name
${CONTEXT} * Current context
${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS (Deprecated; use ${STRFTIME(${EPOCH},,%d%mNaVH:NaVS)})
${DB_RESULT} Result value of DB_EXISTS() dial plan function
${DNID} * Dialed Number Identifier (Deprecated; use ${CALLERID(dnid)})
${EPOCH} * Current unix style epoch
${EXTEN} * Current extension
${ENV(VAR)} Environmental variable VAR
${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority
after a blind transfer (use ^ characters in place of
| to separate context/extension/priority when setting
this variable from the dialplan)
${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound)
${HINT} * Channel hints for this extension
${HINTNAME} * Suggested Caller*ID name for this extension
${INVALID_EXTEN} The invalid called extension (used in the "i" extension)
${LANGUAGE} * Current language (Deprecated; use ${LANGUAGE()})
${LEN(VAR)} * String length of VAR (integer)
${PRIORITY} * Current priority in the dialplan
${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed
${RDNIS} * Redirected Dial Number ID Service (Deprecated; use ${CALLERID(rdnis)})
${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS (Deprecated; use ${STRFTIME(${EPOCH},,%Y%mNaVH%M%S)})
${TRANSFER_CONTEXT} Context for transferred calls
${FORWARD_CONTEXT} Context for forwarded calls
${UNIQUEID} * Current call unique identifier
${SYSTEMNAME} * value of the systemname option of asterisk.conf

Application return values

In Asterisk 1.2, many applications return the result in a variable
instead of, as in Asterisk 1.0, changing the dial plan priority (+101).
For the various status values, see each application's help text.

${AGISTATUS} * agi()
${AQMSTATUS} * addqueuemember()
${AVAILSTATUS} * chanisavail()
${CHECKGROUPSTATUS} * checkgroup()
${CHECKMD5STATUS} * checkmd5()
${CPLAYBACKSTATUS} * controlplayback()
${DIALSTATUS} * dial() - see also ${HANGUPCAUSE}
${DBGETSTATUS} * dbget()
${ENUMSTATUS} * enumlookup()
${HASVMSTATUS} * hasnewvoicemail()
${LOOKUPBLSTATUS} * lookupblacklist()
${OSPAUTHSTATUS} * ospauth()
${OSPLOOKUPSTATUS} * osplookup()
${OSPNEXTSTATUS} * ospnext()
${OSPFINISHSTATUS} * ospfinish()
${PARKEDAT} * parkandannounce()
${PLAYBACKSTATUS} * playback()
${PQMSTATUS} * pausequeuemember()
${PRIVACYMGRSTATUS} * privacymanager()
${QUEUESTATUS} * queue()
${RQMSTATUS} * removequeuemember()
${SENDIMAGESTATUS} * sendimage()
${SENDTEXTSTATUS} * sendtext()
${SENDURLSTATUS} * sendurl()
${SYSTEMSTATUS} * system()
${TRANSFERSTATUS} * transfer()
${TXTCIDNAMESTATUS} * txtcidname()
${UPQMSTATUS} * unpausequeuemember()
${VMSTATUS} * voicmail()
${VMBOXEXISTSSTATUS} * vmboxexists()
${WAITSTATUS} * waitforsilence()

Various application variables

${CURL} * Resulting page content for curl()
${ENUM} * Result of application EnumLookup
${EXITCONTEXT} Context to exit to in IVR menu (app background())
or in the RetryDial() application
${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor())
${MONITOR_EXEC} Application to execute after monitoring a call
${MONITOR_EXEC_ARGS} Arguments to application
${MONITOR_FILENAME} File for monitoring (recording) calls in queue
${QUEUE_PRIO} Queue priority
${QUEUE_MAX_PENALTY} Maximum member penalty allowed to answer caller
${QUEUESTATUS} Status of the call, one of:
${RECORDED_FILE} * Recorded file in record()
${TALK_DETECTED} * Result from talkdetect()
${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record)
${TOUCH_MONITOR_FORMAT} The audio format to use with Touch Monitor (auto record)
${TOUCH_MONITOR_OUTPUT} * Recorded file from Touch Monitor (auto record)
${TXTCIDNAME} * Result of application TXTCIDName
${VPB_GETDTMF} chan_vpb

The MeetMe Conference Bridge uses the following variables:

${MEETME_RECORDINGFILE} Name of file for recording a conference with
the "r" option
${MEETME_RECORDINGFORMAT} Format of file to be recorded
${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting
${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only)
${MEETMESECS} * Number of seconds a user participated in a MeetMe conference

The VoiceMail() application uses the following variables:

${VM_CATEGORY} Sets voicemail category
${VM_NAME} * Full name in voicemail
${VM_DUR} * Voicemail duration
${VM_MSGNUM} * Number of voicemail message in mailbox
${VM_CALLERID} * Voicemail Caller ID (Person leaving vm)
${VM_CIDNAME} * Voicemail Caller ID Name
${VM_CIDNUM} * Voicemail Caller ID Number
${VM_DATE} * Voicemail Date
${VM_MESSAGEFILE} * Path to message left by caller

The VMAuthenticate() application uses the following variables:

${AUTH_MAILBOX} * Authenticated mailbox
${AUTH_CONTEXT} * Authenticated mailbox context

DUNDiLookup() uses the following variables

${DUNDTECH} * The Technology of the result from a call to DUNDiLookup()
${DUNDDEST} * The Destination of the result from a call to DUNDiLookup()

The Zaptel channel sets the following variables:

${ANI2} * The ANI2 Code provided by the network on the incoming call. (ie, Code 29 identifies call as a Prison/Inmate Call) See also: NANPA ANI II Digits Assignments
${CALLTYPE} * Type of call (Speech, Digital, etc)
${CALLEDTON} * Type of number for incoming PRI extension
i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific,
4=subscriber, 6=abbreviated, 7=reserved
${CALLINGSUBADDR} * Called PRI Subaddress
${FAXEXTEN} * The extension called before being redirected to "fax"
${PRIREDIRECTREASON} * Reason for redirect, if a call was directed
${SMDI_VM_TYPE} * When an call is received with an SMDI message, the 'type'
of message 'b' or 'u'

The SIP channel uses the following variables:

${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching)
${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate)
${SIPUSERAGENT} * SIP user agent
${SIPURI} * SIP uri
${SIP_CODEC} Set the SIP codec for a call
${SIP_URI_OPTIONS} * additional options to add to the URI for an outgoing call
${RTPAUDIOQOS} RTCP QoS report for the audio of this call
${RTPVIDEOQOS} RTCP QoS report for the video of this call

The Agent channel uses the following variables:

${AGENTMAXLOGINTRIES} Set the maximum number of failed logins
${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data
${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out
${AGENTACKCALL} Whether the agent should acknowledge the incoming call
${AGENTAUTOLOGOFF} Auto logging off for an agent
${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls
${AGENTNUMBER} * Agent number (username) set at login
${AGENTSTATUS} * Status of login ( fail | on | off )
${AGENTEXTEN} * Extension for logged in agent

The Dial() application uses the following variables:

${DIALEDPEERNAME} * Dialed peer name
${DIALEDPEERNUMBER} * Dialed peer number
${DIALEDTIME} * Time for the call (seconds)
${ANSWEREDTIME} * Time from dial to answer (seconds)
${DIALSTATUS} * Status of the call, one of:
${DYNAMIC_FEATURES} * The list of features (from the applicationmap section of
features.conf) to activate during the call, with feature
names separated by '#' characters
${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits
${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits
${LIMIT_WARNING_FILE} Soundfile for call limits
${LIMIT_TIMEOUT_FILE} Soundfile for call limits
${LIMIT_CONNECT_FILE} Soundfile for call limits
${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup)
  • See "show application dial" for more information

The chanisavail() application sets the following variables:

${AVAILCHAN} * the name of the available channel if one was found
${AVAILORIGCHAN} * the canonical channel name that was used to create the channel
${AVAILSTATUS} * Status of requested channel

When using macros in the dialplan, these variables are available

${MACRO_EXTEN} * The calling extensions
${MACRO_CONTEXT} * The calling context
${MACRO_PRIORITY} * The calling priority
${MACRO_OFFSET} Offset to add to priority at return from macro

The ChanSpy() application uses the following variables:

${SPYGROUP} * A ':' (colon) separated list of group names.
(To be set on spied on channel and matched against the g(grp) option)

If you compile with OSP support, these variables are used:

${OSPINHANDLE} OSP handle of in_bound call
${OSPINTIMELIMIT} Duration limit for in_bound call
${OSPOUTHANDLE} OSP handle of out_bound call
${OSPTECH} OSP technology
${OSPDEST} OSP destination
${OSPCALLING} OSP calling number
${OSPOUTTOKEN} OSP token to use for out_bound call
${OSPOUTTIMELIMIT} Duration limit for out_bound call
${OSPRESULTS} Number of remained destinations

CDR Variables

If the channel has a cdr, that cdr record has it's own set of variables which
can be accessed just like channel variables. The following builtin variables
are available and, unless specified, read-only.

${CDR(clid)} Caller ID
${CDR(src)} Source
${CDR(dst)} Destination
${CDR(dcontext)} Destination context
${CDR(channel)} Channel name
${CDR(dstchannel)} Destination channel
${CDR(lastapp)} Last app executed
${CDR(lastdata)} Last app's arguments
${CDR(start)} Time the call started.
${CDR(answer)} Time the call was answered.
${CDR(end)} Time the call ended.
${CDR(duration)} Duration of the call.
${CDR(billsec)} Duration of the call once it was answered.
${CDR(accountcode)} The channel's account code (read-write).
${CDR(uniqueid)} The channel's unique id.
${CDR(userfield)} The channels uses specified field (read-write).

In addition, you can set your own extra variables with a traditional
Set(CDR(var)=val) to anything you want.

NOTE Some CDR values (eg: duration & billsec) can't be accessed until the call has terminated. As of 91617, those values will be calculated on-demand if requested. Until that makes it into a stable release, you can set endbeforehexten=yes in cdr.conf, and then use the "hangup" context to wrap up your call.

Certain functional variables may be accessed with ${foo()}. A list
of these functional variables may be found by typing "show functions"
at the Asterisk CLI.

Asterisk variables

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


where foo is the name of the variable, offset is an optional field indicating which characters should be excluded, and length is an optional field indicating the number of characters from the offset to be returned (see "Substrings" below for details and examples). 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 Set command (previously "setvar"). 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:(:smile:)

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.

Inheritance of Channel Variables

Prepending a single _ character to a variables name in SetVar will cause that variable to be inherited by channels created by the main channel. eg. when using Dial(Local/...); once inherited these variables will not be further inherited. Prepending two _ characters will cause them to be inherited indefinitely.

Note that for retrieval purposes these variable names do not include the underscores.

exten => 100,1,SetVar(__FOO=5)
exten => 100,2,Dial(Local/test@CheckInherit)
exten => test,1,NoOp(${FOO})

will result in FOO being inherited. Without the underscores, the new local channel would start with a clean slate.


exten => 104,1,SetVar(FEE=fee)
exten => 104,2,SetVar(_FIE=fie)
exten => 104,3,SetVar(__FUM=fum)
exten => 104,4,Dial(Local/105)

exten => 105,1,NoOp(${FEE})
exten => 105,2,NoOp(${FIE})
exten => 105,3,NoOp(${FUM})
exten => 105,4,Dial(Local/106)

exten => 106,1,NoOp(${FEE})
exten => 106,2,NoOp(${FIE})
exten => 106,3,NoOp(${FUM})

results in

— Executing SetVar("SIP/oberon-365e", "FEE=fee") in new stack
— Executing SetVar("SIP/oberon-365e", "_FIE=fie") in new stack
— Executing SetVar("SIP/oberon-365e", "__FUM=fum") in new stack
— Executing Dial("SIP/oberon-365e", "Local/105") in new stack
— Called 105
— Executing NoOp("Local/105@default-7263,2", "") in new stack
— Executing NoOp("Local/105@default-7263,2", "fie") in new stack
— Executing NoOp("Local/105@default-7263,2", "fum") in new stack
— Executing Dial("Local/105@default-7263,2", "Local/106") in new stack
— Called 106
— Executing NoOp("Local/106@default-49be,2", "") in new stack
— Executing NoOp("Local/106@default-49be,2", "") in new stack
— Executing NoOp("Local/106@default-49be,2", "fum") in new stack

(This did not work correctly prior to the 1.2 release.)

Using $

If you want to set a global variable containing the another variable name in the [globals] category of extensions.conf you have to do something like this:


This way the MY_VAR value is ${EPOCH}-${EXTEN}.gsm

Using it with the EVAL() function is very useful. I.e. if you want to record you can do this:

exten => 104,1,SetVar(file=${EVAL(${MY_VAR})})
exten => 104,2,MixMonitor($The attachment id given is not valid.)

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. Note: Several of these builtin variables have been converted to functions in 1.2, to allow setting their values.
  • ${ACCOUNTCODE}: Account code, if specified - see Asterisk billing (DEPRECATED in 1.2.0 and removed in 1.4. Use ${CDR(accountcode)}
  • ${ANSWEREDTIME}: This is the amount of time(in seconds) for actual call.
  • ${BLINDTRANSFER}: The active SIP channel that dialed the number. This will return the SIP Channel that dialed the number when doing blind transfers - see BLINDTRANSFER
  • ${CALLERID(all)}: The current Caller ID name and number - See Setting Callerid for usage in Asterisk 1.4
  • ${CALLERID(name)}: The current Caller ID name - ${CALLERIDNAME} was used in versions of Asterisk prior to 1.2.0, it was DEPRECATED in 1.2.0 and removed in 1.4.
  • ${CALLERID(num)}: The current Caller ID number - ${CALLERIDNUM} was used in versions of Asterisk prior to 1.2.0, it was DEPRECATED in 1.2.0 and removed in 1.4.
(Note: this is not necessarily numeric as the name would indicate and can legitimately contain the space character. Commands acting on this variable (such as 'GotoIf', for example) should be aware of this).
  • ${CALLINGPRES}: PRI Call ID Presentation variable for incoming calls (See callingpres )
  • ${CHANNEL}: Current channel name
  • ${CONTEXT}: The name of the current context
  • ${DATETIME}: Current date time in the format: DDMMYYYY-HH:MM:SS This is deprecated in Asterisk 1.2, instead use :${STRFTIME(${EPOCH},,%d%mNaVH:NaVS)})
  • ${DIALEDPEERNAME}: Name of the called party. Broken for now, see DIALEDPEERNAME
  • ${DIALEDPEERNUMBER}: Number of the called party. Broken for now, see DIALEDPEERNUMBER
  • ${DIALEDTIME}: Time since the number was dialed (only works when dialed party answers the line?!)
  • ${DIALSTATUS}: Status of the call. See DIALSTATUS (note: In the current SVN release, DIALSTATUS seems to have been removed. Now you should use the DEVSTATE function. Try in astersisk console "core show function DEVSTATE" for more informations)
  • ${DNID}: Dialed Number Identifier. Limitations apply, see DNID
  • ${EPOCH}: The current UNIX-style epoch (number of seconds since 1 Jan 1970)
  • ${EXTEN}: The current extension
  • ${HANGUPCAUSE}: The last hangup return code on a Zap channel connected to a PRI interface
  • ${INVALID_EXTEN}: The extension asked for when redirected to the i (invalid) extension
  • ${LANGUAGE}: The current language setting. See Asterisk multi-language
  • ${MEETMESECS}: Number of seconds a user participated in a MeetMe conference
  • ${PRIORITY}: The current priority
  • ${RDNIS}: The current redirecting DNIS, Caller ID that redirected the call. Limitations apply, see RDNIS
  • ${SIPDOMAIN}: SIP destination domain of an inbound call (if appropriate)
  • ${SIP_CODEC}: Used to set the SIP codec for a call (apparently broken in Ver 1.0.1, ok in Ver. 1.0.3 & 1.0.4, not sure about 1.0.2)
  • ${SIPCALLID}: The SIP dialog Call-ID: header
  • ${SIPUSERAGENT}: The SIP user agent header
  • ${TIMESTAMP}: Current date time in the format: YYYYMMDD-HHMMSS This is deprecated as of Asterisk 1.4, instead use :${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)})
  • ${TRANSFERCAPABILITY}: Type of Channel
  • ${TXTCIDNAME}: Result of application TXTCIDName (see below)
  • ${UNIQUEID}: Current call unique identifier
  • ${TOUCH_MONITOR}: used for "one touch record" (see features.conf, and wW dial flags). If is set on either side of the call then that var contains the app_args for app_monitor otherwise the default of WAV||m is used

Application-specific variables

Some applications take extra input or provide output using channel variables.
  • AgentCallbackLogin returns ${AGENTBYCALLERID_${CALLERID}}: The ID of the agent successfully logged on.
  • ChanIsAvail returns ${AVAILCHAN}: The first available channel
  • Dial takes input from ${VXML_URL}: Send XML Url to Cisco 7960 or to i6net VoiceXML browser
  • Dial takes input from ${ALERT_INFO}: Set ring cadence or allow intercom on for various SIP phones
  • Dial returns ${CAUSECODE}: If the dial failed, this is the errormessage
  • Dial returns ${DIALSTATUS}: Text code returning status of last dial attempt.
  • Dial takes input from ${TRANSFER_CONTEXT}: If this variable exists, when a #transfer is executed it goes to the selected extension on this context.
  • EnumLookup returns ${ENUM}: The result of the lookup
  • Hangup reads the ${PRI_CAUSE} variable for setting PRI return codes
  • 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
  • Playback returns ${PLAYBACKSTATUS}: The status of the command (FAILED|SUCCESS)
  • Queue returns ${QUEUESTATUS}: The reason for popping the call out of the queue
  • TXTCIDName returns ${TXTCIDNAME}: The result of the DNS lookup
  • VoiceMail returns ${VMSTATUS}: indicates the status of the execution of the VoiceMail application. Possible values are: SUCCESS | USEREXIT | FAILED .

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_OFFSET}: Set by a macro to influence the priority where execution will continue after exiting the macro
  • ${MACRO_PRIORITY}: The priority in the extension where this macro was triggered

Environment Variables

You may access unix environment variables using the syntax:


  • ${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


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

This is an excellent way to check for a NULL or empty string.



returns a substring of the string foo, beginning at offset offset and returning the next length characters. The first character is at offset 0.
  • 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.


${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'

String Concatenation

To concatenate two strings, simply write them together:


Variable math

To perform math on variables e.g. increment, multiplication, addition simply write:

exten => s,1,SetVar(SOMEVAR=$[${SOMEVAR} + 1]) ; increment
exten => s,2,SetVar(SOMEVAR=$[2 * ${SOMEVAR}]) ; multiplication etc...
In times past, a single space was required between items in the $[...] expressions. This is no longer the case!

In late model Asterisks (1.2?), the MATH function is also available...

exten => s,1,Set(SOMEVAR=${MATH(${SOMEVAR}+1)}) ; increment
exten => s,2,Set(SOMEVAR=${MATH(2*${SOMEVAR})}) ; multiplication etc...

Asterisk functions

Asterisk functions are used in Asterisk's dialplan. Unlike dialplan applications, they cannot be used directly. Instead they return a value that could be used by the dialplan logic.

Functions are new in 1.2. Some functions may be read from, others may be written to. Please note that several of the builtin variables (including ENV and LEN) have been converted to functions for 1.2.

Functions in the below list are marked in red if they are only available in version 1.4 and higher.

Functions in the below list are marked in blue if they are only available in version 1.6 and higher.

Function names by practice are all capitalzed letters. The names ARE CASE SENSITIVE!

Function List

  • AGENT: Gets information about an Agent
  • ARRAY: Allows setting multiple variables at once
  • BASE64_DECODE: Decode a base64 string
  • BASE64_ENCODE: Encode a string into base64
  • CALLERID: Get or set Caller*ID
  • CDR: Get or set a CDR variable
  • CHANNEL: Gets/sets various pieces of information about the channel.
  • CHECKSIPDOMAIN: Checks if domain is a local domain
  • CHECK_MD5: Checks an MD5 digest. Deprecated in 1.4, since it can be done with an expression in combination with MD5.
  • Asterisk func clearhash: New in 1.6
  • CURL: Retrieves a URL
  • CUT: String parsing, based upon a delimiter
  • Asterisk func device_State): New in 1.6 allows retrieving any device state in the dialplan, as well as creating custom device states that are controllable from the dialplan
  • DB: Get or set a value in the AstDB
  • DB_DELETE: Delete a value from the AstDB; replaces the DBDel application
  • DB_EXISTS: Check to see if a key exists in the Asterisk database
  • DIALGROUP: New in 1.6: Poor man's calling queue
  • Asterisk func dialplan_exists: New in 1.6 Check for the existence of a dialplan target
  • DUNDILOOKUP: Do a DUNDi lookup of a phone number.
  • ENUMLOOKUP: General or specific querying of NAPTR records or counts of NAPTR types for ENUM or ENUM-like DNS pointers
  • ENV: Get or set an environmental variable
  • EVAL: Evaluate stored variables.
  • EXISTS: Existence Test: Returns 1 if exists, 0 otherwise
  • Asterisk func extension_state: New in 1.6 Allows retrieving the state of any extension
  • FIELDQTY: Get the number of fields, based upon a delimiter
  • FILTER: Filter the string to include only the allowed characters
  • GROUP: Can also return the name of the group set on a channel when used in a read environment
  • GROUP_COUNT: Counts the number of channels in the specified group
  • GROUP_LIST: Returns a space separated list of all of the groups set on a channel
  • GROUP_MATCH_COUNT: Counts the number of channels in the groups matching the specified pattern
  • HASH: New in 1.6
  • Asterisk func hashkeys: New in 1.6
  • Asterisk func hint: New in 1.6 Allows retrieving hint information
  • IAXPEER: Gets IAX peer information
  • Asterisk func iaxvar: Pass variables over IAX channels, somewhat similar to SIPADDHEADER() and SIP_HEADER()
  • IF: Conditional: Returns the data following '?' if true else the data following ':'
  • IFTIME: Temporal Conditional: Returns the data following '?' if true else the data following ':'
  • ISNULL: NULL Test: Returns 1 if NULL or 0 otherwise
  • KEYPADHASH: Hash the letters in the string into the equivalent keypad numbers.
  • LANGUAGE: Get or set the channel's language
  • LEN: Get the length of an arbitrary string
  • MATH: Performs Mathematical Functions
  • MD5: Computes an MD5 digest
  • MUSICCLASS: Get or set the MusicOnHold class
  • ODBC: Generic database access/queries using ODBC
  • QUEUEAGENTCOUNT: Gets the number of members currently listening on a queue. Deprecated in favor of QUEUE_MEMBER_COUNT.
  • QUEUE_MEMBER_COUNT: Count number of members answering a queue
  • QUEUE_MEMBER_LIST: Returns a list of interfaces on a queue
  • QUOTE: Quotes a given string, escaping embedded quotes as necessary
  • RAND: Choose a random number in a range
  • REALTIME: This function will read or write values from/to a RealTime repository.
  • REGEX: Regular Expression: Returns 1 if data matches regular expression.
  • SET: SET assigns a value to a channel variable
  • SHA1: Computes a SHA1 digest
  • SIPCHANINFO: Gets the specified SIP parameter from the current channel
  • SIPPEER: Gets SIP peer information
  • Asterisk func SIPAddHeader: Typically used to set Alert-Info information, e.g. ring tone .wav files
  • SIP_HEADER: Gets or sets the specified SIP header
  • SORT: Sorts a list of keys and values into a list of keys
  • SQL_ESC: Escapes a value for inclusion in an SQL call (prevent injection attacks).
  • STAT: Does a check on the specified file
  • STRFTIME: Formats an epoch into an arbitrary datetime string
  • STRPTIME: Returns the epoch of the arbitrary date/time string structured as described in the format.
  • Asterisk func sysinfo: New in 1.6 Allows retrieval of system information
  • TIMEOUT: Gets or sets timeouts on the channel.
  • Asterisk func toupper: New in 1.6 Converts a string to uppercase
  • Asterisk func tolower: New in 1.6 Converts a string to lowercase
  • TXTCIDNAME: TXTCIDNAME looks up a caller name via DNS
  • URIDECODE: Decodes an URI-encoded string.
  • URIENCODE: Encodes a string to URI-safe encoding.
  • VMCOUNT: Counts the voicemail in a specified mailbox

Using functions in Asterisk dialplans

Example usage of the function CUT:

exten => s,1,Set(foo=${CUT(bar,,2)})

The above example sets the variable foo to the function CUT whose first parameter is 'bar', second parameter is empty and third parameter is '2'.

A function is often used to determain which "part of a variable" to set. For instance, the use of the function CALLERID:

exten => s,n,Set(CALLERID(name)=Foo Fighters)
exten => s,n,Set(CALLERID(number)=700)

Functions Reference Through the CLI

The list of availble functions depends on the modules installed and loaded on the current system. To get the list of functions from the Asterisk CLI use the command show functions . This gives a list of all functions.

To get the syntax of a specific function, use the command show function FUNCNAME. This gives a longer description of the function. It is often handy to use tab completion that way to identify a function name.