The heart of Asterisk is the dialplan; it tells Asterisk what to actually do when it receives a call or when someone dials an extension. And speaking of extensions, let's clear up something before we go any further.
An "extension" is an arbitrary set of digits (or even letters) which trigger something to happen inside Asterisk. While that something could be to ring the phone sitting on your desk, it could just as easily play back a menu of options as an IVR, place you into a conference room, or send an instant message to someone via XMPP. An extension and a device (a phone) are in no way tied to each other or even related -- unless you make that association between them, via the dialplan.
Let's construct our first dialplan so our TestPhone-A peer can do something. Using your favorite text editor, create the file /etc/asterisk/extensions.conf with the following:
Very basic! Let's break it down.
[internal] starts a new context in the dialplan. Contexts are like containers for extensions; they serve to separate extensions from each other in the dialplan. In sip.conf we configured our TestPhone-A peer with context=internal, so any calls it makes will wind up in the [internal] context of the dialplan.
exten => signifies this line is an extension entry, which follows a specific syntax:
Per the above, 555 is the extension we've created -- the thing that you dial. It has a priority of 1, which is a sequential number that controls the order of execution when an extension has multiple steps. The priority for the first step of a given extension should (almost) always be 1. We'll talk more about priorities shortly. Finally, Playback is the application to execute when the extension is dialed, and we pass it an argument of hello-world which is the name of one of the core sound files installed with Asterisk.
In order to try this extension out, first we need to reload the dialplan into memory. On the Asterisk console, type:
This should result in something similar to:
Now let's try it. Dial 555 on the softphone and place the call. You should hear a short "Hello, world!" and the call will terminate.
See? Not so tough Let's expand our test extension a little bit, and test two-way audio. Edit /etc/asterisk/extensions.conf again, and change it to read:
As you can see, we now have 4 steps for extension 555, each with an ascending priority. Upon dialing extension 555, priorty 1 would execute (the Playback of 'hello-world'), followed by priority 2 (another Playback but of 'echo-test'), and so on. You could re-arrange the order of the four lines in the config, but they would still execute in their numbered priority order.
Do another dialplan reload on the console, and dial 555 on your phone. This time you'll hear the "Hello, World!" followed by a quick instruction that everything you say will be echoed back. Assuming you have a headset of some sort and your softphone is configured correctly to use it, you should be able to blab a bit into your mic and hear yourself echoed back on a short delay. Once you get bored with that, press the # key on your phone to end the Echo application, at which point you'll hear the summary sound, and the call will end.
This is great, but what happens if you want to add an additional application or two into the middle of the extension? Rather than having to manually renumber all of the priorities following the one(s) you added, Asterisk lets us use some shorthand to make things a bit simpler. Without adding anything new right now, let's just modify our existing extension to allow for future changes:
We still have to specify priority 1 to signify the entry point for the extension, but we've eliminated the subsequent priorities and replaced them with 'n' which means "next." Now, Asterisk will automatically assign ascending sequential priorities in place of 'n' (at which point the order of the lines in extensions.conf does matter.) Now you can add other priorities in and around your existing ones without having to go insane constantly renumbering everything manually.
Now let's say we want to change our test extension from 555 to 777 instead. We have a similar issue in having to modify all 4 lines to change the extension number -- which in this case isn't a lot, but think if you had a more elaborate extension of 20 or 30 steps. There's one more shortcut we can use:
As you can see, the first exten line looks the same, except for having changed the extension from 555 to 777. Subsequent lines however are using the same keyword, which means "the same extension as before." We then leave out the extension number, and begin with the priority, again still using our previously learned 'n' shortcut as well. Now if we ever have to change this extension number again, we only need to modify one line.
Issue the dialplan reload command on the console again, then give extension 777 a call to see that everything is still working.
Now that we've got some dialplan basics down, what else can we do? The dialplan applications are the workers of the dialplan. So far, we've only used two -- Playback and Echo -- but there are dozens more. For a list of every application offered by all the modules currently loaded into Asterisk, on the Asterisk console type:
You can get more information on what an application does and its syntax of usage by typing:
where is the name of the application.
In the next section, we'll talk about the ever-important Dial application which is used to place calls to other devices/peers.