Dial Plan

Starting with a Basic Dialplan

Dialplans define the exact parameters of how a call is processed. When someone calls you, do you want the call to go to your extension first and then your voice mail? Or, do you want the caller to receive a recording asking him to enter an extension first? You can also establish an order in which calls reach you. You can build a dialplan that attempts to reach you on your office line, your cellphone, and the VoIP softphone on your computer, and then send the call to your voice mail . . . now that's being connected!

You build the dialplans in the extensions.conf file that is usually located in the following directory:

/etc/asterisk

The extensions.conf file is one long string of dialplans, separated only by the individual contexts within brackets. All configurations beneath one context and above another apply to the upper context.

This is an example of a simple dialplan:

[incoming]

exten => 2565551212,1,Answer()

 Remember   This simple dialplan doesn't look like much now, but from these humble beginnings, great things are made.

Figure 5-1 identifies the four elements of a basic dialplan. Each element of the dialplan acts as shorthand for a set of rules, processes, or locations that are applied to all calls that fall within the dialplan parameters. The dialplan in Figure 5-1 is for an incoming call that is being directed to phone number 9495551212. This scheme doesn't play a greeting to the caller, nor does it offer voice mail or a list of extensions; it simply sends the caller to the extension for phone number 949-555-1212, where the caller remains until someone picks up the line or he hangs up the phone.

 

 Understanding the context

[incoming]

exten =>9495551212,1,Answer()

