One of the most important keys to building interactive Asterisk dialplans is the Background()^[75] application. Like Playback(), it plays a recorded sound file. Unlike Playback(), however, when the caller presses a key (or series of keys) on her telephone keypad, it interrupts the playback and goes to the extension that corresponds with the pressed digit(s). If a caller presses 5, for example, Asterisk will stop playing the sound prompt and send control of the call to the first priority of extension 5.

The most common use of the Background() application is to create voice menus (often called auto-attendants or phone trees). Many companies use voice menus to direct callers to the proper extensions, thus relieving their receptionists from having to answer every single call.

Background() has the same syntax as Playback():

exten => 123,1,Answer()
exten => 123,n,Background(main-menu)

In earlier versions of Asterisk, if the Background() application finished playing the sound prompt and there were no more priorities in the current extension, Asterisk would sit and wait for input from the caller. Asterisk no longer does this by default. If you want Asterisk to wait for input from the caller after the sound prompt has finished playing, you can call the WaitExten() application. The WaitExten() application waits for the caller to enter DTMF digits, and is frequently called directly after the Background() application, like this:

exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 123,n,WaitExten()

If you’d like the WaitExten() application to wait a specific number of seconds for a response (instead of using the default timeout), simply pass the number of seconds as the first argument to WaitExten(), like this:

exten => 123,n,WaitExten(5)

Both Background() and WaitExten() allow the caller to enter DTMF digits. Asterisk then attempts to find an extension in the current context that matches the digits that the caller entered. If Asterisk finds an unambiguous match, it will send the call to that extension. Let’s demonstrate by adding a few lines to our example:

exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 123,n,WaitExten()

exten => 2,1,Playback(digits/2)

exten => 3,1,Playback(digits/3)

exten => 4,1,Playback(digits/4)

If you call into extension 123 in the example above, it will play a sound prompt that says “main menu.” It will then wait for you to enter either 2, 3, or 4. If you press one of those digits, Asterisk will read that digit back to you. You’ll also find that if you enter a different digit (such as 5), it won’t give you what you expected.

It is also possible that Asterisk will find an ambiguous match. This can be easily explained if we add an extension named 1 to the previous example:

exten => 123,1,Answer()
exten => 123,n,Background(main-menu)
exten => 123,n,WaitExten()

exten => 1,1,Playback(digits/1)

exten => 2,1,Playback(digits/2)

exten => 3,1,Playback(digits/3)

exten => 4,1,Playback(digits/4)

Dial extension 123, and then at the main menu prompt dial 1. Why doesn’t Asterisk immediately read back the number one to you? It’s because the digit 1 is ambiguous; Asterisk doesn’t know whether you’re trying to go to extension 1 or extension 123. It waits a few seconds to see if you’re going to dial another digit (such as the 2 in extension 123). If you don’t dial any more digits, Asterisk will eventually time out and send the call to extension 1. (We’ll learn how to choose our own timeout values in Chapter 6, More Dialplan Concepts.)

Before going on, let’s review what we’ve done so far. When users call into our dialplan, they will hear a greeting. If they press 1, they will hear the number one, and if they press 2, they will hear the number two, and so on. While that’s a good start, let’s embellish it a little. We’ll use the Goto() application to make the dialplan repeat the greeting after playing back the number.

As its name implies, the Goto() application is used to send the call to another part of the dialplan. The syntax for the Goto() application requires us to pass the destination context, extension, and priority on as arguments to the application, like this:

exten => 123,n,Goto(context,extension,priority)

Now, let’s use the Goto() application in our dialplan:

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(main-menu)

exten => 1,1,Playback(digits/1)
exten => 1,n,Goto(incoming,123,1)

exten => 2,1,Playback(digits/2)
exten => 2,n,Goto(incoming,123,1)

These two new lines (highlighted in bold) will send control of the call back to the 123 extension after playing back the selected number.

Now that our first voice menu is starting to come together, let’s add some additional special extensions. First, we need an extension for invalid entries; when a caller presses an invalid entry (e.g., pressing 9 in the above example), the call is sent to the i extension. Second, we need an extension to handle situations when the caller doesn’t give input in time (the default timeout is 10 seconds). Calls will be sent to the t extension if the caller takes too long to press a digit after WaitExten() has been called. Here is what our dialplan will look like after we’ve added these two extensions:

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()

exten => 1,1,Playback(digits/1)
exten => 1,n,Goto(incoming,123,1)

exten => 2,1,Playback(digits/2)
exten => 2,n,Goto(incoming,123,1)

exten => 3,1,Playback(digits/3)
exten => 3,n,Goto(incoming,123,1)

exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)

exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()

Using the i and t extensions makes our dialplan a little more robust and user-friendly. That being said, it is still quite limited, because outside callers have no way of connecting to a live person. To do that, we’ll need to learn about another application, called Dial().

