fix typo
[asterisk/asterisk.git] / doc / README.variables
1 Asterisk dial plan variables 
2 ---------------------------
3
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.
10
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.
14
15 ___________________________
16 PARAMETER QUOTING: 
17 ---------------------------
18
19 exten => s,5,BackGround,blabla
20
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.
24
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 \\). 
29
30 These Double quotes and escapes are evaluated at the level of the
31 asterisk config file parser. 
32
33 Double quotes can also be used inside expressions, as discussed below.
34
35 ___________________________
36 VARIABLES: 
37 ---------------------------
38
39 Parameter strings can include variables. Variable names are arbitrary strings. 
40 They are stored in the respective channel structure. 
41
42 To set a variable to a particular value, do : 
43
44     exten => 1,2,SetVar(varname=value)
45
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, 
48 do: 
49
50    exten => 1,2,SetVar(koko=${blabla}${lala})
51
52
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: 
58
59         exten => 1,2,SetVar(koko=lala)
60         exten => 1,3,SetVar(${koko}=blabla)
61
62 stores to the variable "koko" the value "lala" and to variable "lala" the 
63 value "blabla". 
64
65 In fact, everything contained ${here} is just replaced with the value of 
66 the variable "here". 
67
68 _______________________________
69 REMOVING CHARACTERS FROM STRING
70 -------------------------------
71
72 The format for removing characters from a variable can be expressed as:
73
74         ${variable_name[:offset[:length]]}
75
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.
79
80         ;Remove the first character of extension, save in "number" variable
81         exten => _9X.,1,SetVar(number=${EXTEN:1})
82
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 
86 digit.
87
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.
92
93         ;Remove everything before the last four digits of the dialed string
94         exten => _9X.,1,SetVar(number=${EXTEN:-4})
95
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'
99 variable.
100
101         ;Only save the middle numbers 555 from the string 918005551234
102         exten => _9X.,1,SetVar(number=${EXTEN:5:3})
103
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
108 previous example).
109
110         ;Save the numbers 555 to the 'number' variable
111         exten => _9X.,1,SetVar(number=${EXTEN:-7:3})
112
113 If a negative length value is entered, it is ignored and Asterisk will match
114 to the end of the string.
115 ___________________________
116 EXPRESSIONS: 
117 ---------------------------
118
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 
123 evaluation. 
124 Note: The arguments and operands of the expression MUST BE separated 
125 by at least one space. 
126
127
128 For example, after the sequence: 
129
130 exten => 1,1,SetVar(lala=$[1 + 2])
131 exten => 1,2,SetVar(koko=$[2 * ${lala}])
132
133 the value of variable koko is "6".
134
135 And, further:
136
137 exten => 1,1,SetVar(lala=$[1+2]);
138
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".
143
144 and, further:
145
146 exten => 1,1,SetVar,"lala=$[  1 +    2   ]";
147
148 will parse as intended. Extra spaces are ignored.
149
150 ___________________________
151 SPACES INSIDE VARIABLE
152 ---------------------------
153 If the variable being evaluated contains spaces, there can be problems.
154
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.
158
159 As an example:
160
161 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
162
163 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
164 but the above will evaluate to:
165
166 "DELOREAN MOTORS" : "Privacy Manager"
167
168 and will evaluate to 0.
169
170 The above without double quotes would have evaluated to:
171
172 DELOREAN MOTORS : Privacy Manager
173
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.
177
178 _____________________
179 OPERATORS
180 ---------------------
181 Operators are listed below in order of increasing precedence.  Operators
182 with equal precedence are grouped within { } symbols.
183
184      expr1 | expr2
185              Return the evaluation of expr1 if it is neither an empty string
186              nor zero; otherwise, returns the evaluation of expr2.
187
188      expr1 & expr2
189              Return the evaluation of expr1 if neither expression evaluates to
190              an empty string or zero; otherwise, returns zero.
191
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
197              relation is false.
198
199      expr1 {+, -} expr2
200              Return the results of addition or subtraction of integer-valued
201              arguments.
202
203      expr1 {*, /, %} expr2
204              Return the results of multiplication, integer division, or
205              remainder of integer-valued arguments.
206
207      expr1 : expr2
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 `^'.
211
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.
218
219 Parentheses are used for grouping in the usual manner.
220
221 The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
222 produce pure parsers, which are reentrant) 
223
224 ___________________________
225 CONDITIONALS
226 ---------------------------
227
228 There is one conditional operator - the conditional goto : 
229
230         exten => 1,2,gotoif(condition?label1:label2)
231
232 If condition is true go to label1, else go to label2. Labels are interpreted
233 exactly as in the normal goto command.
234
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 
238 above, eg : 
239
240         exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)
241
242
243 Example of use : 
244
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)
249
250 ___________________________
251 PARSE ERRORS
252 ---------------------------
253
254 Syntax errors are now output with 3 lines.
255
256 If the extensions.conf file contains a line like:
257
258 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & &  "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
259
260 You may see an error in /var/log/asterisk/messages like this:
261
262 May  3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
263  "3072312154"  : "3071234567" & & "Steves Extension" : "Privacy Manager"
264  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
265                                   ^
266
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.
270
271 The second line usually shows a string of '^' chars, that show what's
272 been legally parsed so far.
273
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!
279
280
281 ___________________________
282 NULL STRINGS
283 ---------------------------
284
285 Testing to see if a string is null can be done in one of two different ways:
286
287         exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
288
289         exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
290
291
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.
294
295 The first way should work in all cases, and indeed, might now
296 be the safest way to handle this situation.
297
298 ___________________________
299 WARNING
300 ---------------------------
301
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.
308
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.
316
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 
319 ignored.
320
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
355
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 ${GROUPCOUNT}           * Result from groupcount()
363 ${MONITOR}              * Set to "TRUE" if the channel is/has been monitored (app monitor())
364 ${MONITOR_EXEC}         Application to execute after monitoring a call
365 ${MONITOR_EXEC_ARGS}    Arguments to application
366 ${MONITOR_FILENAME}     File for monitoring (recording) calls in queue
367 ${QUEUE_PRIO}           Queue priority
368 ${QUEUESTATUS}          Status of the call, one of:
369                         (TIMEOUT | FULL | JOINEMPTY | LEAVEEMPTY | JOINUNAVAIL | LEAVEUNAVAIL)
370 ${RECORDED_FILE}        * Recorded file in record()
371 ${TALK_DETECTED}        * Result from talkdetect()
372 ${TOUCH_MONITOR}        The filename base to use with Touch Monitor (auto record)
373 ${TXTCIDNAME}           * Result of application TXTCIDName
374 ${VPB_GETDTMF}          chan_vpb
375
376 The MeetMe Conference Bridge uses the following variables:
377 ----------------------------------------------------------
378 ${MEETME_RECORDINGFILE}         Name of file for recording a conference with 
379                                 the "r" option
380 ${MEETME_RECORDINGFORMAT}       Format of file to be recorded
381 ${MEETME_EXIT_CONTEXT}          Context for exit out of meetme meeting
382 ${MEETME_AGI_BACKGROUND}        AGI script for Meetme (zap only)
383 ${MEETMESECS}                   * Number of seconds a user participated in a MeetMe conference
384
385 The VoiceMail() application uses the following variables:
386 ---------------------------------------------------------
387 ${VM_CATEGORY}          Sets voicemail category
388 ${VM_NAME}              * Full name in voicemail
389 ${VM_DUR}               * Voicemail duration
390 ${VM_MSGNUM}            * Number of voicemail message in mailbox
391 ${VM_CALLERID}          * Voicemail Caller ID (Person leaving vm)
392 ${VM_CIDNAME}           * Voicemail Caller ID Name
393 ${VM_CIDNUM}            * Voicemail Caller ID Number
394 ${VM_DATE}              * Voicemail Date
395 ${VM_MESSAGEFILE}       * Path to message left by caller
396
397 The VMAuthenticate() application uses the following variables:
398 ---------------------------------------------------------
399 ${AUTH_MAILBOX} * Authenticated mailbox
400 ${AUTH_CONTEXT} * Authenticated mailbox context
401
402 DUNDiLookup() uses the following variables
403 ---------------------------------------------------------
404 ${DUNDTECH}     * The Technology of the result from a call to DUNDiLookup()
405 ${DUNDDEST}     * The Destination of the result from a call to DUNDiLookup()
406
407 The Zaptel channel sets the following variables:
408 ---------------------------------------------------------
409 ${ANI2}                 * The ANI2 Code provided by the network on the incoming call. 
410                         (ie, Code 29 identifies call as a Prison/Inmate Call)
411 ${CALLTYPE}             * Type of call (Speech, Digital, etc)
412 ${CALLEDTON}            * Type of number for incoming PRI extension
413                         i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, 
414                         4=subscriber, 6=abbreviated, 7=reserved 
415 ${CALLINGSUBADDR}       * Called PRI Subaddress
416 ${FAXEXTEN}             * The extension called before being redirected to "fax" 
417 ${PRIREDIRECTREASON}    * Reason for redirect, if a call was directed
418
419 The SIP channel sets the following variables:
420 ---------------------------------------------------------
421 ${SIPCALLID}            * SIP Call-ID: header verbatim (for logging or CDR matching)
422 ${SIPDOMAIN}            * SIP destination domain of an inbound call (if appropriate)
423 ${SIPUSERAGENT}         * SIP user agent 
424 ${SIPURI}               * SIP uri
425 ${SIP_CODEC}            Set the SIP codec for a call    
426
427 The Agent channel uses the following variables:
428 ---------------------------------------------------------
429 ${AGENTMAXLOGINTRIES}   Set the maximum number of failed logins
430 ${AGENTUPDATECDR}       Whether to update the CDR record with Agent channel data
431 ${AGENTGOODBYE}         Sound file to use for "Good Bye" when agent logs out
432 ${AGENTACKCALL}         Whether the agent should acknowledge the incoming call
433 ${AGENTAUTOLOGOFF}      Auto logging off for an agent
434 ${AGENTWRAPUPTIME}      Setting the time for wrapup between incoming calls
435 ${AGENTNUMBER}          * Agent number (username) set at login
436 ${AGENTSTATUS}          * Status of login       ( fail | on | off )
437 ${AGENTEXTEN}           * Extension for logged in agent
438
439 The Dial() application uses the following variables:
440 ---------------------------------------------------------
441 ${DIALEDPEERNAME}               * Dialed peer name
442 ${DIALEDPEERNUMBER}             * Dialed peer number
443 ${DIALEDTIME}                   * Time for the call (seconds)
444 ${ANSWEREDTIME}                 * Time from dial to answer (seconds)
445 ${DIALSTATUS}                   * Status of the call, one of:
446                                 (CHANUNAVAIL | CONGESTION | BUSY | NOANSWER | ANSWER | CANCEL)
447 ${LIMIT_PLAYAUDIO_CALLER}       Soundfile for call limits
448 ${LIMIT_PLAYAUDIO_CALLEE}       Soundfile for call limits
449 ${LIMIT_WARNING_FILE}           Soundfile for call limits
450 ${LIMIT_TIMEOUT_FILE}           Soundfile for call limits
451 ${LIMIT_CONNECT_FILE}           Soundfile for call limits
452 ${OUTBOUND_GROUP}               Default groups for peer channels (as in SetGroup)
453 * See "show application dial" for more information
454
455 The chanisavail() application sets the following variables:
456 -----------------------------------------------------------
457 ${AVAILCHAN}            * the name of the available channel if one was found    
458 ${AVAILORIGCHAN}        * the canonical channel name that was used to create the channel
459 ${AVAILSTATUS}          * Status of requested channel
460
461 When using macros in the dialplan, these variables are available
462 ---------------------------------------------------------
463 ${MACRO_EXTEN}          * The calling extensions
464 ${MACRO_CONTEXT}        * The calling context
465 ${MACRO_PRIORITY}       * The calling priority
466 ${MACRO_OFFSET}         Offset to add to priority at return from macro
467
468 If you compile with OSP support in the SIP channel, these
469 variables are used:
470 ---------------------------------------------------------
471 ${OSPHANDLE}            Handle from the OSP Library
472 ${OSPTECH}              OSP Technology from Library
473 ${OSPDEST}              OSP Destination from Library
474 ${OSPTOKEN}             OSP Token to use for call from Library
475 ${OSPRESULTS}           Number of OSP results
476
477 ____________________________________
478 CDR Variables
479 ------------------------------------
480
481 If the channel has a cdr, that cdr record has it's own set of variables which 
482 can be accessed just like channel variables. The following builtin variables
483 are available.
484
485 ${CDR(clid)}                    Caller ID
486 ${CDR(src)}                     Source 
487 ${CDR(dst)}                     Destination
488 ${CDR(dcontext)}                Destination context
489 ${CDR(channel)}                 Channel name
490 ${CDR(dstchannel)}              Destination channel
491 ${CDR(lastapp)}                 Last app executed
492 ${CDR(lastdata)}                Last app's arguments
493 ${CDR(start)}                   Time the call started.
494 ${CDR(answer)}                  Time the call was answered.
495 ${CDR(end)}                     Time the call ended.
496 ${CDR(duration)}                Duration of the call.
497 ${CDR(billsec)}                 Duration of the call once it was answered.
498 ${CDR(disposition)}             ANSWERED, NO ANSWER, BUSY
499 ${CDR(amaflags)}                DOCUMENTATION, BILL, IGNORE etc
500 ${CDR(accountcode)}             The channel's account code.
501 ${CDR(uniqueid)}                The channel's unique id.
502 ${CDR(userfield)}               The channels uses specified field.
503
504
505 In addition, you can set your own extra variables with a traditional
506 SetVAR(CDR(var)=val) to anything you want.
507
508 Certain functional variables may be accessed with $(foo <args>).  A list
509 of these functional variables may be found by typing "show functions"
510 at the Asterisk CLI.