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.
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:
[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.
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(
)andHangup( ), 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. |