The context is the first line of code and it correlates to the context you defined when configuring the individual VoIP, analog, digital, and/or IAX devices. (If you're wondering how to program the context to these devices, check out Chapter 4.)

 

 

When a call comes in to the server, Asterisk looks for the device sending the call (SIP/0001, for instance) for registration. If Asterisk can't find the registration, it looks for a default context for the channel type (VoIP, analog, or IAX connection, for example).

You should group devices with the same functions and that belong to the same financial entity into contexts for ease of programming. The contexts we cover in this chapter are as follows:

§                    [incoming]: Use this context to configure Asterisk for inbound calls.

§                    [internal]: Use this context to configure Asterisk for calls that are transferred between two endpoints within the Asterisk network.

§                    [outgoing]: This context is for outbound calls through analog, digital,VoIP, or wireless connections.

§                    [globals]: This is a special context in which you build dialplan universals that you apply to all contexts. Your home area code would be listed here, for example, and used as a telecom point of reference for all local calls.

 

 

These contexts are actually configuration contexts assigned to devices connecting to the Asterisk system. The device parameters and abilities are linked to the dialplan, which allows you to process the incoming and outgoing calls from the device. The [globals] context is the only special context because the relationships established in this context are used in every other context in your dialplan. These relationships are generally coding expedients whereby a common name is used to replace a complex device ID, such as

TRUNK=SIP/111.222.333.444/

This programming shorthand, called a variable, allows you to write the word TRUNK instead of typing the VoIP port and IP address of SIP/111.222.333.444.

 

 

 

 Remember   You don't have to use all these specific context names. Only the [globals] context is preset in Asterisk. You can use any naming convention you want for the other contexts. Context names can include letters, numbers, and hyphens. You can make your life easier if you do name your dialplans something descriptive. Context names such as [inbound], [outbound], [longdistance], [local], [international], and [extensiononly] are easier to work with, and you can more easily remember their purpose.

 

 

 

 Warning   Okay, you can also use underscores in context names, but they can be problematic. Underscores are also used in other aspects of Asterisk, and mistyping a context with an underscore can complicate your dialplan. We recommend not using them for contexts; stick with hyphens instead.

 Tip   If you're using Asterisk for internal company use as well as for external customers, create context names that reflect the different entities. For instance, you can split the [incoming] context into the following:

[incoming-mine]

[incoming-customer]

Splitting contexts reduces confusion and allows you to handle internal calls differently. If you dial 0 in your office, you probably want to speak to your receptionist. If your customer has the option of dialing 0, you can have him sent to your customer service queue instead.

Asterisk does have one context that isn't really a context as we understand them in the dialplan. The [general] context is located in the extensions.conf file, but is actually a general holding place for information in the extensions.conf file and not a traditional context like [incoming] or [outgoing]. It holds information that pertains to all contexts, like the autofallthrough option that acts like a security net to handle calls that may have inadvertently have no real destination due to a gap in your dialplan programming

 

Identifying extensions

[incoming]

exten =>9495551212,1,Answer()

In the most traditional sense, extensions refer to the number you dial to call someone within your company. Asterisk takes extensions to a whole new level. It views not only the physical phone on a desk or channel driver (SIP/ZAP, IAX) as an extension, but it also provides intelligence to the extension allowing it to play a message while sending the call to various places, in this order:

1.          The phone on your desk.

2.          Your cellphone, if you don't answer your desk phone in a preset number of seconds.

3.          Your voice mail, if you don't answer your cellphone.

 

Remember   The new era of VoIP also expands how you identify extensions. You are no longer restricted to simply using numbers to identify Asterisk extensions. You can use e-mail addresses as valid extension names if you build them into the system, as well as employee names (for use in dial-by-name directories).

The extensions you build can be as complex and dynamic as you need. The automated systems that prompt you for your essential and nonessential information when you call customer service are one example of the intelligence you can build into an extension, or a set of extensions. Every response the caller keys into the system either sends her to another extension within the system in a different context, or simply further along in the dialplan. As long as you remember that an extension can be a virtual destination within a device used to qualify responses of the caller, and not just a phone on a desk, you are ready to unlock the potential of Asterisk extensions.

 

Technical Stuff   Devices are physical hardware and can contain and facilitate extensions, but aren't extensions themselves. The only way you can reach a device is through an extension, which must be dialed to route a call to a specific device. The rub is the fact that extensions are not defined on a one-for-one basis with devices.

Extensions can have a multitude of possible destinations, of which only some are devices. Samples of nondevices into which an extension can terminate are as follows:

 

§                    Applications

§                    Direct voice mail servers

§                    Calling card applications

§                    Conference rooms

§                    Fax servers

 

If you want to call the physical analog phone in your customer service department from the VoIP softphone on your desk, you simply dial the Asterisk internal extension that directs your call to a device connected to the Zaptel card, and the remote phone rings. If you want to call Papua, New Guinea, over your outbound VoIP carrier, your Asterisk actually connects your call to an extension that terminates in an outbound device, such as SIP/1.

Extensions are identified in the extensions.conf file with the following line of code:

exten => 133,1,Answer()

The exten => part identifies the extension, and the number or letters after the => indicate the specific extension you're defining. In this example, 133 is the extension.

Just like the context names, you can design most of your own extension names. The default extensions with Asterisk are as follows:

§                    exten => s: This extension is the start extension. It receives calls and plays an automated greeting prompt as long as it is configured in your device configuration.

 

§                    exten => i: This is the invalid extension. If you prompt a caller to input a 3-digit extension number and he presses three digits that aren't listed as a legitimate extension, he's sent to exten=> i.

 

 

§                    exten => t: This is the timeout extension. You set time limits on some extensions in your dialplan, and if the caller doesn't choose a prompt within your time limit, the call is sent to the exten => t extension.

 

§                    exten => T: This is an absolute timeout identifying the maximum duration Asterisk allows for an active phone call before it's sent to the T extension or hung up. Carriers use a feature like this to prevent calls that have failed to completely hang up (called a hung call) from remaining active in their switch.

 

 

§                    exten => #: This functions like a command more than an extension.It's normally used to hang up a call in a dialplan with many layers of recordings prompting you to "press 1" for this and "press 2" for that. These Interactive Voice Response (IVR) systems use the extension as an expedient to disconnect a call, in spite of it not being a traditional "pre-defined" extension destination.

 Remember   These extensions are case-sensitive. Confusing a t extension with a T extension could result in calls being disconnected that simply can't find their extension. Pay attention when using them in your dialplan to avoid headaches later.

These extensions allow you to build a solid dialplan. Asterisk does have a safety net to prevent calls from being sent to limbo and left hanging. The autofallthrough option in the [general] section of the extension configuration prevents forgotten calls from lingering in the system.

The default extensions in the previous bulleted list are predefined destinations in Asterisk. You must still define them in your context so that Asterisk knows what you want it to do when someone must be routed to the extension. Do you want to hang up on people that exceed your timeout limit, or send them back to the main recorded greeting for a second chance? Failing to program for these little eventualities can cause the call to congest the system and automatically be hung up.

Warning   It is very important to identify and process calls that time out. Someone could call you on Friday at 5:00 p.m. on your toll-free number, connect to your phone system, and fail to hang up correctly (honest, it happens). In this case, you would have a billable phone call that lasts until Monday morning, when the person calling you realizes his phone line has no dial tone because it is still connected to your system.

 

Utilizing priorities

[incoming]

exten =>9495551212,1,Answer()

The second parameter of the extension code is the priority; it controls the sequence of events in the dialplan. Each priority contains a call to a single application in Asterisk. It can also forward information to that application, if necessary, to provide additional features to the call. The priorities increase in value as each step in the dialplan is executed. A dialplan with several steps would look like this:

exten => 133,1,EatPizza()

exten => 133,2,DrinkSoda()

exten => 133,3,WathchTV()

exten => 133,4,TakeNap()

This is, of course, a bogus Asterisk extension with non-existent applications, but it does demonstrate how the priority increases sequentially as progressive actions are taken in sequence.

Tip   If you don't want to remember the last priority you used in an extension, you can replace the priority number with n (which is referred to as an unnumbered priority). The n represents the previous priority plus 1. You write an unnumbered priority in a dialplan like the following:

exten => 133,1,EatPizza()

exten => 133,n,DrinkSoda()

exten => 133,n,WathchTV()

exten => 133,n,TakeNap()

Engaging an application

[Incoming]

exten =>9495551212,1,Answer()

The application is the last element of code in the extension line. Even though it is only one element, it is actually constructed of two distinct sections: the application and the argument:

 

§                    Application: The application represents the action being taken at this step (priority) of the extension. In Figure 5-2, the application being used is dial. The first channel on the Zap card from extension 9495551212 is being dialed.

 

Figure 5-2: An application schematic.

Many different applications are available with Asterisk; answer, hangup, background, dial, and Goto are the most important to know, so we discuss those in the following sections.

§                    Argument: The argument includes three unique parameters, separated by commas. In Figure 5-2 the arguments are as follows:

 

o                           Parameter 1: The syntax of the first parameter of the code specifies the channel technology/resource. Our example identifies the channel technology as ZAP, indicating the Zapata time-division multiplexing (TDM) (analog) card. The resource, listed after the backslash is 1, indicating port 1 as the channel device using this application. It could have just as easily been a device with a VoIP port, a digital card, or a Wi-Fi port.

o                           Parameter 2: The 20 identifies that you're requiring Asterisk to maintain this application for 20 seconds. If the dialed device answers the call before the 20 seconds are up, the call is bridged through it. If the dialed device doesn't answer in 20 seconds, the extension proceeds to the next priority. You can configure it to send the call to voice mail, return to the main operator for the system, or disconnect the call. Each of these available fallback destinations is an additional priority and is located in the current context, or in another context.

o                           Parameter 3: The r parameter allows the person originating the call to hear the phone ringing.

 

 

 

 

 

 Remember   You can omit any of the parameters within the argument if you don't want to restrict the call or enable the ringing. An extension without a specified duration looks like this:

exten=> 9495551212,1,Dial(Zap/1,,r)

If you want to keep the 20-second time limit on the application, but don't want to the person making the call to hear a ringing tone, the code is as follows:

exten=> 9495551212,1,Dial(Zap/1,20)

Answering calls

The answer() application doesn't use arguments; because the parentheses are always blank, you can omit them if you want. The answer() application receives a call from the outside world and sends a connect signal back through the device that originated the call.

 Technical Stuff   The parentheses in applications aren't essential if they don't hold any information. You can even replace the parentheses with a single comma between the application and the arguments. For example, you can write the application Dial(Zap/1,,r) as Dial,Zap/1,,r.

The Asterisk environment is very dynamic, so don't be linked to the idea that whenever we mention a call that it is coming from someplace beyond your network. A wealth of calls is flying through Asterisk networks from SIP phones to voice mail, or analog phones linking up on a teleconference. A whole world of traffic is rolling through your Asterisk phone; this traffic is referred to as calls.

 Remember   The connect signal sent back to an incoming carrier happens regardless of the device that delivers the incoming call. The answer() application also receives inbound VoIP calls or internal calls into your Asterisk phone. The answer() application is only necessary when immediately connecting you to a system that plays a message, such as "Please enter the extension of the person you wish to dial," before connecting you to a second device.

The application doesn't play a recorded message or anything else, aside from establishing a connection on the call. The code for a call sent to a default start extension (s) and answered appears like this in a dialplan:

exten=> s,1,Answer()

exten=> s,2,Background(enter-ext-of-person)

 Remember   Only use the answer() application when it is inside your IVR system (you know, the thing asking you for the extension you wish to dial). You don't have to use this application if you are using the dial application directly because it automatically answers the call when the destination channel picks up the call.

Hanging up calls

The hangup is the logical conclusion to every call. As such, this command doesn't appear with a priority of 1. Common courtesy dictates that you at least answer the phone before hanging up on someone. The code for a call to be answered and then hung up is as follows:

exten=> s,1,Answer()

exten=> s,2,Hangup()

Responding to touch tones

We have all called a large company and received the voice-mail prompt of "Please enter your party's 3-digit extension." You also notice that if you dial the 3-digit extension while the recording is playing, it stops the recording and immediately sends you to the extension you dialed. Asterisk has the same feature, and because it is waiting in the background for you to dial the extension, the application is called background(). It looks like this in the dialplan:

exten=> s,1,Answer()

exten=> s,2,Background(enter-ext-of-person)

Dialing the new-fashioned way

Every inbound call includes at least two segments. The [incoming] context receives the call into the Asterisk, but after it has arrived there, the call must still be sent to a desired channel device, voice mailbox, or external carrier. The dial() application allows you to forward the call to its next destination. The following example demonstrates a simple dialplan using dial():

[internal]

  exten => 0,1,Dial(Zap/1,20,r)

This code allows internal customers to dial 0 and receive the operator that is connected to the Zap/1 card.

Moving with a Goto

The Goto application allows you to do wonderful things because it allows you to send a call from one context to another. A simple dialplan that allows an incoming customer call to reach your internal operator looks like the following:

[internal]

  exten => 0,1,Dial(Zap/1,20,r)

[incoming-customers]

  exten => 7,1,Goto(internal,0,1)

 Tip   If you want a complete list of the applications available on your Asterisk, you can type the show applications command in the Asterisk command-line interface (CLI). When you find an application you are interested in, you can read a detailed document on the application by querying Asterisk for it with the following command:

Show application name

Simply replace name with the name of the application you are interested in, and a document appears with all the application's pertinent information. You can also find the documentation by scanning the /docs/ directory of the Asterisk source code.

For a general list of applications available on Asterisk, check out the following Web site:

www.voip-info.org/wiki-Asterisk+-+documentation+of+application+commands

This simple bit of code shows how the call in the [incoming-customers] context, when pressing extension 7, is routed to the new [internal] context, extension 0 and priority 1. The [internal] context identifies where extension 0 is sent.