Now we’re ready to create our first dialplan. We’ll start with a very simple example. We are going to instruct Asterisk to answer a call, play a sound file, and hang up. We’ll use this simple example to point out the most important dialplan fundamentals.
For the examples in this chapter to work correctly, we’re assuming
that at least one channel (either Zap, SIP, or IAX2) has been created and
configured (as described in the previous chapter), and that all calls
coming into that channel enter the dialplan at the [incoming] context. If you have been creative
with any previous examples, you may need to make adjustments to fit your
particular channel names.
Because of the technology we are using in our channels, we need to cover
one more thing before we get started with our dialplan. We need to
explain extension s. When calls enter
a context without a specific destination extension (for example, a
ringing FXO line), they are passed to the s extension. (The s stands for “start,” as this is where a call
will start if no extension information was passed with the call.)
Since this is exactly what we need for our dialplan, let’s begin
to fill in the pieces. We will be performing three actions on the call
(answer it, play a sound file, and hang it up), so our extension called
s will need three priorities. We’ll
place the three priorities below [incoming], because we have decided that all incoming calls should
start in this context.[72]
[incoming] exten => s,1,application()exten => s,n,application()exten => s,n,application()
Now all we need to do is fill in the applications, and we’ve created our first dialplan.
If we’re going to answer the call, play a sound file, and then hang up,
we’d better learn how to do just that. The Answer() application is used to answer a
channel that is ringing. This does the initial setup for the channel
that receives the incoming call. (A few applications don’t require that
you answer the channel first, but properly answering the channel before
performing any other actions is a very good habit.) As we mentioned
earlier, Answer() takes no
arguments.
The Playback() application is
used for playing a previously recorded sound file over a channel. When
using the Playback() application,
input from the user is simply ignored.
Asterisk comes with many professionally recorded sound files, which should be found in the default sounds directory (usually /var/lib/asterisk/sounds/). When you compile Asterisk, you can choose to install various sets of sample sounds that have been recorded in a variety of languages and file formats. We’ll be using these files in many of our examples. Several of the files in our examples come from the Extra Sound Package, so please take the time to install it (see Chapter 3, Installing Asterisk). You can also have your own sound prompts recorded in the same voices as the stock prompts by visiting http://thevoice.digium.com/.
To use Playback(), specify a
filename (without a file extension) as the argument. For example,
Playback(filename) would play the
sound file called filename.gsm, assuming it was
located in the default sounds directory. Note that you can include the
full path to the file if you want, like this:
Playback(/home/john/sounds/filename)
The previous example would play filename.gsm from the /home/john/sounds/ directory. You can also use relative paths from the Asterisk sounds directory as follows:
Playback(custom/filename)
This example would play filename.gsm from the custom/ subdirectory of the default sounds directory (probably /var/lib/asterisk/sounds/custom/filename.gsm). Note that if the specified directory contains more than one file with that filename but with different file extensions, Asterisk automatically plays the best file.[73]
The Hangup() application does
exactly as its name implies: it hangs up the active channel. You should
use this application at the end of a context when you want to end the
current call to ensure that callers don’t continue on in the dialplan in
a way you might not have anticipated. The Hangup() application takes no
arguments.
Now that we have designed our extension, let’s put together all the pieces to create our first dialplan. As is typical in many technology books (especially computer programming books), our first example will be called “Hello World!”
In the first priority of our 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. Here’s what the dialplan looks like:
[incoming] exten => s,1,Answer() exten => s,n,Playback(hello-world) exten => s,n,Hangup()
If you have a channel or two configured, go ahead and try it
out![74] Simply create a file called
extensions.conf, (probably in
/etc/asterisk) and insert the four lines of
dialplan code we just designed. 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 our example. After all, a phone system that simply plays a sound file and then hangs up the channel isn’t that useful!
[72] There is nothing special about any context name. We could have
named this context [stuff_that_comes_in], and as
long as that was the context assigned in the channel definition in
sip.conf, iax.conf,
zaptel.conf, et al., the channel would enter
the dialplan in that context. Having said that, it is strongly
recommended that you give your contexts names that help you to
understand their purpose. Some good context names might include
[incoming], [local_calls],
[long_distance],
[sip_telephones],
[user_services],
[experimental],
[remote_locations], and so forth. Always remember
that a context determines how a channel enters the dialplan, so name
accordingly.
[73] Asterisk selects the best file based on translation cost―that
is, it selects the file that is the least CPU-intensive to convert
to its native audio format. When you start Asterisk, it calculates
the translation costs between the different audio formats (they
often vary from system to system). You can see these translation
costs by typing show translation at the Asterisk
command-line interface. The numbers shown represent how many
milliseconds it takes Asterisk to transcode one second of audio.
We’ll cover more about the different audio formats (known as
codecs) in Chapter 8, Protocols for VoIP.
[74] 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 little dialplan work.