Dialplan theory

What is a dialplan?

When first starting with Asterisk, you might be intimidated by the sheer complexity of the dialplan. But we find it is actually very simple - so simple that it's getting difficult, as it were :-)

Think of it this way: you've got a PBX, and that can do just about one thing: handle calls. And what is a call? Two endpoints, connected together to enable communication (voice communication, we're inclined to think). So Asterisk must handle calls. And we must tell it how - using something that's called a "dialplan". That's all there is to it, really.

Now, for any call, there's an element of "dialing", where the initiating endpoint feeds information into the telephony system about who he/she wants to reach. This initiates the call, but the call is not actually set up until the other side "picks up" - either because the target endpoint has accepted the call, or because a PBX on the target endpoint site has picked up the phone. In the latter case, it might be necessary to feed additional info into the call, like in answering a "voice menu". From this element of dialing, the call handling configuration file derives its name, but it might help you to keep in mind that the dial plan is actually handling calls, not just dialing.

We can observe that calls come in three varieties:

• incoming, where one side of the call is already totally set up to communicate. This is the case when someone "outside" your premises tries to contact someone "inside"
• outgoing, where the PBX must also make a connection, but the receiving party is not on a channel attached to the PBX, but "somewhere out there".
• passing through, where the PBX accepts an incoming connection, but then dials out to reach the intended recipient.

However, the more you think about these three kinds of calls, the more you'll see that they're almost the same. The most notable difference is in who is paying for the call.... So all of these calls go through the dial plan, and we must cater for all use cases that these calls can follow.

When we create a dialplan for our Asterisk PBX, what exactly must we do? Not much, only to create little recipes for each perceivable call that Asterisk must handle for us. As such, creating a dial plan is much like programming - only the language that we have to program in is a bit clumsy and limited (at least with Asterisk 1.4). So we have to learn this call programming stuff - and how hard can that be?

Dialplan elements

Any dialplan contains the following building blocks:

• Applications
• Extensions
• Contexts

Extensions

An extension can be one of two types: a literal or a pattern.

A literal extension can be a number, like 123, and it can also contain the standard symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension.

A single extension can also match patterns. In the extensions.conf file, an extension name is a pattern if it starts with the underscore symbol (_). In an extension pattern, the following characters have special meanings:

X          matches any digit from 0-9
Z          matches any digit from 1-9
N          matches any digit from 2-9
[1237-9]   matches any digit or letter in the brackets
           (in this example, 1,2,3,7,8,9)
.          wildcard, matches one or more characters
!          wildcard, matches zero or more characters immediately           

Asterisk uses some extension names for special purposes:

   * i : Invalid
   * s : Start
   * h : Hangup
   * t : Timeout
   * T : AbsoluteTimeout
   * a : Asterisk extension
   * o : Operator

Asterisk dialplans - handling incoming calls

What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel.