Dialplan Programming Constructs

In Asterisk, functions or programs can be implemented either externally, through an Asterisk Gateway Interface (AGI) script (in much the same way that a Common Gateway Interface [CGI] script can add functionality to a web page) or internally, through functions and applications in the dialplan.

The dialplan is defined in the extensions.conf configuration file. The dialplan itself looks much some archic language created in 1950th and look somewhat like Fortran II program. The administrator can implement features and call flow using a simple scripting language.

Dialplan Program Structure

Each telephone number defined in the Asterisk dialplan (/etc/asterisk/extensions.conf) is really a small subroutine. In Asterisk it is called an extension. For example:

exten => 1001,1,Answer()
exten => 1001,n,Playback(hello-world)
exten => 1001,n,Hangup()

Priorities may also be numbered sequentially but this an old style:

exten => 1001,1,Answer()
exten => 1001,2,Playback(hello-world)
exten => 1001,3,Hangup()

The two subroutines above are functionally identical. If you use n, however, it makes adding and deleting entries in the extension much easier later on.

Variables assignment using Set()

Use the application Set() to create and change variables:

exten => 1002,1,Set(Favoriteanimal = "Tiger")
exten => 1002,n,Set(Favoritenumber = 23)

Use the syntax ${VARIABLENAME} to read and print variables. You can print variable values on the CLI with NoOp() (with verbosity level 3 and up):

exten => 1003,1,NoOp(${Favoriteanimal})
exten => 1003,n,NoOp(${Favoritenumber})

There are different kinds of variables:

• Global variables

  Valid anywhere in the dialplan and created or modified with Set(<variable>=<content>,g):

  exten => 1004,1,Set(READABLEANYWHERE = 23,g)
  exten => 1004,n,NoOp(${READABLEANYWHERE})

• Channel variables

  Valid only in the current channel (a channel could be a connection between two people having a phone conversation). Created or modified with Set(<variable>=<content>) (without the g):

  exten => 1005,1,Set(READABLEHEREONLY= 42)
  exten => 1005,n,NoOp(${READABLEHEREONLY})

• System variables

  These dynamic variables are set by Asterisk and may be called in the dialplan without needing to create them. A frequently used system variable is ${EXTEN}:

  exten => 1006,1,NoOp(Dialed number: ${EXTEN})

Using Expressions in Assiingments

Expressions are combinations of variables, operators, and values that you string together to produce a result. An expression can test values, alter strings, or perform mathematical calculations. Let's say we have a variable called COUNT. In plain English, two expressions using that variable might be "COUNT plus 1" and "COUNT divided by 2." Each of these expressions has a particular result or value, depending on the value of the given variable.

In Asterisk, expressions always begin with a dollar sign and an opening square bracket and end with a closing square bracket, as shown here:

$[expression]
 

Thus, we would write the above two examples like this:

$[${COUNT} + 1]
$[${COUNT} / 2] 

When Asterisk encounters an expression in a dialplan, it replaces the entire expression with the resulting value. It is important to note that this takes place after variable substitution.

exten => 321,1,Set(COUNT=3)
exten => 321,n,Set(NEWCOUNT=$[${COUNT} + 1])
exten => 321,n,SayNumber(${NEWCOUNT})

In the first priority, we assign the value of 3 to the variable named COUNT.

In the second priority, only one application—Set()—is involved, but three things actually happen:

1. Asterisk substitutes ${COUNT} with the number 3 in the expression. The expression effectively becomes this:

   exten => 321,n,Set(NEWCOUNT=$[3 + 1])

   
   

2. Asterisk evaluates the expression, adding 1 to 3, and replaces it with its computed value of 4:

   exten => 321,n,Set(NEWCOUNT=4)

   
   

3. The value 4 is assigned to the NEWCOUNT variable by the Set() application.

The third priority simply invokes the SayNumber() application, which speaks the current value of the variable ${NEWCOUNT} (set to the value 4 in priority two).

Try it out in your own dialplan.

