5.2. A Simple Dialplan

Now we're ready to create our first dialplan. We'll start with a very simple example. We will design this dialplan so that as a call comes in, Asterisk will answer the call, play a sound file, and then hang up the call. 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 Zap channel has been created and configured (as described in the previous chapter), and that all incoming calls are sent to the [incoming]context. If you're using other types of channels, you may need to adjust these examples to fit your particular circumstances.

5.2.1. The s Extension

Before we get started with our dialplan, we ought to explain a special extension called s. When calls enter a context without a specific destination extension (for example, a ringing FXO line), they are handled automatically by the s extension. (The s stands for "start," as most calls start in the s extension.) 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 we need to create an extension called s with three priorities. We'll place the three priorities inside [incoming], as all incoming calls should start in this context:

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

Now all we need to do is fill in the applications, and we've created our first dialplan.

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

Asterisk comes with many professionally recorded sound files, which should be found in the default sounds directory (usually /var/lib/asterisk/sounds/). They have been recorded in the GSM format, so they have a .gsm file extension. We'll be using these files in many of our examples. Several of the files in our examples come from the asterisk-sounds module, so please take the time to install it (see Chapter 3).

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)

This example would play filename.gsm from the /home/john/sounds/ directory. You can also use relative paths from the Asterisk sounds directory:

    Playback(custom/filename)

This example would play filename.gsm from the custom/ subdirectory of the default sounds directory. 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.^[*]

^[*] 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. We'll cover more about the different audio formats (known as codecs) in Chapter 8.

The Hangup( ) application does exactly as its name implies: it hangs up the active channel. The caller will receive an indication that the call has been hung up. You will 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. This application takes no arguments.

5.2.3. Our First Dialplan

Now that we have created our extension, given it three different priorities, and learned about the applications we are going to use, 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,2,Playback(hello-world)
    exten => s,3,Hangup( )

If you have a channel or two configured, go ahead and try it out! Simply make a new extensions.conf file with this short dialplan. (If it doesn't work, check the Asterisk console for error messages, and make sure your channels are configured to send inbound calls to the [incoming] context.)

Even though this example is very short and simple, it emphasizes the core concepts of contexts, extensions, priorities, and applications. Now that we've covered these basic concepts, 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!