Everything should be made as simple as possible, but not simpler.
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.
If you have attempted to read some sample dialplans and found them overwhelming, or if you’ve tried to write an Asterisk dialplan and had no success, help is at hand. This chapter explains how dialplans work in a step-by-step manner and teaches the skills necessary to create your own. The examples have been designed to build upon one another, so feel free to go back and reread a section if something doesn’t quite make sense. Please also note that this chapter is by no means an exhaustive survey of all the possible things dialplans can do; our aim is to cover just the fundamentals. We’ll cover more advanced dialplan topics in later chapters.
The Asterisk dialplan is specified in the configuration file named extensions.conf.
Tip
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 concepts: contexts, extensions, priorities, and applications. In the next few sections, we’ll cover each of these parts and explain how they work together. 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.
Dialplans are broken into sections called contexts. Contexts are named groups of extensions, which serve several purposes.
Contexts 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 other 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.[70] For example, a context for incoming calls looks like
this:
[incoming]
Note
Context names have a maximum length of 79 characters (80 characters –1 terminating null)
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]. The [general] section contains a list of general
dialplan settings (which you’ll probably never have to worry about),
and we will discuss the [globals]
context the Global variables” section; for
now it’s just important to know that these two contexts are special.
As long as you avoid the names [general] and [globals], you may name your contexts
anything you like.
When you define a channel (which is how you connect things to the system), one of the parameters that is defined in the channel definition is the context. In other words, the context is the point in the dialplan where connections from that channel will begin.
Another important use of contexts (perhaps the most important) is to provide 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.
Warning
The doc/ subdirectory of the Asterisk source code contains a very important file named security.txt, 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 paying—literally! Please take the time and effort to secure your system from toll fraud.
In the world of telecommunications, the word extension usually refers to a numeric identifier given to a line that rings a particular phone. In Asterisk, however, an extension is far more powerful, as it defines a unique series of steps (each step containing an application) that Asterisk will take that call through. Within each context, we can define as many (or few) extensions as required. When a particular extension is triggered (by an incoming call or by digits being dialed on a channel), Asterisk will follow the steps defined for that extension. It is the extensions, therefore, that specify what happens to calls as they make their way through the dialplan. Although extensions can certainly be used to specify phone extensions in the traditional sense (i.e., extension 153 will cause the SIP telephone set on John’s desk to ring), in an Asterisk dialplan, they can be used for much more.
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 (or number) of the extension. When dealing with traditional 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 more; for 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.
Tip
Assigning names to extensions may seem like a revolutionary concept, but when you realize that many VoIP transports support (or even actively encourage) dialing by name or email address instead of only dialing by number, it makes perfect sense. This is one of the features that makes Asterisk so flexible and powerful.
A complete extension is composed of three components:
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.
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()
Don’t worry if you don’t understand what Answer() and Hangup() are—we’ll cover them shortly. The
key point to remember here is that for a particular extension,
Asterisk follows the priorities in order.
In older releases of Asterisk, the numbering of priorities caused a lot of problems. Imagine having an extension that had 15 priorities, and then needing to add something at step 2. All of the subsequent priorities would have to be manually renumbered. Asterisk does not handle missing steps or misnumbered priorities, and debugging these types of errors was pointless and frustrating.
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 somethingexten => 123,n,do something elseexten => 123,n,do one last thingexten => 123,n,Hangup()
Internally, Asterisk will calculate the next priority number
every time it encounters an n.[71] 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.
Starting with Asterisk version 1.2 and higher, common practice is to assign text labels to priorities. This is to ensure that you can refer to a priority by something other than its number, which probably isn’t known, given that dialplans now generally use unnumbered priorities. To assign a text label to a priority, simply add the label inside parentheses after the priority, like this:
exten => 123,n(label),application()
Warning
A very common mistake when writing labels is to insert a
comma between the n and the
(, like this:
exten => 123,n,(label),application();<-- THIS IS NOT GOING TO WORK
This mistake will break that part of your dialplan, and you will get an error that the application cannot be found.
In the next chapter, we’ll cover how to jump between different priorities based on dialplan logic. You’ll be seeing a lot more of priority labels, and you will be using them often in your dialplans.
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(). You’ll
learn more about how these work momentarily.
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.
Tip
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, we will
be using the comma to separate arguments to an application, as the
authors prefer the look of this syntax. You should be aware,
however, that when Asterisk parses the dialplan, it converts any
commas in the application arguments to pipes.
As we build our first dialplan in the next section, you’ll learn to use applications (and their associated arguments) to your advantage.
[70] Please note that the space is conspicuously absent from the list of allowed characters. Don’t use spaces in your context names—you won’t like the result!
[71] Asterisk permits simple arithmetic within the priority,
such as n+200 or the priority
s (for same), but their usage
is considered to be an advanced topic. Please note that
extension s and priority
s are two distinct
concepts.
Get Asterisk: The Future of Telephony, 2nd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
