Asterisk: The Future of Telephony, 2nd Edition

A Simple Dialplan

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.

The s Extension

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.

Note

Note that we could have numbered each priority as shown below, but this is no longer the preferred method, as it makes it harder to make changes to the dialplan at a later time:

[incoming]
exten => s,1,application()
exten => s,2,application()
exten => s,3,application()

The Answer(), Playback(), and Hangup() Applications

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.

Tip

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

Our First Dialplan

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.

^[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.