Saruman!: /* What is a dialplan? */ reworked

2008-10-19T21:09:47Z

What is a dialplan?: reworked

← Older revision		Revision as of 21:09, 19 October 2008
Line 2:		Line 2:
	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 :-)		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.		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.

	~~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".		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.

	~~So, we~~ can observe that calls come in three varieties:		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"		* 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".		* 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.		* 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 ~~two~~ 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....		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.

	So, when you have a PBX like Asterisk, you have to instruct it how to handle calls - be it incoming, outgoing or passing through. In all cases, the initiating party has or will enter information by dialing, upon which the PBX must act. The recipe for these actions is thus called a "dialplan".		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?

	~~So when WE have to~~ create a dialplan for our Asterisk PBX, what must we do? Not much, only to create little recipes for each perceivable call that Asterisk must handle for us. As such, creating a ~~dialplan~~ 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=		=Dialplan elements=

Saruman!: Page started

2008-10-17T14:17:41Z

Page started

New page

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

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

So, 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 two 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, when you have a PBX like Asterisk, you have to instruct it how to handle calls - be it incoming, outgoing or passing through. In all cases, the initiating party has or will enter information by dialing, upon which the PBX must act. The recipe for these actions is thus called a "dialplan".

So when WE have to create a dialplan for our Asterisk PBX, what must we do? Not much, only to create little recipes for each perceivable call that Asterisk must handle for us. As such, creating a dialplan 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

=Applications=

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

= Asterisk dialplans - handling outgoing calls =

= Where to go from here=

Dialplan theory - Revision history

Saruman!: /* What is a dialplan? */ reworked

Saruman!: Page started