One of Asterisk’s most valuable features is its ability to connect different callers to each other. This is especially useful when callers are using different methods of communication. For example, caller A might be communicating over the traditional analog telephone network, while user B might be sitting in a café halfway around the world and speaking on an IP telephone. Luckily, Asterisk takes most of the hard work out of connecting and translating between disparate networks. All you have to do is learn how to use the Dial() application.

The syntax of the Dial() application is a little more complex than that of the other applications we’ve used so far, but don’t let that scare you off. Dial() takes up to four arguments. The first is the destination you’re attempting to call, which (in its simplest form) is made up of a technology (or transport) across which to make the call, a forward slash, and the remote endpoint or resource. Common technology types include Zap (for analog and T1/E1/J1 channels), SIP, and IAX2. For example, let’s assume that we want to call a Zap endpoint identified by Zap/1, which is an FXS channel with an analog phone plugged into it. The technology is Zap, and the resource is 1. Similarly, a call to a SIP device (as defined in sip.conf) might have a destination of SIP/Jane, and a call to an IAX device (defined in iax.conf) might have a destination of IAX2/Fred. If we wanted Asterisk to ring the Zap/1 channel when extension 123 is reached in the dialplan, we’d add the following extension:

exten => 123,1,Dial(Zap/1)

We can also dial multiple channels at the same time, by concatenating the destinations with an ampersand (&), like this:

exten => 123,1,Dial(Zap/1&Zap/2&SIP/Jane)

The Dial() application will ring the specified destinations simultaneously, and bridge the inbound call with whichever destination channel answers the call first. If the Dial() application can’t contact any of the destinations, Asterisk will set a variable called DIALSTATUS with the reason that it couldn’t dial the destinations, and continue on with the next priority in the extension.^[76]

The Dial() application also allows you to connect to a remote VoIP endpoint not previously defined in one of the channel configuration files. The full syntax for this type of connection is:

Dial(technology/user[:password]@remote_host[:port][/remote_extension])

As an example, you can dial into a demonstration server at Digium using the IAX2 protocol by using the following extension:

exten => 500,1,Dial(IAX2/guest@misery.digium.com/s)

The full syntax for the Dial() application is slightly different when dealing with Zap channels, as shown:

Dial(Zap/[gGrR]channel_or_group[/remote_extension])

For example, here is how you would dial 1-800-555-1212 on Zap channel number 4.

exten => 501,1,Dial(Zap/4/18005551212)

The second argument to the Dial() application is a timeout, specified in seconds. If a timeout is given, Dial() will attempt to call the destination(s) for that number of seconds before giving up and moving on to the next priority in the extension. If no timeout is specified, Dial() will continue to dial the called channel(s) until someone answers or the caller hangs up. Let’s add a timeout of 10 seconds to our extension:

exten => 123,1,Dial(Zap/1,10)

If the call is answered before the timeout, the channels are bridged and the dialplan is done. If the destination simply does not answer, is busy, or is otherwise unavailable, Asterisk will set a variable called DIALSTATUS and then continue on with the next priority in the extension.

Let’s put what we’ve learned so far into another example:

exten => 123,1,Dial(Zap/1,10)    
exten => 123,n,Playback(vm-nobodyavail)
exten => 123,n,Hangup()

As you can see, this example will play the vm-nobodyavail.gsm sound file if the call goes unanswered.

The third argument to Dial() is an option string. It may contain one or more characters that modify the behavior of the Dial() application. While the list of possible options is too long to cover here, one of the most popular options is the m option. If you place the letter m as the third argument, the calling party will hear hold music instead of ringing while the destination channel is being called (assuming, of course, that music on hold has been configured correctly). To add the m option to our last example, we simply change the first line:

exten => 123,1,Dial(Zap/1,10,m)
exten => 123,n,Playback(vm-nobodyavail)
exten => 123,n,Hangup()

Since the extensions numbered 1 and 2 in our dialplan are somewhat useless now that we know how to use the Dial() application, let’s replace them with new extensions that will allow outside callers to reach John and Jane:

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()

