VoIPowering Your Office With Asterisk: Mastering Dialplan Basics
The dialplan sets up the basic nuts and bolts of how calls are processed. To build one, you need to understand configuration files, today's mission.
Last week we were introduced to "real Asterisk." Today we're going to get up close and personal, and poke around under the hood. The heart of Asterisk is the dialplan, and the key to Asterisk happiness is understanding how to create one. The dialplan controls how all calls are handled, both inbound and outbound.
Asterisk configuration files
Asterisk has more configuration files than you can shake a stick at, but we're going to focus on the fundamental ones:
extensions.conf is for configuring dialplans. sip.conf and iax.conf are for setting up incoming and outbound channels. SIP is probably the most popular VoIP protocol, and virtually all IP phones support it. IAX is used primarily for VoIP servers to talk to each other, then the signal can be converted to SIP for phones that don't support IAX. We'll talk more about these next week.
A dialplan has four elements:
The word "extensions" is a bit unfortunate, because it sounds like plain old telephone extensions. But Asterisk extensions are sturdy little workhorses that do all kinds of things. Extension syntax looks like this:
exten => name,priority,application( )
A real-life extension looks like this:
exten => 555,1,Answer( )
The extension name is 555. Names can be either words or numbers. This extension is simple: when someone dials 555, it has the highest priority, and the action is to answer. Usually multiple extensions are required to handle a single call; these are called contexts.
Named groups of extensions are called contexts. Each context is a separate unit, like a function in a software program, and does not interact with other contexts unless it is configured to do so. We used contexts in VoIPowering Your Office with Asterisk: Getting Free Long Distance, Part 2:
exten => 15035551212,1,Answer( )
exten => 15035551212,n(call),Dial(SIP/200)
exten => 15035551212,n,Voicemail(u200)
exten => 15035551212,n,Hangup( )
There are four actions to be taken in this example. The first is to answer; "n" means go to the "next" action, which is to dial 200 and use the SIP protocol. The next action is to go to voicemail. After all that, hangup.
The second line demonstrates an interesting and powerful feature, the Dial command. The Dial command includes a boatload of commands and options. You could also include a login and password, an IP address, or an entirely different phone number.
n(call) shows how to use a text label. This is just a comment to help you remember what the command does. Text labels are enclosed in parentheses and follow priorities. It's a bit confusing because command options, which follow applications, are also enclosed in parentheses. Text labels are optional; you don't have to use them.
You must always specify a number 1 priority; this is the first command Asterisk follows when processing a call. It doesn't have to be in any particular order, because Asterisk goes by the priority number. Additional extensions can either be numbered in sequence, or just use "n" and list them in sequence. With numbered priorities, our dundi-priv-local context could look like this:
exten => 15035551212,4,Hangup( )
exten => 15035551212,2(call),Dial(SIP/200)
exten => 15035551212,3,Voicemail(u200)
exten => 15035551212,1,Answer( )
I don't know why anyone would want to do this, but it can be done. If you are numbering your priorities and accidentally skip one, Asterisk will stop there and not continue.
There are meelyuns of applications included in Asterisk. Well, more like dozens, which you will find in the "Application Reference" in "Asterisk: The Future of Telephony."
Playback is a fun one, and useful for testing. It plays a sound file:
exten => 555,n,Playback(ima_lumberjack_and_Im_OK)
Asterisk comes with a bunch of sound files in the sounds/ directory. To use this in testing, use it with the s (start) extension. This is a special built-in extension for handling calls without specific destinations:
exten => s,1,Answer( )
exten => s,n,Playback(ima_lumberjack_and_Im_OK)
exten => s,n,Hangup( )
You could use this in place of the dundi-priv-local context in VoIPowering Your Office with Asterisk: Getting Free Long Distance, Part 2. It doesn't let you do a two-way conversation, it just verifies that your configuration works.
It's crucial to understand dialplans, so your homework is to study your sample configuration files. Next week we'll go in-depth on the other two key parts of having a functioning Asterisk VoIP system, the sip.conf and iax.conf files.
Asterisk Documentation Project has a downloadable free copy of the book "Asterisk: The Future of Telephony." It can also be purchased at the usual outlets. (Hint: supporting authors financially is a splendid thing to do.) This book is an essential reference, and contains all the Asterisk commands and configuration options.