The dialplan in extensions.conf is organized into sections, called contexts. Contexts are the basic organizational unit within the dialplan, and as such, they keep different sections of the dialplan independent from each other. You can use contexts to separate out functionality and features, enforce security boundaries between the various parts of our dialplan, as well as to provide different classes of service to groups of users.
The syntax for a context is exactly the same as any other section heading in the configuration files, as explained in Sections and Settings. Simply place the context name in square brackets. For example, here we define an example context called 'users'.
Within each context, we can define one or more extensions. An extension is simply a named set of actions. Asterisk will perform each action, in sequence, when that extension number is dialed. The syntax for an extension is:
Let's look at an example extension.
In this case, the extension number is 6001, the priority number is 1, the application is Dial(), and the two parameters to the application are PJSIP/demo-alice and 20.
Within each extension, there must be one or more priorities. A priority is simply a sequence number. The first priority on an extension is executed first. When it finishes, the second priority is executed, and so forth.
Priority letter n
Priority numbers can also be simplified by using the letter n in place of the priority numbers greater than one. The letter n stands for next, and when Asterisk sees priority n it replaces it in memory with the previous priority number plus one. Note that you must still explicitly declare priority number one.
Consider the dialplan below.
It may not be immediately intuitive, but the "_.!" extension with the "n" priority will be executed after any of the preceding lines are executed.
You'll notice that each priority is calling a dialplan application (such as NoOp, or Verbose in the example above). That is how we tell Asterisk to "do something" with the channel that is executing dialplan. See the Applications section for more detail.
You can also assign a label (or alias) to a particular priority number by placing the label in parentheses directly after the priority number, as shown below. Labels make it easier to jump back to a particular location within the extension at a later time.
Here, we've assigned a label named repeat to the second priority.
Included in the Asterisk 1.6.2 branch (and later) there is a way to avoid having to repeat the extension name/number or pattern using the same => prefix.
Dialplan search order
The order of matching within a context is always exact extensions, pattern match extensions, include statements, and switch statements. Includes are always processed depth-first. So for example, if you would like a switch "A" to match before context "B", simply put switch "A" in an included context "C", where "C" is included in your original context before "B".
- Explicit extensions
- Pattern match extensions
Make sure to see the Pattern Matching page for a description of pattern matching order.
One thing that wasn't obvious from reading this page is Asterisk doesn't find an extension or pattern and stick to it while executing priorities, but rather seeks the best matching extension each time it executes a priority. So is assuming you always enter at priority 1, this dialplan:
is equivalent to:
It is mentioned in the section on includes, but it applies here too.
No one would deliberately write a dial plan like that of course, but very easy to end up in a similar situation by mistake:
Great point. I'll modify this page to mention this.
Just thinking out loud here, but this page makes reference to patterns - without telling the reader that that concept is covered later (Pattern Matching). The first usage above:
could have a note following?
Dialplan Pattern Matching requires all patterns to start with a "_" for more information see the section on Pattern Matching?