Dialplan Basics

This subject is dealt with in chapter 5 of the book Asterisk; The Future of Telephony.

The Asterisk dialplan is specified in the configuration file named extensions.conf.

The dialplan is made up of four main parts: contexts, extensions, priorities, and applications.

A complete extension is composed of three components:

• The name (or number) of the extension
• The priority (each extension can include multiple steps; the step number is called the “priority”)
• The application (or command) that performs some action on the call

These three components are separated by commas, like this:

exten => name,priority,application( )

Here’s a simple example of what a real extension might look like:

exten => 123,1,Answer( )

In this example, the extension name is 123, the priority is 1, and the application is Answer( ).

The name of the extension can also match a pattern. In order to do so, the pattern must start with an "_". See Pattern-matching syntax for details on the syntax.

Priorities

Each extension can have multiple steps, called priorities. Each priority is numbered sequentially, starting with 1. (Actually, there is one exception to this rule, as discussed in the sidebar “Unnumbered Priorities.”) Each priority executes one specific application. As an example, the following extension would answer the phone (in priority number 1), and then hang it up (in priority number 2):

exten => 123,1,Answer( )
exten => 123,2,Hangup( )

Since Asterisk really wants priorities start to at 1 and numbered consecutively, it will be annoying when it stops at the point where a number is skipped. To overcome this annoyance, Asterisk 1.2 introduced unnumbered priorities.

These are called the n priority, which stands for "next". Each time Asterisk encounters a priority named n, it takes the number of the previous priority and adds 1. This makes it easier to make changes to your dialplan, as you don’t have to keep renumbering all your steps. For example, your dialplan might look something like this:

exten => 123,1,Answer( )
exten => 123,n,do something
exten => 123,n,do something else
exten => 123,n,do one last thing
exten => 123,n,Hangup( )

Version 1.2 also allows you to assign text labels to priorities. To assign a text label to a priority, simply add the label inside parentheses after the priority, like this:

exten => 123,n(label),do something

This gives the possibility to jump between different priorities based on dialplan logic.

The s Extension

When calls enter a context without a specific destination extension (for example, a ringing FXO line), they are handled automatically by the s extension. (The s stands for “start,” as most calls start in the s extension.)

We will be performing three actions on the call (answer it, play a sound file, and hang it up), so we need to create an extension called s with three priorities. We’ll place the three priorities inside [incoming], as all incoming calls should start in this context:

[incoming]
exten => s,1,Answer( )
exten => s,2,Playback(hello-world)
exten => s,3,Hangup( )

The Background( ) and Goto( ) Applications

When users call into the following dialplan, they will hear a greeting saying, “Please enter the number you wish to call.” If they press 1, they will hear the number one, and if they press 2, they will hear the number two. The dialplan will repeat the greeting after playing back the number:

[incoming]
exten => s,1,Answer( )
exten => s,2,Background(enter-ext-of-person)
exten => 1,1,Playback(digits/1)
exten => 1,2,Goto(incoming,s,1)
exten => 2,1,Playback(digits/2)
exten => 2,2,Goto(incoming,s,1)

Handling Invalid Entries and Timeouts

Using the i and t extensions makes our dialplan a little more robust and userfriendly.

• i is the extension for invalid entry's (e.g. pressing a "3")
• t is the extension to handle situations when the caller doesn’t give input in time (the default timeout is 10 seconds).

[incoming]
exten => s,1,Answer( )
exten => s,2,Background(enter-ext-of-person)
exten => 1,1,Playback(digits/1)
exten => 1,2,Goto(incoming,s,1)
exten => 2,1,Playback(digits/2)
exten => 2,2,Goto(incoming,s,1)
exten => i,1,Playback(pbx-invalid)
exten => i,2,Goto(incoming,s,1)
exten => t,1,Playback(vm-goodbye)
exten => t,2,Hangup( )