Section 5.1. Dialplan Syntax

5.1. Dialplan Syntax

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

The extensions.conf file usually resides in the /etc/asterisk/ directory, but its location may vary depending on how you installed Asterisk. Other common locations for this file include /usr/local/asterisk/etc/ and /opt/asterisk/etc/ .

The dialplan is made up of four main parts : contexts, extensions, priorities, and applications. In the next few sections, we'll cover each of these parts and explain how they work together to create a dialplan. After explaining the role each of these elements plays in the dialplan , we will step you though the process of creating a basic, functioning dialplan.

Sample Configuration Files

If you installed the sample configuration files when you installed Asterisk, you will most likely have an existing extensions.conf file. Instead of starting with the sample file , we suggest that you build your extensions.conf file from scratch. This will be very beneficial, as it will give you a better understanding of dialplan concepts and fundamentals.

That being said, the sample extensions.conf file remains a fantastic resource, full of examples and ideas that you can use after you've learned the basic concepts. We suggest you rename the sample file to something like extensions.conf.sample . That 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.

5.1.1. Contexts

Dialplans are broken into sections called contexts . Contexts are named groups of extensions. Simply put, they keep different parts of the dialplan from interacting with one another. An extension that is defined in one context is completely isolated from extensions in any another context, unless interaction is specifically allowed. (We'll cover how to allow interaction between contexts near the end of the chapter.)

As a simple example, let's imagine we have two companies sharing an Asterisk server. If we place each company's voice menu in its own context, they are effectively separated from each other. This allows us to independently 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 . (This example assumes, of course, that we've told Asterisk to transfer the calls to the receptionists when callers press 0.)

Contexts are denoted by placing the name of the context inside square brackets ( [] ). The name can be made up of the letters A through Z (upper- and lowercase), the numbers 0 through 9, and the hyphen and underscore . ^[*] For example, a context for incoming calls looks like this:

^[*] Please note that the space is conspicuously absent from the list of allowed characters . Don't use spaces in your context namesyou won't like the result!

 [incoming] 

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 ] . We will discuss the [globals] context later in this chapter; for now it's just important to know that these two contexts are special.

One of the most important uses of contexts is to enforce security. By using contexts correctly, you can give certain callers access to features (such as long-distance calling) that aren't made available to others. If you don't design your dialplan carefully , you may inadvertently allow others to fraudulently use your system. Please 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 keep your Asterisk system secure. It is vitally important that you read and understand this file. If you ignore the security precautions outlined there, you may end up allowing anyone and everyone 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 payingliterally! Please take the time and effort to secure your system from toll fraud.

5.1.2. Extensions

Within each context, we define one or more extensions . An extension is an instruction that Asterisk will follow, triggered by an incoming call or by digits being dialed on a channel. Extensions specify what happens to calls as they make their way 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 much more in Asterisk.

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 => 

This is followed by the name of the extension. When dealing with telephone systems, we tend to think of extensions as the numbers you would dial to make another phone ring. In Asterisk, you get a whole lot morefor example, extension names can be any combination of numbers and letters. Over the course of this chapter and the next, we'll use both numeric and alphanumeric extensions.

Assigning names to extensions may seem like a revolutionary concept, but when you realize that many Voice-over-IP transports support (or even actively encourage ) dialing by name or email address instead of by number, it makes perfect sense. This is one of the features that make Asterisk so flexible and powerful.

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( ) . Now, let's move ahead and explain priorities and applications.

5.1.3. 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( ) 

You must make sure that your priorities start 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 make sure you haven't skipped or misnumbered a priority.

Don't worry if you don't understand what Answer( ) and Hangup( ) arewe'll cover them shortly. The key point to remember here is that for a particular extension, Asterisk follows the priorities in numerical order.

5.1.4. Applications

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, or hanging up the call. In the previous example, you were introduced to two simple applications: Answer( ) and Hangup( ) . You'll learn more about how these work momentarily.

Unnumbered Priorities

There's nothing like telling you that priorities have to be numbered sequentially, and then contradicting ourselves . Oh well, it needs to be done.

Version 1.2 of Asterisk adds a new twist to priority numbering. It introduces 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( ) 

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   

In the next chapter, we'll cover how to jump between different priorities based on dialplan logic.

Some applications, such as Answer( ) and Hangup( ) , need no other instructions to do their jobs. Other applications require additional information. These pieces of information, called arguments , can be passed on to the applications to affect how they perform their actions. To pass arguments to an application, place them between the parentheses that follow the application name, separated by commas.

Occasionally, you may also see the pipe character ( ) being used as a separator between arguments, instead of a comma. Feel free to use whichever you prefer. For the examples in this book, however, we'll be using the comma to separate arguments to an application.

As we build our first dialplan in the next section, you'll learn to use applications (and their associated arguments) to your advantage.