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

[my-phones]

exten => 23,1,Answer()

exten => 23,2,Playback(hello-world)

exten => 23,3,Hangup()

*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']

'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 the

specified priority, optionally setting the

destination’s extension and context

exten => 123,1,Answer( )

exten => 123,2,Set(COUNT=1)

exten => 23,3,SayNumber(${COUNT})

exten => 123,4,Set(COUNT=$[$

{COUNT} + 1 ])

exten => 123,5,Goto(3)

; same as above, but using a named priority

exten => 124,1,Answer( )

exten => 124,2,Set(COUNT=1)

exten => 124,3(repeat),SayNumber($

{COUNT})

exten => 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 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 this time we'll specify an

extension and a priority for each label

exten => 124,1,GotoIf($[ ${TEST} = 101]?123,10:123,20)

; 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 => local1exten => _0N.,1,NoOp(Country Wide Call)

[international1]include => local1include => countrywideexten => _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.

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

VariablesA 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 => localcallsexten => _0N.,1,Macro(test,${EXTEN})

[intercalls]include => localcallsinclude => nationwideexten => _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-internal1exten => 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})

ExpressionsOperators types of operators that are available in Asterisk Boolean operators These operators evaluate the "truth" of a statementThe Boolean operators are: expr1 | expr2expr1 & expr2expr1 {=, >, >=, <, <=, !=} expr2