Introduction To Dial Plan
Actual Asterisk Call Switching is performed by Dial Plan
Two Important files make up Dial Plan
extensions.conf
Based on priority model
extensions.ael
Based on asterisk extension language
The dial plan consists of four main parts: contexts, extensions, priorities, and
applications.
extensions.conf layout
Contents of extensions.conf is organized in three sections



general
global
contents
general and global are setting sections
executable dial plan components are defined in contexts
`
[general] Section
Here we define few general options regarding dial plan
static
it indicates if a 'save dial plan' command from console is possiable. It
works with write protect. If set to no or omitted, pbx_config will rewrite
this file and all comments made in the file will be lost.
writeprotect
if static is yes and write protect=no the you can save dial plan by CLI
command 'save dial plan'.
autofallthrough
If autofallthrough is set, then if an extension runs out of things to do, it
will terminate the call with BUSY, CONGESTION or HANGUP
depending on Asterisk's best guess (strongly recommended).
If autofallthrough is not set, then if an extension runs out of
things to do, asterisk will wait for a new extension to be dialed
[general] Section
clearglobalvars
If clearglobalvars is set, global variables will be cleared and reparsed on
an extensions reload, or Asterisk reload. If clearglobalvars is not set,
then global variables will persist through reloads, and even if deleted
from the extensions.conf or one if its included files, will remain set to the
previous value."
global variables will be discussed in details later
Priorityjumping
If priorityjumping is set to 'yes', then applications that support 'jumping' to
a different priority based on the result of their operations will do so
Individual applications can also be requested to do this by passing a 'j'
option in their arguments.
[general] Section
#include "filename.conf"
Include other config files with the include command.
[global] Section
Dial plan global variables and their initial values are defined in this section.
Global variables are normally used as constants.
They are defined here so that they might be changed easily in the future.
Global variables will be discussed in detail later
[contexts] in extensions.conf
The Dial plan consists of a collection of contexts. Each context consists of a
collection of extensions which perform actual call routing.
Contexts will be discussed later.
extensions
An extension consists of the following parts:



Extension (Name or number)
Priority (a kind of program line number)
Application - an instruction which tells Asterisk what it should do with the
call
The syntax is:
exten => extension , priority, Command(parameters)
extensions
Extensions are of three types



Literal
Pattern
Predefined
Literal
Literal extensions can contain numbers (0-9), letters A,B,C,D (some hard
phones have these letters) or all letters (a-z)
An example
exten => arif,1,Dial(SIP/arif)
Pattern
If an extension’s name starts with '_', it is considered as pattern
for pattern some characters have special meaning.
X
any digit from 0-9
Z
any digit from 1-9
N
any digit from 2-9
[12679]
any digit in the bracket for example 1,2,6,7,or 9
. (dot)
wildcard, matches everything remaining.
[1-8]
any digit in the range 1 to 8
Testing a Pattern
Using CLI command 'dialplan show'
we can test pattern.
Example:
extensions.conf
*CLI> dialplan show
[ Context 'default' created by 'pbx_config'[
Context 'my-phones' created by 'pbx_config' ]
'23' =>
1. Answer()
[pbx_config]
2. Playback(hello-world)
[pbx_config]
3. Hangup()
[pbx_config]
[ Context 'parkedcalls' created by 'res_features']
[my-phones]
exten => 23,1,Answer()
exten => 23,2,Playback(hello-world)
exten => 23,3,Hangup()
'700' =>
1. Park()
[res_features]
-= 2 extensions (4 priorities) in 3 contexts. =
*CLI>
Testing a Pattern
dialplan show my-phones
dialplan show 23@my-phone
dialplan show 25@my-phones
Now change pattern to _2X
[my-phones]
exten => _2X,1,Answer()
exten => _2X,2,Playback(hello-world)
exten => _2X,3,Hangup()
Testing a Pattern
Test with the following CLI commands.
dialplan show 23@my-phone
dialplan show 25@my-phone
dialplan show 246@my-phones
now change pattern to _2X.
[my-phones]
exten => _2X.,1,Answer()
exten => _2X.,2,Playback(hello-world)
exten => _2X.,3,Hangup()
Testing a Pattern
Test with following CLI commands.
dialplan show 23@my-phones
dialplan show 25@my-phones
dialplan show 246@my-phones
Pattern matching order
Asterisk prioritizes patterns based on the quality of the match.
If two extensions match a dialed number, Asterisk will always chose the
better match. Before deciding which extension matches best, it processes
the entire context.
Example:
[sales]
exten => _12X.,1,NoOp(12X)
exten => 12345,1,NoOp(12345)
exten => _1234.,1,NoOp(1234.)
Pattern matching
Testing
dial plan show 12345@sales
dial plan show 12346@sales
Pattern “_.” in Asterisk 1.2
Digium has changed the behaviour of “_.” as it was in Asterisk 1.2. it should
have lowest priority but in Asterisk 1.2 its behaviour is opposite to the
expected behaviour
Pattern matching
Example
[sales]
exten => _12X.,1,NoOp(12X)
exten => 12345,1,NoOp(12345)
exten => _1234.,1,NoOp(1234.)
exten => _.,1,NoOp(testing _.)
Testing:
dialplan show 12345@sales
In Asterisk 1.2:
show dialplan 12346@sales
Predefined
There are several predefined extension names:
- i - Invalid
- s - Start
- h - Hangup
- t - Timeout
- T - AbsoluteTimeout
- o – Operator
we ll discuss them later with examples
priorities
Priority is the order in which commands are run. First the one with priority 1,
then with 2, .
Asterisk does not consider the order in which you put the lines in the
extensions.conf file. You can mix the lines into a different order, like the
following example, and it will make no difference because Asterisk uses the
priority of each line to determine the order of execution:

[test]
exten => 555,4,Hangup
exten => 555,1,Answer
exten => 555,3,Voicemail(44)
exten => 555,2,Playback(tt-weasels)
n priority
n priority automatically increases a priority's value
using n priority its easy to insert new command without disturbing the
original priorities
Labels can be set using n priority, so that it can be targeted with goto
exten => s,n(start),Answer
Arbitrary increments can be defined
exten => s,n+2,Dial(SIP/101)
Applications
Answer([delay])
Answer the ringing channel. If delay is specified then asterisk will wait for the
specified number of milliseconds before answering the channel.
Hangup
Hangs up the channel
BackGround()
Plays a file while waiting for the user to begin entering an extension
PlayBack(filename)
Plays a given filename
Applications(cont.)
SayDitits()
Says the specified digits using the current language setting for the channel
Busy()
Request that the channel indicate the busy condition
Set(n=value)
Sets variable n to the specified value
Wait(seconds)
Wait for the specified number of seconds, then return 0.
WaitExten()
Waits for the user to enter a new extension for the specified amount of time
then return 0
Applications(cont.)
Goto([[context,]extension,]priority)
Sends control of the current channel to
; same as above, but using a named
the specified priority, optionally setting
priority
the destination’s extension and context
exten => 124,1,Answer( )
exten => 123,1,Answer( )
exten => 124,2,Set(COUNT=1)
exten => 123,2,Set(COUNT=1)
exten =>
exten => 23,3,SayNumber(${COUNT})
124,3(repeat),SayNumber(${COUNT})
exten =>
exten =>
123,4,Set(COUNT=$[${COUNT} + 1 ])
exten => 123,5,Goto(3)
124,4,Set(COUNT=$[${COUNT} + 1 ])
exten => 124,5,Goto(repeat)
Applications(cont.)
GotoIf(condition?label1:label2)
Sends the call to label1 if the
condition is true, or to label2 if the
; same thing as above, but this time we'll specify an
extension and a priority for each label
exten => 124,1,GotoIf($[ ${TEST} =
101]?123,10:123,20)
condition is false.
Either label1 or label2 may be
omitted but not both.
[globals]
TEST=101
[incoming]
; go to priority 10 if ${TEST} is 101, otherwise go
to priority 20
exten => 123,1,GotoIf($[ ${TEST} = 101 ]?10:20)
exten => 123,10,Playback(the-monkeys-twice)
exten => 123,20,Playback(tt-somethingwrong)
; same thing as above, but these labels have a context,
extension, and priority
exten => 125,1,GotoIf($[ ${TEST} = 101
]?incoming,123,10:incoming,123,20)
Applications(cont.)
GotoIfTime(times,days_of_week,days_of_month,months?label)
jumps to the specified label if current time matched with the specified time
; If we're open, then go to the open context
; We're open from 9am to 6pm Monday through Friday
exten => s,1,GotoIfTime(09:00-17:59,mon-fri,*,*?open,s,1)
; We're also open from 9am to noon on Saturday
exten => s,2,GotoIfTime(09:00-11:59,sat,*,*?open,s,1)
; Otherwise, we're closed
exten => s,3,Goto(closed,s,1)
Context
Context is a collection of extensions
Context can be used to implement some important features
Routing:
Route call based on extension
Autoattendent: Greet callers and ask them to enter extensions
MultilevelMenus: Menus for sales, Support etc
Authentication: Ask for passwords for certain extensions
Day/Night: Vary behavior after hours
Example
[contex]
exten => some_exten,priority,application(arg1,arg2...)
exten => some_exten,priority,application(arg1,arg2...)
Context Example
[local1]
exten => _NX.,1,NoOp(Local call)
[countrywide]
include => local1
exten => _0N.,1,NoOp(Country Wide Call)
[international1]
include => local1
include => countrywide
exten => _00Z.,1,NoOp(International Call)
Variables
Variable is a placeholder for a value
Variables are referenced in dial plan as
${foo} ;foo is a variable name
Variables are of three types

Global variables

Channel variables

Environment variables
Types of Variables
Global variables
Global variables apply to all extensions in all contexts
should be defined in global context
they can also be defined using SetGlobalVar() application
Channel Variables
Channel variables is associated only to a particual call
Channel variables are defined only for the duration of call
Channel variables are set via the set() application
Environment Variable
Environment variables are a way of accessing UNIX environment variables
these are referenced as ${ENV(var)} where var is UNIX environment
Variable Example
[FooTest]
exten =>
100,1,SetGlobalVar(FOO=5)
exten => 100,2,NoOp(${FOO})
exten => 100,3,NoOp(${foo})
exten => 100,4,SetVar(foo=8)
exten => 100,5,NoOp(${FOO})
exten => 100,6,NoOp(${foo})
Executing SetGlobalVar("Zap/1-1", "FOO=5") in
new stack
― Setting global variable 'FOO' to '5'
― Executing NoOp("Zap/1-1", "5") in new
stack
― Executing NoOp("Zap/1-1", "5") in new
stack
― Executing SetVar("Zap/1-1", "foo=8") in
new stack
― Executing NoOp("Zap/1-1", "8") in new
stack
― Executing NoOp("Zap/1-1", "8") in new
stack
Inheritance of Channel
Variables
A variable name preceded by '_' character will cause that variable to be
inherited by channels created by the main channel
A variable preceded by a single '_' character will be inherited only once
A variable preceded by two '_' characters that is '__' will be inherited
indefinitely
Inheritance of Channel
Variables
[variable-inheritance-test]
exten => 104,1,Set(FEE=fee)
exten => 104,2,Set(_FIE=fie)
exten => 104,3,Set(__FUM=fum)
exten => 104,4,Dial(Local/105@test1)
[test1]
exten => 105,1,NoOp(${FEE})
exten => 105,2,NoOp(${FIE})
exten => 105,3,NoOp(${FUM})
exten => 105,4,Dial(Local/106@test2)
[test2]
exten => 106,1,NoOp(${FEE})
exten => 106,2,NoOp(${FIE})
exten => 106,3,NoOp(${FUM})
exten => 106,4,hangup
Some Predefined Channel Variables
${CHANNEL}
current channel name
${EXTEN}
current extension
${PRIORITY}
current priority
${CONTEXT}
current context
${EPOCH}
current UNIX style epoch (no. of seconds since 1 jan
1970)
${DIALSTATUS}
status of call
${DIALTIME}
time since number was dialed
${ANSWEREDTIME}
actual amount of time in seconds
${DATETIME}
current date time(DDMMYY-HH:MM:SS) deprecated
in Asterisk 1.2, instead use STRFTIME
${TIMESTAMP}
current date and time (YYYYMMDD-HHMMSS)
deprecated in Asterisk 1.4, , instead use STRFTIME
${CALLERID(num)}
current caller ID number
Macros
A macro is a kind of subroutine
A macro is used to avoid repitation in dialplan
A macro is an extension context preceded by “macro-” for example [macro-
voicemail]
commands are same as in context but with a few exceptions
Only s extension is allowed in macros
The original ${EXTEN} and ${CONTEXT} cannot be used.
${MACRO_EXTEN} and ${MACRO_CONTEXT} variables are used instead.
A macro is called with macro() application in an extension. Syntax is
Macro(macroname,arg1,arg2...)
[localcalls]
exten => _NX.,1,Macro(test,${EXTEN})
[nationwide]
include => localcalls
exten => _0N.,1,Macro(test,${EXTEN})
[intercalls]
include => localcalls
include => nationwide
exten => _00Z.,1,Macro(test,${EXTEN}
[macro-test]
exten => s,1,GoToIf($["${MACRO_CONTEXT}":"localcalls"] ?local)
exten => s,n,GoToIf($["${MACRO_CONTEXT}":"nationwide]" ?nation)
exten => s,n,NoOp(interntional call)
exten => s,n,hangup()
exten => s,n(local),NoOp(local calls)
exten => s,n,hangup()
exten => s,n(nation),NoOp(nation wide call)
exten => s,n,hangup()
Include
For simplifying and organising larger dial plans.
With include, we use other contexts in current context
The following is syntax of include statement
include => context
;where context is name of contex
first asterisk will look in the current context for match. If finds no match, then
asterisk looks in first included context then second and so on.
Include statement can be made conditional to the time of the day. This make
it easier to implement different day and night behaviors.
Example
[time-based]
include => open|09:00-17:00|mon-fri|*|*
include => open|09:00-14:00|sat|*|*
include => closed
[open]
exten => _X.,1,NoOp(Ofice Open)
[closed]
exten => _X.,1,NoOp(Office Closed)
Dial Command
Dial command sends call on one or more channels
if priorityjumping=yes, the the dial plan jumps to priority+101 on busy,
congested and on channel unavailable.
Syntax is
Dial(type1/identifier [&type2/identifier2 [&type3/identifier3...]],timeout,options,URL
type specifies channel type such as ZAP, SIP, IAX2 and so on
identifier specifies “phone number” to dial on that channel
specify more than one channel for dial command using & sign.
Timeout optional parameter, defines timeout
Dial Command
Options
t: allow called user to transfer call
T: allow the calling user to transfer
r: generate ringing tone
m: provide music on hold to calling party until called channel answers
h: allow the called person to hangup by dialing *
H: allow the caller to hangup by dialing *
o: send the caller's ID
j: Asterisk v.1.2 jump to priority n+101 if all of the requested channels are
busy
M(x): executes the macro(x) once call connects
Dial Command
g: when the called party hangs up, exit to execute more commands in the
current context
G(context^exten^pri) if call is answered, transfer both parties to the
specified context and extension
S(n):
hang up the call after n seconds of answer call
Return Codes of Dial Command
Dial sets DIALSTATUS to indicate its success or failure
DIALSTATUS contains the following text string
ANSWER
a sucessful dial
BUSY
the number is busy
NOANSWER
the number rang but no one answer the call
CANCEL
dial command reached the number but the caller
handup before the called person picked up
CONGESTION
congestion usually means number is not recognized
CHANUNAVAIL
channel unavailable
Example
[dialstatus-test]
exten => 200,1,Dial(SIP/802,5,g)
exten => 200,n,NoOp(Dialstatus:${DIALSTATUS})
exten => 201,1,Dial(SIP/801,5,g)
exten => 201,n,NoOp(Dialstatus:${DIALSTATUS})
Special Extensions
Some additional system defined extensions are:
h: hangup, this extension is called when a caller hangs up the phone.
When this extension is called channel related variables get destroyed
Example:
[exten-h-testing]
include => from-internal1
exten => 200,1,GoTo(from-internal1,s,1)
[from-internal1]
exten => s,1,Set(CONNECTIONS=$[${CONNECTIONS}+1]|g)
exten => s,2,NoOp(${CONNECTIONS})
exten => s,3,wait(210)
exten => h,1,Set(CONNECTIONS=$[${CONNECTIONS}-1])
Special Extensions
i: I extension is executed when a caller enters an invalid extension. I
extension only works with background(). Channel variables get
destroyed when I is called
O and a extension
Call will be directed to operater if caller presses 0 and if operater=yes in
voicemail.conf
•
Will direct call to a extension (abort)
Special Extensions
T and t extension
t
If there is no input in an IVR menu within a certain timeframe, the t
extension is called
T
The T extension is called after the absolute timeout has been exceeded.
You can set this timeout value with
Set(TIMEOUT(absolute)=<seconds>)
Special Extensions
The timer starts whenever the timeout value is set (it does not automatically
start with the connection, it must be started explicitly with the Set()
command).
Example:
exten => 20,1,Answer()
exten => 20,2,Set(TIMEOUT(absolute)=120)
exten => 20,3,Playback(hello-world)
exten => 20,4,Wait(1)
exten => 20,5,Goto(3)
exten => T,1,Wait(1)
exten => T,2,Playback(thank-you-for-calling)
exten => T,3,Wait(1)
exten => T,4,Hangup()
Special Extensions
s extension
For any scenario in which we cannot determine the number dialed, use the
s extension.
exten => s,1,Answer()
exten => s,2,Wait(1)
exten => s,3,Play(tt-monkeys)
exten => s,4,Wait(1)
exten => s,5,Hangup()
Expressions
Expressions are combinations of variables, operators, and values that you
put together to get a result
In Asterisk, expressions always begin with a dollar sign and an opening
square bracket and end with a closing square bracket, as shown below:
$[expression]
When Asterisk encounters an expression in a dial plan, it replaces the entire
expression with the resulting value.
Example
exten => 321,1,Set(COUNT=3)
exten => 321,2,Set(NEWCOUNT=$[${COUNT} + 1])
exten => 321,3,SayNumber(${NEWCOUNT})
Expressions
Operators
types of operators that are available in Asterisk
Boolean operators
These operators evaluate the "truth" of a statement
The Boolean operators are:
expr1 | expr2
expr1 & expr2
expr1 {=, >, >=, <, <=, !=} expr2