The dialplan is truly the heart of any Asterisk system, as it defines how Asterisk handles inbound and outbound calls. In a nutshell, it consists of a list of instructions or steps that Asterisk will follow. Unlike traditional phone systems, Asterisk’s dialplan is fully customizable. To successfully set up your own Asterisk system, you will need to understand the dialplan.
The dialplan is specified in the file called extensions.conf (Location: /etc/asterisk/extensions.conf).
A dialplan has four main concepts:
Dialplans are divided into sections called contexts. The name of the context is placed inside square brackets ([ ]). The context for internal calls looks like this:
An extension is simply a named set of actions. Asterisk will perform each action in sequence.
The syntax for an extension is the word exten, followed by an arrow formed by the equals sign and the greater-than sign, like this:
exten => name,priority,application()
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.
Let’s take a closer look. Each line begins with the command exten. This is a directive inside Asterisk. You do not change this for each extension.
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().
Now, let’s move ahead and explain priorities and applications.
Priorities Each extension can have multiple steps, called priorities. Each priority is numbered sequentially, starting with 1, and 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()
The key point to remember here is that for a particular extension, Asterisk follows the priorities in order.
Beginning with version 1.2, Asterisk addressed this problem. It introduced the use of 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()
Internally, Asterisk will calculate the next priority number every time it encounters an n. You should note, however, that you must always specify priority number 1. If you accidentally put an n instead of 1 for the first priority, you’ll find that the extension will not be available.
Applications are the workhorses of the dialplan. Each application performs a specific action on the current channel, such as playing a sound, accepting touch-tone input, dialing a channel, hanging up the call, and so forth. In the previous example, you were introduced to two simple applications: Answer() and Hangup().
The Answer() application is used to answer a channel that is ringing. Answer() takes no arguments.
The Hangup() application hangs up the active channel. The Hangup() application takes no arguments.
The Playback() application is used for playing a previously recorded sound file over a channel. Playback() takes an argument, the name of the file to play. (Playback(/var/lib/asterisk/sounds/hello-world.gsm)
Add the following lines a the end of the extensions.conf file (Location: /etc/asterisk/extensions.conf).
Dial number 100 and asterisk will play the “hello-world” file.
In the first priority of extension, we’ll answer the call. In the second, we’ll play a sound file named hello-world.gsm, and in the third we’ll hang up the call.
If you have a channel or two configured, go ahead and try it out (In fact, if you don’t have any channels configured, now is the time to do so. There is a real satisfaction that comes from passing your first call into an Asterisk system that you built from scratch. People get this funny grin on their face as they realize that they have just created a telephone system. This pleasure can be yours as well, so please, don’t go any further until you have made this littledialplan work).
Simply create a file called extensions.conf, (probably in /etc/asterisk) and insert the four lines of dialplan code above . If it doesn’t work, check the Asterisk console for error messages, and make sure your channels are assigned to the [incoming] context.
Even though this example is very short and simple, it emphasizes the core concepts of contexts, extensions, priorities, and applications. If you can get this to work, you have the fundamental knowledge on which all dialplans are built.
Let’s build upon that example. After all, a phone system that simply plays a sound file and then hangs up the channel isn’t that useful!