exten => 1,1,Dial(Zap/1,10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()

exten => 2,1,Dial(SIP/Jane,10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()

exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)

exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()

The fourth and final argument to the Dial() application is a URL. If the destination channel supports receiving a URL at the time of the call, the specified URL will be sent (for example, if you have an IP telephone that supports receiving a URL, it will appear on the phone’s display; likewise, if you’re using a soft phone, the URL might pop up on your computer screen). This argument is very rarely used.

Note that the second, third, and fourth arguments may be left blank. For example, if you want to specify an option but not a timeout, simply leave the timeout argument blank, like this:

exten => 1,1,Dial(Zap/1,,m)

In our examples thus far, we have limited ourselves to a single context, but it is probably fair to assume that almost all Asterisk installations will have more than one context in their dialplans. As we mentioned at the beginning of this chapter, one important function of contexts is to separate privileges (such as making long-distance calls or calling certain extensions) for different classes of callers. In our next example, we’ll add to our dialplan by creating two internal phone extensions, and we’ll set up the ability for these two extensions to call each other. To accomplish this, we’ll create a new context called [employees].

Our dialplan now looks like this:

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()

exten => 1,1,Dial(Zap/1,10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()

exten => 2,1,Dial(SIP/Jane,10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()

exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)

exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()

[employees]
exten => 101,1,Dial(Zap/1)

exten => 102,1,Dial(SIP/Jane)

In this example, we have added two new extensions to the [employees] context. This way, the person using channel Zap/1 can pick up the phone and dial the person at channel SIP/Jane by dialing 102. By that same token, the phone registered as SIP/Jane can dial Zap/1 by dialing 101.

We’ve arbitrarily decided to use extensions 101 and 102 for our examples, but feel free to use whatever numbering convention you wish for your extensions. You should also be aware that you’re not limited to three-digit extensions; you can use as few or as many digits as you like. (Well, almost. Extensions must be shorter than 80 characters long, and you shouldn’t use single-character extensions for your own use, as they’re reserved.) Don’t forget that you can use names as well, like so:

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()

exten => 1,1,Dial(Zap/1,10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()

exten => 2,1,Dial(SIP/Jane,10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()

exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)

exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()

[employees]
exten => 101,1,Dial(Zap/1)
exten => john,1,Dial(Zap/1)

exten => 102,1,Dial(SIP/Jane)
exten => jane,1,Dial(SIP/Jane)

It certainly wouldn’t hurt to add named extensions if you think your users might be dialed via a VoIP protocol such as SIP that supports dialing by name. You can also see that it is possible to have different extensions in the dialplan ring the same endpoint. For example, you could have extension 200 ring SIP/George, and then have extension 201 play a prompt of some kind and then ring SIP/George.

Now that our internal callers can call each other, we’re well on our way toward having a complete dialplan. Next, we’ll see how we can make our dialplan more scalable and easier to modify in the future.

Variables can be used in an Asterisk dialplan to help reduce typing, add clarity, or add additional logic to a dialplan. If you have some computer programming experience, you probably already understand what a variable is. If not, don’t worry; we’ll explain what variables are and how they are used.

You can think of a variable as a container that can hold one value at a time. So, for example, we might create a variable called JOHN and assign it the value of Zap/1. This way, when we’re writing our dialplan, we can refer to John’s channel by name, instead of remembering that John is using the channel named Zap/1.

There are two ways to reference a variable. To reference the variable’s name, simply type the name of the variable, such as JOHN. If, on the other hand, you want to reference its value, you must type a dollar sign, an opening curly brace, the name of the variable, and a closing curly brace. Here’s how we’d reference the variable inside the Dial() application:

exten => 555,1,Dial(${JOHN})

In our dialplan, whenever we write ${JOHN}, Asterisk will automatically replace it with whatever value has been assigned to the variable named JOHN.

There are three types of variables we can use in our dialplan: global variables, channel variables, and environment variables. Let’s take a moment to look at each type.

[globals]
JOHN=Zap/1

[employees]
exten => 124,1,Set(GLOBAL(GEORGE)=SIP/George)

exten => 125,1,Set(MAGICNUMBER=42)

[globals]
JOHN=Zap/1
JANE=SIP/Jane

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()

exten => 1,1,Dial(${JOHN},10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()

exten => 2,1,Dial(${JANE},10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()

exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)

exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()

[employees]

exten => 101,1,Dial(${JOHN})
exten => john,1,Dial(${JOHN})

exten => 102,1,Dial(${JANE})
exten => jane,1,Dial(${JANE})

If we want to be able to allow people to dial through Asterisk and have Asterisk connect the caller to an outside resource, we need a way to match on any possible phone number that the caller might dial. Can you imagine how tedious it would be to manually write a dialplan with an extension for every possible number you could dial? Luckily, Asterisk has just the thing for situations like this: pattern matching. Pattern matching allows you to create one extension in your dialplan that matches many different numbers.

exten => _NXX,1,Playback(auth-thankyou)

exten => _555XXXX,1,Playback(digits/1)
exten => _55512XX,1,Playback(digits/2)

_NXXXXXX

_NXXNXXXXXX

_1NXXNXXXXXX

_011.

exten => _XXX,1,SayDigits(${EXTEN})

exten => _XXX,1,SayDigits(${EXTEN:1})

94169671111

Now that we’ve introduced pattern matching, we can go about the process of allowing users to make outbound calls. The first thing we’ll do is add a variable to the [globals] context to define which channel will be used for outbound calls:

[globals]
JOHN=Zap/1
JANE=SIP/Jane
OUTBOUNDTRUNK=Zap/4

Next, we will add contexts to our dialplan for outbound dialing.

You may be asking yourself at this point, “Why do we need separate contexts for outbound calls?” This is so that we can regulate and control which callers have permission to make outbound calls, and which types of outbound calls they are allowed to make.

To begin, let’s create a context for local calls. To be consistent with most traditional phone switches, we’ll put a 9 on the front of our patterns, so that users have to dial 9 before calling an outside number:

[outbound-local]
exten => _9NXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _9NXXXXXX,n,Congestion()
exten => _9NXXXXXX,n,Hangup()

ignorepat => 9

Let’s review what we’ve just done. We’ve added a global variable called OUTBOUNDTRUNK, which simply defines the channel we are using for outbound calls.^[79] We’ve also added a context for local outbound calls. In priority 1, we take the dialed extension, strip off the 9 with the ${EXTEN:1} syntax, and then attempt to dial that number on the channel signified by the variable OUTBOUNDTRUNK. If the call is successful, the caller is bridged with the outbound channel. If the call is unsuccessful (because either the channel is busy or the number can’t be dialed for some reason), the Congestion() application is called, which plays a “fast busy signal” (congestion tone) to let the caller know that the call was unsuccessful.

Before we go any further, let’s make sure our dialplan allows outbound emergency numbers:

[outbound-local]
exten => _9NXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _9NXXXXXX,n,Congestion()
exten => _9NXXXXXX,n,Hangup()

exten => 911,1,Dial(${OUTBOUNDTRUNK}/911)
exten => 9911,1,Dial(${OUTBOUNDTRUNK}/911) ; So that folks who dial “9” 
                                           ; first will also get through

Again, we’re assuming for the sake of these examples that we’re inside the United States or Canada. If you’re outside of this area, please replace 911 with the emergency services number in your particular location. This is something you never want to forget to put in your dialplan!

Next, let’s add a context for long-distance calls:

[outbound-long-distance]
exten => _91NXXNXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _91NXXNXXXXXX,n,Playtones(congestion)
exten => _91NXXNXXXXXX,n,Hangup()

Now that we have these two new contexts, how do we allow internal users to take advantage of them? We need a way for contexts to be able to use the functionality contained in other contexts.

Asterisk has a feature that enables us to use the extensions from one context within another context via the include directive. This is used to control access to different sections of the dialplan. We’ll use the include functionality to allow users in our [employees] context the ability to make outbound phone calls. But first, let’s cover the syntax.

The include statement takes the following form, where context is the name of the remote context we want to include in the current context:

include => context

When we include other contexts within our current context, we have to be mindful of the order in which we are including them. Asterisk will first try to match the dialed extension in the current context. If unsuccessful, it will then try the first included context (including any contexts included in that context), and then continue to the other included contexts in the order in which they were included.

As it sits, our current dialplan has two contexts for outbound calls, but there’s no way for people in the [employees] context to use them. Let’s remedy that by including the two outbound contexts in the [employees] context, like this:

[globals]
JOHN=Zap/1
JANE=SIP/Jane
OUTBOUNDTRUNK=Zap/4

[incoming]
exten => 123,1,Answer()
exten => 123,n,Background(enter-ext-of-person)
exten => 123,n,WaitExten()

exten => 1,1,Dial(${JOHN},10)
exten => 1,n,Playback(vm-nobodyavail)
exten => 1,n,Hangup()

exten => 2,1,Dial(${JANE},10)
exten => 2,n,Playback(vm-nobodyavail)
exten => 2,n,Hangup()

exten => i,1,Playback(pbx-invalid)
exten => i,n,Goto(incoming,123,1)

exten => t,1,Playback(vm-goodbye)
exten => t,n,Hangup()

[employees]
include => outbound-local
include => outbound-long-distance

exten => 101,1,Dial(${JOHN})
exten => john,1,Dial(${JOHN})
exten => 102,1,Dial(${JANE})
exten => jane,1,Dial(${JANE})

[outbound-local]
exten => _9NXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _9NXXXXXX,n,Congestion()
exten => _9NXXXXXX,n,Hangup()

exten => 911,1,Dial(${OUTBOUNDTRUNK}/911)
exten => 9911,1,Dial(${OUTBOUNDTRUNK}/911)

[outbound-long-distance]
exten => _91NXXNXXXXXX,1,Dial(${OUTBOUNDTRUNK}/${EXTEN:1})
exten => _91NXXNXXXXXX,n,Playtones(congestion)
exten => _91NXXNXXXXXX,n,Hangup()

These two include statements make it possible for callers in the [employees] context to make outbound calls. We should also note that for security’s sake you should always make sure that your [inbound] context never allows outbound dialing. (If by chance it did, people could dial into your system and then make outbound toll calls that would be charged to you!)