Let's start with a simple example. We will design this dialplan such that as a call comes in, Asterisk answers the call, plays a sound file, then hang up the call. We'll use this example to demonstrate the most important dialplan features.
For the examples to work, we're assuming that at least one Zap channel has been created and configured, and that all incoming calls are sent to the [incoming] context of the dialplan. If you're using other types of channels, you may need to alter these examples to suit your particular case.
The s Extension
Before we get started with our dialplan, we need to explain a special extension called s. When calls enter a context without a specified 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:
exten => s,1,application( )
exten => s,2,application( )
exten => s,3,application( )
Now all we need to do next is fill in the applications, and we've created our first dialplan.
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 good practise. 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.
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:
This example would play filename.gsm from the /home/john/sounds/ directory. You can also use relative paths from the Asterisk sounds directory:
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.
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.
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:
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.