The asterisk dialplan is the core of an Asterisk system, for it defines how Asterisk handles outbound and inbound calls. It consists of a list of instructions that Asterisk follows to perform given actions. Asterisk's dialplan is fully customizable. You will need to understand the dialplan to successfully set up your own Asterisk system.
Asterisk Dialplan Basics
The Asterisk dialplan is configured in the configuration file named extensions.conf.
The extensions.conf file is located in the /etc/asterisk/ directory, but its location may change depending on how you installed Asterisk. Other locations for this file include /usr/local/asterisk/etc/ and /opt/asterisk/etc/.
The dialplan consists of four main parts; contexts, priorities, extensions and applications.
Sample Configuration Files
If you installed the sample config files during asterisk installation, you will most likely have an existing extensions.conf file. The alternative of starting with the sample file is to build your extensions.conf file from scratch. This could be useful in giving you a better grasp of dialplan concepts.
The sample extensions.conf file remains a useful resource, filled with examples and ideas that one can use after learning the basic concepts. You can rename the sample file to something like extensions.conf.sample. This way, you can refer to it in the future. You can also find the sample configuration files in the /configs/ directory of the Asterisk source.
Dialplans are divided into sections known as contexts. Contexts are named groups of extensions. Simply said, contexts isolate different parts of the dialplan from one another. An extension that is defined in one context is completely isolated from extensions in any another context, unless interaction is intentionally allowed.
An example would be: let's say we have two companies sharing an Asterisk server. If we place each company's voice menu in its own context, they are effectively isolated from each other. This allows us to separately define what happens when, say, extension 0 is dialed: people pressing 0 at Company A's voice menu will get Company A's receptionist, and callers pressing 0 at Company B's voice menu will get Company B's receptionist. (assuming we've told Asterisk to pass the calls to the receptionists when callers press 0.)
Contexts are created by placing the name of the context inside square brackets (). The name can be made up of the letters A-Z (upper and lowercase), the numbers 0-9, and the hyphen and underscore. Don't use spaces in your context names. It'll break your system. For example, a context for incoming calls looks like this:
All of the instructions placed after a context definition are part of that context, until the next context is defined. At the beginning of the dialplan, there are two special contexts named [general] and [globals]. these two contexts are special.
Contexts enforce security. By using contexts correctly, one can give certain callers access to features (eg long-distance calling) that aren't available to other users. If you don't design your dialplan carefully, others can fraudulently use your system. Keep this in mind as you build your Asterisk system.
The Asterisk source contains a very important file named SECURITY, which outlines several steps you should take to secure your Asterisk system. It is important that you read and understand this file. If you ignore the security precautions outlined there, you may end up allowing anyone to make long-distance or toll calls at your expense.
If you don't take the security of your Asterisk system seriously, you may end up paying literally. Please take the time and effort to secure your system from toll fraud.
Within each context, we define one or more extensions. An extension is an instruction that Asterisk will follow and is triggered by a incoming call or by digits being dialed on a channel. Extensions specify what happens to calls step after step through the dialplan. Although extensions can be used to specify phone extensions in the traditional sense (i.e., please call John at extension 153), they can be used for more in Asterisk.
An extension's notation is the word exten, followed by an arrow composed of the equals sign and the > sign, as shown below:
This is followed by the extension's name. When dealing with telephony systems, we tend to see extensions as the numbers you dialed to make another phone ring. However, in Asterisk, you can do a lot more eg, extension names can contain any combination of numbers and/or letters.
Naming extensions may look like a disruptive concept, but that many Voice-over-IP transports support and even actively encourage dialing by name or email address as opposed to by number, it makes sense. This is one of the many features that make Asterisk flexible and very powerful.
A complete extension has 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 an example of what a real extension looks like:
exten => 123,1,Answer( )
In this example, the extension's name is 123, the priority is 1, and the application is Answer( ).
An extension can have multiple steps, called priorities. Each priority is numbered sequentially, beginning from 1. There is one exception to this rule, for "Unnumbered Priorities.") Each priority executes one specific application. E.g. 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( )
You must ensure that your priorities begin at 1 and are numbered consecutively. If you skip a priority, Asterisk will not continue past it. If you find that Asterisk is not following all the priorities in a given extension, you may want to check that you haven't skipped or misnumbered a priority.
Don't worry if you don't understand what Answer( ) and Hangup( )are. we'll discuss them shortly. The key point to remember here is that for a given extension, Asterisk follows the priorities in numerical order.
Applications are the action initiators of the dialplan. Each application performs a specific action on the current channel, such as playing a sound, accepting touch-tone input, or hanging up the call. Previously, you were introduced to two simple applications: Answer( ) and Hangup( ). You'll learn more about how these work in a moment.
Version 1.2 of Asterisk adds a new feature to priority numbering as it introduces the use of the n priority, which stands for "next." Every time Asterisk encounters a priority named n, it takes the number of the previous priority and adds 1. This eases changing your dialplan, as you don't have to renumber all your steps over and over again. e.g, your dialplan might look 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 lets you to assign text labels to priorities. To assign a text label to a priority, simply add the label inside parentheses immediately after the priority, like below
exten => 123,n(label),do something
Some applications, such as Answer( )andHangup( ), need no other instructions to do their jobs. Other applications may require additional information. These pieces of information, known as arguments, can be passed on to the applications to determine how they perform their actions. To pass arguments to an application, place them between the parentheses after the application name, separated by commas.
Occasionally, you may also notice the pipe character (|) being used as a separator between arguments, instead of a comma. Feel free to use whichever you prefer.