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 ${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
 374
 375 The MeetMe Conference Bridge uses the following variables:
 376 ----------------------------------------------------------
 377 ${MEETME_RECORDINGFILE}         Name of file for recording a conference with
 378                                 the "r" option
 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
 383
 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
 395
 396 The VMAuthenticate() application uses the following variables:
 397 ---------------------------------------------------------
 398 ${AUTH_MAILBOX} * Authenticated mailbox
 399 ${AUTH_CONTEXT} * Authenticated mailbox context
 400
 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()
 405
 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
 417
 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
 423 ${SIPURI}               * SIP uri
 424 ${SIP_CODEC}            Set the SIP codec for a call
 425
 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
 437
 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
 453
 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
 459
 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
 466
 467 If you compile with OSP support in the SIP channel, these
 468 variables are used:
 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
 475
 476 ____________________________________
 477 CDR Variables
 478 ------------------------------------
 479
 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
 482 are available.
 483
 484 ${CDR(clid)}                    Caller ID
 485 ${CDR(src)}                     Source
 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.
 502
 503
 504 In addition, you can set your own extra variables with a traditional
 505 SetVAR(CDR(var)=val) to anything you want.
 506
 507 Certain functional variables may be accessed with $(foo <args>).  A list
 508 of these functional variables may be found by typing "show functions"
 509 at the Asterisk CLI.