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. Xany digit from 0-9 Zany digit from 1-9 Nany 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 dialplan show 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 dialplan show dialplan show 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 dialplan show dialplan show

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 dial plan show 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 In Asterisk 1.2: show dialplan

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,Voic (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...)

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.

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 => [test1] exten => 105,1,NoOp(${FEE}) exten => 105,2,NoOp(${FIE}) exten => 105,3,NoOp(${FUM}) exten => [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- voic ] 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 identifierspecifies “phone number” to dial on that channel specify more than one channel for dial command using & sign. Timeoutoptional 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 ANSWERa sucessful dial BUSYthe number is busy NOANSWERthe number rang but no one answer the call CANCELdial command reached the number but the caller handup before the called person picked up CONGESTIONcongestion usually means number is not recognized CHANUNAVAILchannel 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 voic .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)= )

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