Introduction to Asterisk Dialplan Priorities

Asterisk Priorities are used within a dialplan, in the extensions.conf configuration file.

Priorities are numbered steps in the execution of each command that make up an extension. Each priority represents one specific application. Typically, priority numbers start at 1 and increment consecutively for each line in the context. Priority numbers are not always consecutive, but we will worry about that later. For now, just remember that for each extension, Asterisk runs each priority in numerical order — as opposed to the order in which they appear in the file.

Example

   exten => 555,1,Answer
   exten => 555,2,Playback(tt-weasels)
   exten => 555,3,Voicemail(44)
   exten => 555,4,Hangup

This example is a definition of a single extension with the name "555". When a call is made to extension 555, Asterisk will answer the call itself, play a sound file called "tt-weasels", give the user an opportunity to leave a voicemail message for mailbox 44, and then hangup.

In the example, "exten =>" tells the dialplan that the next thing it sees will be a command.

"555" are the actual digits received (i.e. what the caller dialed, or the "extension" number dialed).

"1", "2", "3", and "4" represent the priority, which determines the order in which commands for that extension will be executed.

Note that Asterisk does not care about the order in which you put the lines in the extensions.conf file. You could mix the lines into a different order, like this following example, and it would make no difference because Asterisk uses the priority of each line to determine order of execution:

   exten => 555,4,Hangup
   exten => 555,1,Answer
   exten => 555,3,Voicemail(44)
   exten => 555,2,Playback(tt-weasels)

The n Priority (Asterisk 1.2.x and later versions)

Instead of having to manually number (and renumber) priorities within a given extension, you may use "n" to represent the next priority. The "n" automatically increases a priority's value incrementally. Previously, if you wanted to insert a command between the third and fourth line of a 20-priority extension, you would need to manually renumber each priority after the inserted line.

Example

   exten => 555,1,Answer
   exten => 555,n,Playback(tt-weasels)
   exten => 555,n,Voicemail(44)
   exten => 555,n,Hangup

Using "n" priorities, there are two things you can do that make creating extension logic a lot easier.

The first is that you can set labels:

 exten => s,n(Start),Answer

As well as making the dialplan more readable, labels can be the target of gotos:

 exten => s,n,Goto(Start)

The second feature that makes using priorities easier is that arbitrary increments can be defined:

 exten => s,n+2,Dial(...)

Maybe its utility is not so obvious, but in conjunction with labels, it can be pretty handy. In a typical dialplan, Asterisk must often handle the "+101" priority to handle the failure condition of an application, like Dial(). Without the n priority, if you were to change one of the lines within an extension, not only must the Dial() priority change, so must the corresponding +101 priority.

With n priority increments, the following expression is possible:

 exten => s,n(MainDial),Dial(...) ; Dial the main numbers for this context
 ...
 ...
 exten => s,MainDial+101,Voicemail(u100)

Now when new dial plan instructions are added before (MainDial) there is no need to update any priorities.

Note that the "+101" priority may also use a label:

 exten => s,MainDial+101(MainDialNotAnswered),Voicemail(u100)

See also

• extensions.conf: The Asterisk Dialplan
• Asterisk Visual Dialplan