2.2. Extension

Individual entries in extensions.conf are called extensions. Extensions are interpreted by Asterisk every time a call is initiated, but extensions.conf is only read into Asterisk at start time.^[9]You can also refresh the dialplan during operation from the CLI (Command Line Interface) by entering the command

reload
    now

(which reloads all the configurations) or extensions reload (which reloads only the dialplan).

Syntax

An extension consists of the following parts:

Extension (Name or number)
Priority (a kind of program line number)
Application - an instruction which tells Asterisk what it should do with the call.

exten => Extension,Priority,Application

e.g.

exten => 123,1,Answer()

Fundamental Applications

In order to build the dialplan examples in this chapter, we need the following basic applications^[10](all these are described in greater detail in Appendix B, Applications in the dialplan):

Answer()
The Answer() application does just that - it answers a call. When a channel rings, Answer() tells Asterisk to "lift the virtual receiver." (See also Section B.9, “Answer()”.)
Hangup()
Hangup() is the opposite of Answer(). An active connection is terminated, and Asterisk "hangs up" the virtual receiver (see also Section B.52, “Hangup()”).
Playback(soundfile)
This tells Asterisk to play a specified sound file. By default, it plays files found in /var/lib/asterisk/sounds/, but you can also specify another source directory. No file extension is specified because the directory may contain the same sound in different formats. Asterisk will select the most appropriate format -- more on that later (see also Section B.84, “Playback()”).
Wait(number)
Wait() defines a pause; Number indicates the number of seconds to pause (see also Section B.134, “Wait()”).
NoOp(string)
This application does nothing. "NoOp" means "no operation." It is useful, however, when you are trying to troubleshoot a problem with your dialplan. When NoOp(string) is executed, Asterisk prints string on the CLI, though only if the verbosity level is set to 3 (you can do this easily by entering the command set verbose 3 in the CLI). (See also Section B.74, “NoOp()”.)
VoiceMail(mailbox,u)
Lets the caller leave a voice message in the mailbox specified (see also Section B.132, “VoiceMail()”).
VoiceMailMain()
Provides access to the voicemail system. The mailbox owner will use this to retrieve her messages (see also Section B.133, “VoiceMailMain()”).

Priority

A typical extension is composed of a multiple entries. Each entry has a priority so that Asterisk knows in what order it should execute the entries. If you have ever worked with early versions of BASIC, you might be familiar with line numbers; priorities work in much the same way, but with one important distinction. They are always executed in numerical order from smallest to largest, but there can be no gaps! If Asterisk executes an entry of priority n, then it will look for the next entry at n + 1. If it cannot find an entry at n + 1, it stops executing without displaying an error in the CLI.

A "Hello World!" example

The following extension will be invoked when a phone with the default context widgets dials 8888. Asterisk picks up the line, plays the hello-world sound file (which is installed with Asterisk) and hangs up.

[widgets]
exten => 8888,1,Answer()
exten => 8888,2,Playback(hello-world)
exten => 8888,3,Hangup()

n priority

To make it easier to work with priorities, Asterisk versions from 1.2 onward have supported the n priority. The n priority is like automatic line numbering; when Asterisk is running through the dialplan and encounters an entry with priority n, it simply executes it as though it were equivalent to the previous priority, plus 1. This is useful when you have extensions with many entries and you need to add or remove an entry, because it saves you having to renumber the entire extension. The example below illustrates what we mean. A standard extension would look like this:

exten => 1234,1,Answer()
exten => 1234,2,Wait(2)
exten => 1234,3,Playback(hello-world)
exten => 1234,4,Wait(2)
exten => 1234,5,Hangup()

You can define the same extension with the n priority:

exten => 1234,1,Answer()
exten => 1234,n,Wait(2)
exten => 1234,n,Play(hello-world)
exten => 1234,n,Wait(2)
exten => 1234,n,Hangup()

You can start using the n priority at any point in the extension, as long as all the subsequent entries also use it:

exten => 1234,1,Answer()
exten => 1234,2,Wait(2)
exten => 1234,3,Play(hello-world)
exten => 1234,n,Wait(2)
exten => 1234,n,Hangup()

^[9]An exception is the Asterisk RealTime Architecture (ARA). In an ARA system, the dialplan is stored in a database (e.g. MySQL) and read into Asterisk for each call, not simply when Asterisk is started. This allows an administrator to make dialplan changes on a running Asterisk server which take effect immediately. Nevertheless, this approach is not without significant disadvantages. You can learn more about realtime Asterisk at http://www.voip-info.org/wiki/view/Asterisk+RealTime .

^[10]A typical "chicken or egg" problem. One can only understand an application if one understands the dialplan, and vice versa.