1 Asterisk dial plan variables
2 ---------------------------
4 There are two levels of parameter evaluation done in the Asterisk
5 dial plan in extensions.conf.
6 * The first, and most frequently used, is the substitution of variable
7 references with their values.
8 * Then there are the evaluations of expressions done in $[ .. ].
9 This will be discussed below.
11 Asterisk has user-defined variables and standard variables set
12 by various modules in Asterisk. These standard variables are
13 listed at the end of this document.
15 ___________________________
17 ---------------------------
19 exten => s,5,BackGround,blabla
21 The parameter (blabla) can be quoted ("blabla"). In this case, a
22 comma does not terminate the field. However, the double quotes
23 will be passed down to the Background command, in this example.
25 Also, characters special to variable substitution, expression evaluation, etc
26 (see below), can be quoted. For example, to literally use a $ on the
27 string "$1231", quote it with a preceding \. Special characters that must
28 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\).
30 These Double quotes and escapes are evaluated at the level of the
31 asterisk config file parser.
33 Double quotes can also be used inside expressions, as discussed below.
35 ___________________________
37 ---------------------------
39 Parameter strings can include variables. Variable names are arbitrary strings.
40 They are stored in the respective channel structure.
42 To set a variable to a particular value, do :
44 exten => 1,2,SetVar(varname=value)
46 You can substitute the value of a variable everywhere using ${variablename}.
47 For example, to stringwise append $lala to $blabla and store result in $koko,
50 exten => 1,2,SetVar(koko=${blabla}${lala})
53 There are two reference modes - reference by value and reference by name.
54 To refer to a variable with its name (as an argument to a function that
55 requires a variable), just write the name. To refer to the variable's value,
56 enclose it inside ${}. For example, SetVar takes as the first argument
57 (before the =) a variable name, so:
59 exten => 1,2,SetVar(koko=lala)
60 exten => 1,3,SetVar(${koko}=blabla)
62 stores to the variable "koko" the value "lala" and to variable "lala" the
65 In fact, everything contained ${here} is just replaced with the value of
68 _______________________________
69 REMOVING CHARACTERS FROM STRING
70 -------------------------------
72 The format for removing characters from a variable can be expressed as:
74 ${variable_name[:offset[:length]]}
76 If you want to remove the first N characters from the string assigned
77 to a variable, simply append a colon and the number of characters to
78 remove from the beginning of the string to the variable name.
80 ;Remove the first character of extension, save in "number" variable
81 exten => _9X.,1,SetVar(number=${EXTEN:1})
83 Assuming we've dialed 918005551234, the value saved to the 'number' variable
84 would be 18005551234. This is useful in situations when we require users to
85 dial a number to access an outside line, but do not wish to pass the first
88 If you use a negative offset number, Asterisk starts counting from the end
89 of the string and then removes everything before the new position. The following
90 example will save the numbers 1234 to the 'number' variable, still assuming
91 we've dialed 918005551234.
93 ;Remove everything before the last four digits of the dialed string
94 exten => _9X.,1,SetVar(number=${EXTEN:-4})
96 We can also limit the number of characters from our offset position that we
97 wish to use. This is done by appending a second colon and length value to the
98 variable name. The following example will save the numbers 555 to the 'number'
101 ;Only save the middle numbers 555 from the string 918005551234
102 exten => _9X.,1,SetVar(number=${EXTEN:5:3})
104 The length value can also be used in conjunction with a negative offset. This
105 may be useful if the length of the string is unknown, but the trailing digits
106 are. The following example will save the numbers 555 to the 'number' variable,
107 even if the string starts with more characters than expected (unlike the
110 ;Save the numbers 555 to the 'number' variable
111 exten => _9X.,1,SetVar(number=${EXTEN:-7:3})
113 If a negative length value is entered, it is ignored and Asterisk will match
114 to the end of the string.
115 ___________________________
117 ---------------------------
119 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is
120 considered as an expression and it is evaluated. Evaluation works similar to
121 (but is done on a later stage than) variable substitution: the expression
122 (including the square brackets) is replaced by the result of the expression
124 Note: The arguments and operands of the expression MUST BE separated
125 by at least one space.
128 For example, after the sequence:
130 exten => 1,1,SetVar(lala=$[1 + 2])
131 exten => 1,2,SetVar(koko=$[2 * ${lala}])
133 the value of variable koko is "6".
137 exten => 1,1,SetVar(lala=$[1+2]);
139 will not work as you might have expected. Since all the chars in the single
140 token "1+2" are not numbers, it will be evaluated as the string "1+2". Again,
141 please do not forget, that this is a very simple parsing engine, and it
142 uses a space (at least one), to separate "tokens".
146 exten => 1,1,SetVar,"lala=$[ 1 + 2 ]";
148 will parse as intended. Extra spaces are ignored.
150 ___________________________
151 SPACES INSIDE VARIABLE
152 ---------------------------
153 If the variable being evaluated contains spaces, there can be problems.
155 For these cases, double quotes around text that may contain spaces
156 will force the surrounded text to be evaluated as a single token.
157 The double quotes will be counted as part of that lexical token.
161 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
163 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
164 but the above will evaluate to:
166 "DELOREAN MOTORS" : "Privacy Manager"
168 and will evaluate to 0.
170 The above without double quotes would have evaluated to:
172 DELOREAN MOTORS : Privacy Manager
174 and will result in syntax errors, because token DELOREAN is immediately
175 followed by token MOTORS and the expression parser will not know how to
176 evaluate this expression.
178 _____________________
180 ---------------------
181 Operators are listed below in order of increasing precedence. Operators
182 with equal precedence are grouped within { } symbols.
185 Return the evaluation of expr1 if it is neither an empty string
186 nor zero; otherwise, returns the evaluation of expr2.
189 Return the evaluation of expr1 if neither expression evaluates to
190 an empty string or zero; otherwise, returns zero.
192 expr1 {=, >, >=, <, <=, !=} expr2
193 Return the results of integer comparison if both arguments are
194 integers; otherwise, returns the results of string comparison
195 using the locale-specific collation sequence. The result of each
196 comparison is 1 if the specified relation is true, or 0 if the
200 Return the results of addition or subtraction of integer-valued
203 expr1 {*, /, %} expr2
204 Return the results of multiplication, integer division, or
205 remainder of integer-valued arguments.
208 The `:' operator matches expr1 against expr2, which must be a
209 regular expression. The regular expression is anchored to the
210 beginning of the string with an implicit `^'.
212 If the match succeeds and the pattern contains at least one regu-
213 lar expression subexpression `\(...\)', the string correspond-
214 ing to `\1' is returned; otherwise the matching operator
215 returns the number of characters matched. If the match fails and
216 the pattern contains a regular expression subexpression the null
217 string is returned; otherwise 0.
219 Parentheses are used for grouping in the usual manner.
221 The parser must be parsed with bison (bison is REQUIRED - yacc cannot
222 produce pure parsers, which are reentrant)
224 ___________________________
226 ---------------------------
228 There is one conditional operator - the conditional goto :
230 exten => 1,2,gotoif(condition?label1:label2)
232 If condition is true go to label1, else go to label2. Labels are interpreted
233 exactly as in the normal goto command.
235 "condition" is just a string. If the string is empty or "0", the condition
236 is considered to be false, if it's anything else, the condition is true.
237 This is designed to be used together with the expression syntax described
240 exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)
245 exten => s,2,SetVar(vara=1)
246 exten => s,3,SetVar(varb=$[${vara} + 2])
247 exten => s,4,SetVar(varc=$[${varb} * 2])
248 exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)
250 ___________________________
252 ---------------------------
254 Syntax errors are now output with 3 lines.
256 If the extensions.conf file contains a line like:
258 exten => s,6,GotoIf($[ "${CALLERIDNUM}" = "3071234567" & & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
260 You may see an error in /var/log/asterisk/messages like this:
262 May 3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
263 "3072312154" : "3071234567" & & "Steves Extension" : "Privacy Manager"
264 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
267 The first line shows the string passed to the expression parser. This
268 string is the result of the variable replacements, etc. This way, you
269 can see the actual string that went into the parser.
271 The second line usually shows a string of '^' chars, that show what's
272 been legally parsed so far.
274 And the third line shows where the parser was (lookahead token lexing,
275 etc), when the parse hit the rocks. A single '^' here. The error is
276 going to be somewhere between the last '^' on the second line, and the
277 '^' on the third line. That's right, in the example above, there are two
278 '&' chars, separated by a space, and this is a definite no-no!
281 ___________________________
283 ---------------------------
285 Testing to see if a string is null can be done in one of two different ways:
287 exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)
289 exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)
292 The second example above is the way suggested by the WIKI. It will
293 work as long as there are no spaces in the evaluated value.
295 The first way should work in all cases, and indeed, might now
296 be the safest way to handle this situation.
298 ___________________________
300 ---------------------------
302 If you need to do complicated things with strings, asterisk expressions
303 is most likely NOT the best way to go about it. AGI scripts are an
304 excellent option to this need, and make available the full power of
305 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
306 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
307 Pascal, APL, assembler, etc.
309 ---------------------------------------------------------
310 Asterisk standard channel variables
311 ---------------------------------------------------------
312 There are a number of variables that are defined or read
313 by Asterisk. Here is a list of them. More information is
314 available in each application's help text. All these variables
315 are in UPPER CASE only.
317 Variables marked with a * are builtin functions and can't be set,
318 only read in the dialplan. Writes to such variables are silently
321 ${ACCOUNTCODE} * Account code (if specified)
322 ${BLINDTRANSFER} The name of the channel on the other side of a blind transfer
323 ${BRIDGEPEER} Bridged peer
324 ${CALLERANI} * Caller ANI (PRI channels)
325 ${CALLERID} * Caller ID
326 ${CALLERIDNAME} * Caller ID Name only
327 ${CALLERIDNUM} * Caller ID Number only
328 ${CALLINGANI2} * Caller ANI2 (PRI channels)
329 ${CALLINGPRES} * Caller ID presentation for incoming calls (PRI channels)
330 ${CALLINGTNS} * Transit Network Selector (PRI channels)
331 ${CALLINGTON} * Caller Type of Number (PRI channels)
332 ${CHANNEL} * Current channel name
333 ${CONTEXT} * Current context
334 ${DATETIME} * Current date time in the format: DDMMYYYY-HH:MM:SS
335 ${DNID} * Dialed Number Identifier
336 ${EPOCH} * Current unix style epoch
337 ${EXTEN} * Current extension
338 ${ENV(VAR)} * Environmental variable VAR
339 ${GOTO_ON_BLINDXFR} Transfer to the specified context/extension/priority
340 after a blind transfer (use ^ characters in place of
341 | to separate context/extension/priority when setting
342 this variable from the dialplan)
343 ${HANGUPCAUSE} * Asterisk cause of hangup (inbound/outbound)
344 ${HINT} * Channel hints for this extension
345 ${HINTNAME} * Suggested Caller*ID name for this extension
346 ${INVALID_EXTEN} The invalid called extension (used in the "i" extension)
347 ${LANGUAGE} * Current language
348 ${LEN(VAR)} * String length of VAR (integer)
349 ${PRIORITY} * Current priority in the dialplan
350 ${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed
351 ${RDNIS} * Redirected Dial Number ID Service
352 ${TIMESTAMP} * Current date time in the format: YYYYMMDD-HHMMSS
353 ${TRANSFER_CONTEXT} Context for transferred calls
354 ${UNIQUEID} * Current call unique identifier
356 Various application variables
357 -----------------------------
358 ${CURL} * Resulting page content for curl()
359 ${ENUM} * Result of application EnumLookup
360 ${EXITCONTEXT} Context to exit to in IVR menu (app background())
361 or in the RetryDial() application
362 ${MONITOR} * Set to "TRUE" if the channel is/has been monitored (app monitor())
363 ${MONITOR_EXEC} Application to execute after monitoring a call
364 ${MONITOR_EXEC_ARGS} Arguments to application
365 ${MONITOR_FILENAME} File for monitoring (recording) calls in queue
366 ${QUEUE_PRIO} Queue priority
367 ${QUEUESTATUS} Status of the call, one of:
368 (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
369 ${RECORDED_FILE} * Recorded file in record()
370 ${TALK_DETECTED} * Result from talkdetect()
371 ${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record)
372 ${TXTCIDNAME} * Result of application TXTCIDName
373 ${VPB_GETDTMF} chan_vpb
375 The MeetMe Conference Bridge uses the following variables:
376 ----------------------------------------------------------
377 ${MEETME_RECORDINGFILE} Name of file for recording a conference with
379 ${MEETME_RECORDINGFORMAT} Format of file to be recorded
380 ${MEETME_EXIT_CONTEXT} Context for exit out of meetme meeting
381 ${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only)
382 ${MEETMESECS} * Number of seconds a user participated in a MeetMe conference
384 The VoiceMail() application uses the following variables:
385 ---------------------------------------------------------
386 ${VM_CATEGORY} Sets voicemail category
387 ${VM_NAME} * Full name in voicemail
388 ${VM_DUR} * Voicemail duration
389 ${VM_MSGNUM} * Number of voicemail message in mailbox
390 ${VM_CALLERID} * Voicemail Caller ID (Person leaving vm)
391 ${VM_CIDNAME} * Voicemail Caller ID Name
392 ${VM_CIDNUM} * Voicemail Caller ID Number
393 ${VM_DATE} * Voicemail Date
394 ${VM_MESSAGEFILE} * Path to message left by caller
396 The VMAuthenticate() application uses the following variables:
397 ---------------------------------------------------------
398 ${AUTH_MAILBOX} * Authenticated mailbox
399 ${AUTH_CONTEXT} * Authenticated mailbox context
401 DUNDiLookup() uses the following variables
402 ---------------------------------------------------------
403 ${DUNDTECH} * The Technology of the result from a call to DUNDiLookup()
404 ${DUNDDEST} * The Destination of the result from a call to DUNDiLookup()
406 The Zaptel channel sets the following variables:
407 ---------------------------------------------------------
408 ${ANI2} * The ANI2 Code provided by the network on the incoming call.
409 (ie, Code 29 identifies call as a Prison/Inmate Call)
410 ${CALLTYPE} * Type of call (Speech, Digital, etc)
411 ${CALLEDTON} * Type of number for incoming PRI extension
412 i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific,
413 4=subscriber, 6=abbreviated, 7=reserved
414 ${CALLINGSUBADDR} * Called PRI Subaddress
415 ${FAXEXTEN} * The extension called before being redirected to "fax"
416 ${PRIREDIRECTREASON} * Reason for redirect, if a call was directed
418 The SIP channel sets the following variables:
419 ---------------------------------------------------------
420 ${SIPCALLID} * SIP Call-ID: header verbatim (for logging or CDR matching)
421 ${SIPDOMAIN} * SIP destination domain of an inbound call (if appropriate)
422 ${SIPUSERAGENT} * SIP user agent
424 ${SIP_CODEC} Set the SIP codec for a call
426 The Agent channel uses the following variables:
427 ---------------------------------------------------------
428 ${AGENTMAXLOGINTRIES} Set the maximum number of failed logins
429 ${AGENTUPDATECDR} Whether to update the CDR record with Agent channel data
430 ${AGENTGOODBYE} Sound file to use for "Good Bye" when agent logs out
431 ${AGENTACKCALL} Whether the agent should acknowledge the incoming call
432 ${AGENTAUTOLOGOFF} Auto logging off for an agent
433 ${AGENTWRAPUPTIME} Setting the time for wrapup between incoming calls
434 ${AGENTNUMBER} * Agent number (username) set at login
435 ${AGENTSTATUS} * Status of login ( fail | on | off )
436 ${AGENTEXTEN} * Extension for logged in agent
438 The Dial() application uses the following variables:
439 ---------------------------------------------------------
440 ${DIALEDPEERNAME} * Dialed peer name
441 ${DIALEDPEERNUMBER} * Dialed peer number
442 ${DIALEDTIME} * Time for the call (seconds)
443 ${ANSWEREDTIME} * Time from dial to answer (seconds)
444 ${DIALSTATUS} * Status of the call, one of:
445 (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER | ANSWER | CANCEL)
446 ${LIMIT_PLAYAUDIO_CALLER} Soundfile for call limits
447 ${LIMIT_PLAYAUDIO_CALLEE} Soundfile for call limits
448 ${LIMIT_WARNING_FILE} Soundfile for call limits
449 ${LIMIT_TIMEOUT_FILE} Soundfile for call limits
450 ${LIMIT_CONNECT_FILE} Soundfile for call limits
451 ${OUTBOUND_GROUP} Default groups for peer channels (as in SetGroup)
452 * See "show application dial" for more information
454 The chanisavail() application sets the following variables:
455 -----------------------------------------------------------
456 ${AVAILCHAN} * the name of the available channel if one was found
457 ${AVAILORIGCHAN} * the canonical channel name that was used to create the channel
458 ${AVAILSTATUS} * Status of requested channel
460 When using macros in the dialplan, these variables are available
461 ---------------------------------------------------------
462 ${MACRO_EXTEN} * The calling extensions
463 ${MACRO_CONTEXT} * The calling context
464 ${MACRO_PRIORITY} * The calling priority
465 ${MACRO_OFFSET} Offset to add to priority at return from macro
467 If you compile with OSP support in the SIP channel, these
469 ---------------------------------------------------------
470 ${OSPHANDLE} Handle from the OSP Library
471 ${OSPTECH} OSP Technology from Library
472 ${OSPDEST} OSP Destination from Library
473 ${OSPTOKEN} OSP Token to use for call from Library
474 ${OSPRESULTS} Number of OSP results
476 ____________________________________
478 ------------------------------------
480 If the channel has a cdr, that cdr record has it's own set of variables which
481 can be accessed just like channel variables. The following builtin variables
484 ${CDR(clid)} Caller ID
486 ${CDR(dst)} Destination
487 ${CDR(dcontext)} Destination context
488 ${CDR(channel)} Channel name
489 ${CDR(dstchannel)} Destination channel
490 ${CDR(lastapp)} Last app executed
491 ${CDR(lastdata)} Last app's arguments
492 ${CDR(start)} Time the call started.
493 ${CDR(answer)} Time the call was answered.
494 ${CDR(end)} Time the call ended.
495 ${CDR(duration)} Duration of the call.
496 ${CDR(billsec)} Duration of the call once it was answered.
497 ${CDR(disposition)} ANSWERED, NO ANSWER, BUSY
498 ${CDR(amaflags)} DOCUMENTATION, BILL, IGNORE etc
499 ${CDR(accountcode)} The channel's account code.
500 ${CDR(uniqueid)} The channel's unique id.
501 ${CDR(userfield)} The channels uses specified field.
504 In addition, you can set your own extra variables with a traditional
505 SetVAR(CDR(var)=val) to anything you want.
507 Certain functional variables may be accessed with $(foo <args>). A list
508 of these functional variables may be found by typing "show functions"