Boolean operators

These operators evaluate the "truth" of a statement. In computing terms, that essentially refers to whether the statement is something or nothing (nonzero or zero, true or false, on or off, and so on). The Boolean operators are:

expr1 | expr2

This operator (called the "or" operator, or "pipe") returns the evaluation of expr1 if it is true (neither an empty string nor zero). Otherwise, it returns the evaluation of expr2.

expr1 & expr2

This operator (called "and") returns the evaluation of expr1 if both expressions are true (i.e., neither expression evaluates to an empty string or zero). Otherwise, it returns zero.

expr1 {=, >, >=, <, <=, !=} expr2

These operators return the results of an integer comparison if both arguments are integers; otherwise, they return the results of a string comparison. The result of each comparison is 1 if the specified relation is true, or 0 if the relation is false. (If you are doing string comparisons, they will be done in a manner that's consistent with the current local settings of your operating system.)

Mathematical operators

Want to perform a calculation? You'll want one of these:

expr1 {+, -} expr2

These operators return the results of the addition or subtraction of integer-valued arguments.

expr1 {*, /, %} expr2

These return, respectively, the results of the multiplication, integer division, or remainder of integer-valued arguments.

Regular expression operator

You can also use the regular expression operator in Asterisk:

expr1 : expr2

This operator matches expr1 against expr2, where expr2 must be a regular expression.^[] The regular expression is anchored to the beginning of the string with an implicit ^.^[]

^[] For more on regular expressions, grab a copy of the ultimate reference, Jeffrey E.F. Friedl's Mastering Regular Expressions (O'Reilly) or visit (http://www.regular-expressions.info).

^[] If you don't know what a ^ has to do with regular expressions, you simply must obtain a copy of Mastering Regular Expressions. It will change your life!

If the match succeeds and the pattern contains at least one regular expression subexpression—\( ... \)—the string corresponding to \1 is returned; otherwise, the matching operator returns the number of characters matched. If the match fails and the pattern contains a regular expression subexpression, the null string is returned; otherwise, 0 is returned.

In Asterisk version 1.0 the parser was quite simple, so it required that you put at least one space between the operator and any other values. Consequently, the following might not have worked as expected:

exten => 123,1,Set(TEST=$[2+1])

This would have assigned the variable TEST to the string "2+1", instead of the value 3. In order to remedy that, we would put spaces around the operator like so:

exten => 234,1,Set(TEST=$[2 + 1])

This is no longer necessary in Asterisk 1.2 or 1.4 as the expression parser has been made more forgiving in these types of scenarios, however, for readability's sake, we still recommend the spaces around your operators.

To concatenate text onto the beginning or end of a variable, simply place them together in an expression, like this:

exten => 234,1,Set(NEWTEST=$[blah${TEST}])

Labels and Goto()

Goto() lets you jump from one dialplan entry to another. If you are using n priorities, this can be problematic. The solution is to use labels to tag specific entries and then call the entry by label in Goto().

You can use Goto() within an extension, between extensions, or between contexts.

• You might use it within an extension:

  exten => 1007,1,Answer()
  exten => 1007,n(Start),Wait(1)
  exten => 1007,n,Playback(hello-world)
  exten => 1007,n,Goto(Start)

• Between extensions:

  exten => 1008,1,Answer()
  exten => 1008,n,Goto(1009,Ping)
  
  exten => 1009,1(Ping),Playback(hello-world)
  exten => 1009,n,Wait(2)
  exten => 1009,n,Goto(1010,Pong)
  
  exten => 1010,1(Pong),Playback(tt-weasels)
  exten => 1010,n,Wait(2)
  exten => 1010,n,Goto(1009,Ping)

• Between contexts:

  [hq]
  exten => 1011,1,Answer()
  exten => 1011,n,Playback(hello-world)
  exten => 1011,n,Goto(sales,1012,1)
  [sales]
  exten => 1012,1,Playback(hello-world)
  exten => 1012,n,Hangup()

While() Loops

Loops let you perform operations repeatedly, which is useful for reading out sequences. Use While() to run loops in the dialplan:

exten => 1013,1,Answer()
exten => 1013,n,Set(i=1)
exten => 1013,n,While($[${i} < 10])
exten => 1013,n,SayNumber(${i})
exten => 1013,n,Wait(1)
exten => 1013,n,Set(i=$[${i} + 1])
exten => 1013,n,EndWhile()
exten => 1013,n,Hangup()

GotoIf() Conditional

The key to conditional branching is the GotoIf() application. GotoIf() evaluates an expression and sends the caller to a specific destination based on whether the expression evaluates to true or false.

GotoIf() uses a special syntax, often called the conditional syntax:

GotoIf(expression?destination1:destination2)

If the expression evaluates to true, the caller is sent to destination1. If the expression evaluates to false, the caller is sent to the second destination. So, what is true and what is false? An empty string and the number 0 evaluate as false. Anything else evaluates as true.

The destinations can each be one of the following:

• A priority label within the same extension, such as weasels

• An extension and a priority label within the same context, such as 123,weasels

• A context, extension, and priority label, such as incoming,123,weasels

Either of the destinations may be omitted, but not both. If the omitted destination is to be followed, Asterisk simply goes on to the next priority in the current extension.

Let's use GotoIf() in an example:

exten => 345,1,Set(TEST=1)
exten => 345,n,GotoIf($[${TEST} = 1]?weasels:iguanas)
exten => 345,n(weasels),Playback(weasels-eaten-phonesys)
exten => 345,n,Hangup()
exten => 345,n(iguanas),Playback(office-iguanas)
exten => 345,n,Hangup()

You can jump to other parts of the dialplan, if a specific condition is met, with GotoIf():

exten => 1014,1,Answer()
exten => 1014,n,Set(Favoritestation = 0815)
exten => 1014,n,NoOp(Check to see if ${Favoritestation} is calling.)
exten => 1014,n,GotoIf($[${CALLERID(num) = ${Favoritestation}]?yes,no)

exten => 1014,n(yes),Playback(hello-world)
exten => 1014,n,Hangup()

exten => 1014,n(no),Playback(tt-monkeys)
exten => 1014,n,Hangup()

Gosub() Subroutines

With Gosub(), the call is directed to a subroutine; it can be returned to the initiating priority with Return():

exten => 1015,1,Gosub(cid-set)
exten => 1015,n,Dial(SIP/${EXTEN})

exten => 1015,n(cid-set),Set(CALLERID(all)=Widgets Inc <8005551212>)
exten => 1015,n,Return()

Recommended Links

Visual Dialplan Tutorials and Dialplan examples

Etc

Society

Groupthink : Two Party System as Polyarchy : Corruption of Regulators : Bureaucracies : Understanding Micromanagers and Control Freaks : Toxic Managers :   Harvard Mafia : Diplomatic Communication : Surviving a Bad Performance Review : Insufficient Retirement Funds as Immanent Problem of Neoliberal Regime : PseudoScience : Who Rules America : Neoliberalism  : The Iron Law of Oligarchy : Libertarian Philosophy

Quotes

War and Peace : Skeptical Finance : John Kenneth Galbraith :Talleyrand : Oscar Wilde : Otto Von Bismarck : Keynes : George Carlin : Skeptics : Propaganda  : SE quotes : Language Design and Programming Quotes : Random IT-related quotes :  Somerset Maugham : Marcus Aurelius : Kurt Vonnegut : Eric Hoffer : Winston Churchill : Napoleon Bonaparte : Ambrose Bierce :  Bernard Shaw : Mark Twain Quotes

Bulletin:

Vol 25, No.12 (December, 2013) Rational Fools vs. Efficient Crooks The efficient markets hypothesis : Political Skeptic Bulletin, 2013 : Unemployment Bulletin, 2010 :  Vol 23, No.10 (October, 2011) An observation about corporate security departments : Slightly Skeptical Euromaydan Chronicles, June 2014 : Greenspan legacy bulletin, 2008 : Vol 25, No.10 (October, 2013) Cryptolocker Trojan (Win32/Crilock.A) : Vol 25, No.08 (August, 2013) Cloud providers as intelligence collection hubs : Financial Humor Bulletin, 2010 : Inequality Bulletin, 2009 : Financial Humor Bulletin, 2008 : Copyleft Problems Bulletin, 2004 : Financial Humor Bulletin, 2011 : Energy Bulletin, 2010 : Malware Protection Bulletin, 2010 : Vol 26, No.1 (January, 2013) Object-Oriented Cult : Political Skeptic Bulletin, 2011 : Vol 23, No.11 (November, 2011) Softpanorama classification of sysadmin horror stories : Vol 25, No.05 (May, 2013) Corporate bullshit as a communication method  : Vol 25, No.06 (June, 2013) A Note on the Relationship of Brooks Law and Conway Law

History:

Fifty glorious years (1950-2000): the triumph of the US computer engineering : Donald Knuth : TAoCP and its Influence of Computer Science : Richard Stallman : Linus Torvalds  : Larry Wall  : John K. Ousterhout : CTSS : Multix OS Unix History : Unix shell history : VI editor : History of pipes concept : Solaris : MS DOS :  Programming Languages History : PL/1 : Simula 67 : C : History of GCC development :  Scripting Languages : Perl history   : OS History : Mail : DNS : SSH : CPU Instruction Sets : SPARC systems 1987-2006 : Norton Commander : Norton Utilities : Norton Ghost : Frontpage history : Malware Defense History : GNU Screen : OSS early history

Classic books:

The Peter Principle : Parkinson Law : 1984 : The Mythical Man-Month :  How to Solve It by George Polya : The Art of Computer Programming : The Elements of Programming Style : The Unix Hater’s Handbook : The Jargon file : The True Believer : Programming Pearls : The Good Soldier Svejk : The Power Elite

Most popular humor pages:

Manifest of the Softpanorama IT Slacker Society : Ten Commandments of the IT Slackers Society : Computer Humor Collection : BSD Logo Story : The Cuckoo's Egg : IT Slang : C++ Humor : ARE YOU A BBS ADDICT? : The Perl Purity Test : Object oriented programmers of all nations : Financial Humor : Financial Humor Bulletin, 2008 : Financial Humor Bulletin, 2010 : The Most Comprehensive Collection of Editor-related Humor : Programming Language Humor : Goldman Sachs related humor : Greenspan humor : C Humor : Scripting Humor : Real Programmers Humor : Web Humor : GPL-related Humor : OFM Humor : Politically Incorrect Humor : IDS Humor : "Linux Sucks" Humor : Russian Musical Humor : Best Russian Programmer Humor : Microsoft plans to buy Catholic Church : Richard Stallman Related Humor : Admin Humor : Perl-related Humor : Linus Torvalds Related humor : PseudoScience Related Humor : Networking Humor : Shell Humor : Financial Humor Bulletin, 2011 : Financial Humor Bulletin, 2012 : Financial Humor Bulletin, 2013 : Java Humor : Software Engineering Humor : Sun Solaris Related Humor : Education Humor : IBM Humor : Assembler-related Humor : VIM Humor : Computer Viruses Humor : Bright tomorrow is rescheduled to a day after tomorrow : Classic Computer Humor

The Last but not Least Technology is dominated by two types of people: those who understand what they do not manage and those who manage what they do not understand ~Archibald Putt. Ph.D

The statements, views and opinions presented on this web page are those of the author (or referenced source) and are not endorsed by, nor do they necessarily reflect, the opinions of the Softpanorama society. We do not warrant the correctness of the information provided or its fitness for any purpose. The site uses AdSense so you need to be aware of Google privacy policy. You you do not want to be tracked by Google please disable Javascript for this site. This site is perfectly usable without Javascript.

Last modified: March 12, 2019