4195f299bb77a6454454268797e6b42a0c2677b3
[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 If you want to remove the first N characters from a string, you just
73 add a colon and the number of characters, like
74
75         ;Remove the first character of extension, save in "number" variable
76         exten => _9X.,1,setvar(number=${EXTEN:1})
77
78 A second colon limits the number of characters used from the original
79 string. 
80         ;Strip five characters from the start of string, use only two 
81         ; (character 6 and 7 in the original string)
82         exten => 1000,4,setvar(skrep=${STRING:5:2})
83
84 You can also count from the end of the string by giving a negative
85 position:
86
87         ;Use the two first of the three last characters in the account code
88         exten => 4500,4,setvar(acc=${ACCOUNTCODE:-3:2})
89
90 Or 
91         ;Use the last three digits of the phone number
92         exten => 6112,4,goto(${EXTEN:-3},1)
93
94 ___________________________
95 EXPRESSIONS: 
96 ---------------------------
97
98 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is 
99 considered as an expression and it is evaluated. Evaluation works similar to 
100 (but is done on a later stage than) variable substitution: the expression 
101 (including the square brackets) is replaced by the result of the expression 
102 evaluation. 
103 Note: The arguments and operands of the expression MUST BE separated 
104 by at least one space. 
105
106
107 For example, after the sequence: 
108
109 exten => 1,1,SetVar(lala=$[1 + 2])
110 exten => 1,2,SetVar(koko=$[2 * ${lala}])
111
112 the value of variable koko is "6".
113
114 And, further:
115
116 exten => 1,1,SetVar(lala=$[1+2]);
117
118 will not work as you might have expected. Since all the chars in the single 
119 token "1+2" are not numbers, it will be evaluated as the string "1+2". Again,
120 please do not forget, that this is a very simple parsing engine, and it
121 uses a space (at least one), to separate "tokens".
122
123 and, further:
124
125 exten => 1,1,SetVar,"lala=$[  1 +    2   ]";
126
127 will parse as intended. Extra spaces are ignored.
128
129 ___________________________
130 SPACES INSIDE VARIABLE
131 ---------------------------
132 If the variable being evaluated contains spaces, there can be problems.
133
134 For these cases, double quotes around text that may contain spaces
135 will force the surrounded text to be evaluated as a single token.
136 The double quotes will be counted as part of that lexical token.
137
138 As an example:
139
140 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
141
142 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
143 but the above will evaluate to:
144
145 "DELOREAN MOTORS" : "Privacy Manager"
146
147 and will evaluate to 0.
148
149 The above without double quotes would have evaluated to:
150
151 DELOREAN MOTORS : Privacy Manager
152
153 and will result in syntax errors, because token DELOREAN is immediately
154 followed by token MOTORS and the expression parser will not know how to 
155 evaluate this expression.
156
157 _____________________
158 OPERATORS
159 ---------------------
160 Operators are listed below in order of increasing precedence.  Operators
161 with equal precedence are grouped within { } symbols.
162
163      expr1 | expr2
164              Return the evaluation of expr1 if it is neither an empty string
165              nor zero; otherwise, returns the evaluation of expr2.
166
167      expr1 & expr2
168              Return the evaluation of expr1 if neither expression evaluates to
169              an empty string or zero; otherwise, returns zero.
170
171      expr1 {=, >, >=, <, <=, !=} expr2
172              Return the results of integer comparison if both arguments are
173              integers; otherwise, returns the results of string comparison
174              using the locale-specific collation sequence.  The result of each
175              comparison is 1 if the specified relation is true, or 0 if the
176              relation is false.
177
178      expr1 {+, -} expr2
179              Return the results of addition or subtraction of integer-valued
180              arguments.
181
182      expr1 {*, /, %} expr2
183              Return the results of multiplication, integer division, or
184              remainder of integer-valued arguments.
185
186      expr1 : expr2
187              The `:' operator matches expr1 against expr2, which must be a
188              regular expression.  The regular expression is anchored to the
189              beginning of  the string with an implicit `^'.
190
191              If the match succeeds and the pattern contains at least one regu-
192              lar expression subexpression `\(...\)', the string correspond-
193              ing to `\1' is returned; otherwise the matching operator
194              returns the number of characters matched.  If the match fails and
195              the pattern contains a regular expression subexpression the null
196              string is returned; otherwise 0.
197
198 Parentheses are used for grouping in the usual manner.
199
200 The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
201 produce pure parsers, which are reentrant) 
202
203 ___________________________
204 CONDITIONALS
205 ---------------------------
206
207 There is one conditional operator - the conditional goto : 
208
209         exten => 1,2,gotoif(condition?label1:label2)
210
211 If condition is true go to label1, else go to label2. Labels are interpreted
212 exactly as in the normal goto command.
213
214 "condition" is just a string. If the string is empty or "0", the condition
215 is considered to be false, if it's anything else, the condition is true. 
216 This is designed to be used together with the expression syntax described 
217 above, eg : 
218
219         exten => 1,2,gotoif($[${CALLERID} = 123456]?2|1:3|1)
220
221
222 Example of use : 
223
224 exten => s,2,SetVar(vara=1)
225 exten => s,3,SetVar(varb=$[${vara} + 2])
226 exten => s,4,SetVar(varc=$[${varb} * 2])
227 exten => s,5,GotoIf($[${varc} = 6]?99|1:s|6)
228
229 ___________________________
230 PARSE ERRORS
231 ---------------------------
232
233 Syntax errors are now output with 3 lines.
234
235 If the extensions.conf file contains a line like:
236
237 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & &  "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
238
239 You may see an error in /var/log/asterisk/messages like this:
240
241 May  3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
242  "3072312154"  : "3071234567" & & "Steves Extension" : "Privacy Manager"
243  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
244                                   ^
245
246 The first line shows the string passed to the expression parser. This
247 string is the result of the variable replacements, etc. This way, you
248 can see the actual string that went into the parser.
249
250 The second line usually shows a string of '^' chars, that show what's
251 been legally parsed so far.
252
253 And the third line shows where the parser was (lookahead token lexing,
254 etc), when the parse hit the rocks. A single '^' here. The error is
255 going to be somewhere between the last '^' on the second line, and the
256 '^' on the third line. That's right, in the example above, there are two
257 '&' chars, separated by a space, and this is a definite no-no!
258
259
260 ___________________________
261 NULL STRINGS
262 ---------------------------
263
264 Testing to see if a string is null can be done in one of two different ways:
265
266         exten => _XX.,1,GotoIf($["${calledid}" != ""]?3) 
267
268         exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3) 
269
270
271 The second example above is the way suggested by the WIKI. It will 
272 work as long as there are no spaces in the evaluated value.
273
274 The first way should work in all cases, and indeed, might now
275 be the safest way to handle this situation.
276
277 ___________________________
278 WARNING
279 ---------------------------
280
281 If you need to do complicated things with strings, asterisk expressions
282 is most likely NOT the best way to go about it. AGI scripts are an
283 excellent option to this need, and make available the full power of
284 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
285 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
286 Pascal, APL, assembler, etc.
287
288 ---------------------------------------------------------
289 Asterisk standard channel variables 
290 ---------------------------------------------------------
291 There are a number of variables that are defined or read
292 by Asterisk. Here is a list of them. More information is
293 available in each application's help text. All these variables
294 are in UPPER CASE only.
295
296 Variables marked with a * are builtin functions and can't be set,
297 only read in the dialplan.  Writes to such variables are silently 
298 ignored.
299
300 ${ACCOUNTCODE}   * Account code (if specified)
301 ${BLINDTRANSFER} The name of the channel on the other side a blind transfer
302 ${BRIDGEPEER}    Bridged peer
303 ${CALLERANI}     * Caller ANI (PRI channels)
304 ${CALLERID}      * Caller ID
305 ${CALLERIDNAME}  * Caller ID Name only
306 ${CALLERIDNUM}   * Caller ID Number only
307 ${CALLINGANI2}   * Caller ANI2 (PRI channels)
308 ${CALLINGPRES}   * Caller ID presentation for incoming calls (PRI channels)
309 ${CALLINGTNS}    * Transit Network Selector (PRI channels)
310 ${CALLINGTON}    * Caller Type of Number (PRI channels)
311 ${CHANNEL}       * Current channel name
312 ${CONTEXT}       * Current context
313 ${DATETIME}      * Current date time in the format: YYYY-MM-DD_HH:MM:SS
314 ${DNID}          * Dialed Number Identifier
315 ${EPOCH}         * Current unix style epoch
316 ${EXTEN}         * Current extension
317 ${ENV(VAR)}      * Environmental variable VAR
318 ${HANGUPCAUSE}   * Asterisk cause of hangup (inbound/outbound)
319 ${HINT}          * Channel hints for this extension
320 ${HINTNAME}      * Suggested Caller*ID name for this extension
321 ${INVALID_EXTEN} The invalid called extension (used in the "i" extension)
322 ${LANGUAGE}      * Current language
323 ${LEN(VAR)}      * String length of VAR (integer)
324 ${PRIORITY}      * Current priority in the dialplan
325 ${PRIREDIRECTREASON} Reason for redirect on PRI, if a call was directed
326 ${RDNIS}         * Redirected Dial Number ID Service
327 ${TIMESTAMP}     * Current date time in the format: YYYYMMDD-HHMMSS
328 ${TRANSFER_CONTEXT} Context for transferred calls
329 ${UNIQUEID}      * Current call unique identifier
330
331 Various application variables
332 -----------------------------
333 ${CURL}         Resulting page content for curl()
334 ${ENUM}         Result of application EnumLookup
335 ${EXITCONTEXT}  Context to exit to in IVR menu (app background())
336                 or in the RetryDial() application
337 ${GROUPCOUNT}   Result from groupcount()
338 ${MONITOR}      Set to "TRUE" if the channel is/has been monitored (app monitor())
339 ${MONITOR_EXEC} Application to execute after monitoring a call
340 ${MONITOR_EXEC_ARGS}    Arguments to application
341 ${MONITOR_FILENAME} File for monitoring (recording) calls in queue
342 ${QUEUE_PRIO}   Queue priority
343 ${RECORDED_FILE} Recorded file in record()
344 ${TALK_DETECED} Result from talkdetect()
345 ${TOUCH_MONITOR} The filename base to use with Touch Monitor (auto record)
346 ${TXTCIDNAME}   Result of application TXTCIDName
347 ${VPB_GETDTMF}  chan_vpb
348
349 The MeetMe Conference Bridge uses the following variables:
350 ----------------------------------------------------------
351 ${MEETME_RECORDINGFILE} Name of file for recording a conference with 
352                 the "r" option
353 ${MEETME_RECORDINGFORMAT} Format of file to be recorded
354 ${MEETME_EXIT_CONTEXT}  Context for exit out of meetme meeting
355 ${MEETME_AGI_BACKGROUND} AGI script for Meetme (zap only)
356
357 Meetme() sets the following variable:
358 ${MEETMESECS}   Number of seconds a user participated in a MeetMe conference
359
360 The voicemail() application uses the following variables:
361 ---------------------------------------------------------
362 ${VM_CATEGORY}  Sets voicemail category
363
364 The following variables are set by voicemail()
365 ${VM_NAME}      Full name in voicemail
366 ${VM_DUR}       Voicemail duration
367 ${VM_MSGNUM}    Number of voicemail message in mailbox
368 ${VM_CALLERID}  Voicemail Caller ID (Person leaving vm)
369 ${VM_CIDNAME}   Voicemail Caller ID Name
370 ${VM_CIDNUM}    Voicemail Caller ID Number
371 ${VM_DATE}      Voicemail Date
372
373 The following variables are set by vmauthenticate()
374 ${AUTH_MAILBOX} Authenticated mailbox
375 ${AUTH_CONTEXT} Authenticated mailbox context
376 ${DIFF_DAY}     Day difference (internal use)
377
378 Dundi() uses the following variables
379 ---------------------------------------------------------
380 ${DUNDTECH}     Technology
381 ${DUNDDEST}     Destination
382
383 The Zaptel channel sets the following variables:
384 ---------------------------------------------------------
385 ${ANI2}                 The ANI2 Code provided by the network on the incoming call. 
386                         (ie, Code 29 identifies call as a Prison/Inmate Call)
387 ${CALLTYPE}             Type of call (Speech, Digital, etc)
388 ${CALLEDTON}            Type of number for incoming PRI extension
389                         i.e. 0=unknown, 1=international, 2=domestic, 3=net_specific, 
390                         4=subscriber, 6=abbreviated, 7=reserved 
391 ${CALLINGSUBADDR}       Called PRI Subaddress
392 ${FAXEXTEN}             The extension called before being redirected to "fax"   
393 ${PRIREDIRECTREASON}    Reason for redirect, if a call was directed
394
395 The SIP channel sets the following variables:
396 ---------------------------------------------------------
397 ${SIPCALLID}            SIP Call-ID: header verbatim (for logging or CDR matching)
398 ${SIPDOMAIN}            SIP destination domain of an inbound call (if appropriate)
399 ${SIPUSERAGENT}         SIP user agent 
400 ${SIPURI}               SIP uri
401
402 The SIP channel reads the following variable:
403 ${SIP_CODEC}            Set the SIP codec for a call    
404
405 The Agent channel uses the following variables:
406 ---------------------------------------------------------
407 ${AGENTMAXLOGINTRIES}   Set the maximum number of failed logins
408 ${AGENTUPDATECDR}       Whether to update the CDR record with Agent channel data
409 ${AGENTGOODBYE}         Sound file to use for "Good Bye" when agent logs out
410 ${AGENTACKCALL}         Whether the agent should acknowledge the incoming call
411 ${AGENTAUTOLOGOFF}      Auto logging off for an agent
412 ${AGENTWRAPUPTIME}      Setting the time for wrapup between incoming calls
413 ${AGENTNUMBER}          Agent number (username) set at login
414 ${AGENTSTATUS}          Status of login ( fail | on | off )
415 ${AGENTEXTEN}           Extension for logged in agent
416
417 The Dial() application sets the following variables:
418 ---------------------------------------------------------
419 ${DIALEDPEERNAME} Dialed peer name
420 ${DIALEDPEERNUMBER} Dialed peer number
421 ${DIALEDTIME}   Time for the call (seconds)
422 ${ANSWEREDTIME} Time from dial to answer (seconds)
423 ${DIALSTATUS}   Status of the call, one of:
424                 CHANUNAVAIL | CONGESTION | BUSY | NOANSWER | ANSWER | CANCEL
425
426 The dial() application reads the following variables
427 ${LIMIT_PLAYAUDIO_CALLER}       Soundfile for call limits
428 ${LIMIT_PLAYAUDIO_CALLEE}       Soundfile for call limits
429 ${LIMIT_WARNING_FILE}           Soundfile for call limits
430 ${LIMIT_TIMEOUT_FILE}           Soundfile for call limits
431 ${LIMIT_CONNECT_FILE}           Soundfile for call limits
432 ${OUTBOUND_GROUP}       Default groups for peer channels (as in SetGroup)
433 * See "show application dial" for more information
434
435
436
437 The chanisavail() application sets the following variables:
438 -----------------------------------------------------------
439 ${AVAILCHAN}            return value
440 ${AVAILORIGCHAN}        return value
441 ${AVAILSTATUS}          Status of requested channel
442
443 When using macros in the dialplan, these variables are available
444 ---------------------------------------------------------
445 ${MACRO_EXTEN}          The calling extensions
446 ${MACRO_CONTEXT}        The calling context
447 ${MACRO_PRIORITY}       The calling priority
448 ${MACRO_OFFSET}         Offset to add to priority at return from macro
449
450 If you compile with OSP support in the SIP channel, these
451 variables are used:
452 ---------------------------------------------------------
453 ${OSPHANDLE}            Handle from the OSP Library
454 ${OSPTECH}              OSP Technology from Library
455 ${OSPDEST}              OSP Destination from Library
456 ${OSPTOKEN}             OSP Token to use for call from Library
457 ${OSPRESULTS}           Number of OSP results
458
459 ____________________________________
460 CDR Variables
461 ------------------------------------
462
463 If the channel has a cdr, that cdr record has it's own set of variables which 
464 can be accessed just like channel variables. The following builtin variables
465 are available.
466
467 ${CDR(clid)}                    Caller ID
468 ${CDR(src)}                     Source 
469 ${CDR(dst)}                     Destination
470 ${CDR(dcontext)}                Destination context
471 ${CDR(channel)}                 Channel name
472 ${CDR(dstchannel)}              Destination channel
473 ${CDR(lastapp)}                 Last app executed
474 ${CDR(lastdata)}                Last app's arguments
475 ${CDR(start)}                   Time the call started.
476 ${CDR(answer)}                  Time the call was answered.
477 ${CDR(end)}                     Time the call ended.
478 ${CDR(duration)}                Duration of the call.
479 ${CDR(billsec)}                 Duration of the call once it was answered.
480 ${CDR(disposition)}             ANSWERED, NO ANSWER, BUSY
481 ${CDR(amaflags)}                DOCUMENTATION, BILL, IGNORE etc
482 ${CDR(accountcode)}             The channel's account code.
483 ${CDR(uniqueid)}                The channel's unique id.
484 ${CDR(userfield)}               The channels uses specified field.
485
486
487 In addition, you can set your own extra variables with a traditional
488 SetVAR(CDR(var)=val) to anything you want.