Dialplans are broken into sections called contexts . Contexts are named groups of extensions, that serve several purposes.

Contexts keep different parts of the dialplan from interacting with one another. An extension that is defined in one context is completely isolated from extensions in any another context, unless interaction is specifically allowed. (We'll cover how to allow interaction between contexts near the end of the chapter.)

As a simple example, let's imagine we have two companies sharing an Asterisk server. If we place each company's voice menu in its own context, they are effectively separated from each other. This allows us to independently define what happens when, say, extension 0 is dialed: people pressing 0 at Company A's voice menu will get Company A's receptionist, and callers pressing 0 at Company B's voice menu will get Company B's receptionist. (This example assumes, of course, that we've told Asterisk to transfer the calls to the receptionists when callers press 0.)

Contexts are denoted by placing the name of the context inside square brackets ([ ]). The name can be made up of the letters A through Z (upper- and lowercase), the numbers 0 through 9, and the hyphen and underscore.^[73] For example, a context for incoming calls looks like this:

    [incoming]

	Note
	Context names have a maximum length of 79 characters (80 characters - 1 terminating null)

All of the instructions placed after a context definition are part of that context, until the next context is defined. At the beginning of the dialplan, there are two special contexts named [general] and [globals]. The [general] section contains a list of general dialplan settings (which you'll probably never have to worry about), and we will discuss the [globals] context later in this chapter; for now it's just important to know that these two contexts are special. As long as you avoid the names [general] and [globals] , you may name your contexts anything you like.

When you define a channel (which is how you connect things to the system), one of the parameters that is defined in the channel definition, is the context. In other words, the context is the point in the dial plan where connections from that channel will begin.

Another important use of contexts (perhaps the most important ) is to provide security. By using contexts correctly, you can give certain callers access to features (such as long-distance calling) that aren't made available to others. If you don't design your dialplan carefully, you may inadvertently allow others to fraudulently use your system. Please keep this in mind as you build your Asterisk system.

Warning

The doc/ subdirectory of the Asterisk source code contains a very important file named security.txt, which outlines several steps you should take to keep your Asterisk system secure. It is vitally important that you read and understand this file. If you ignore the security precautions outlined there, you may end up allowing anyone and everyone to make long-distance or toll calls at your expense! If you don't take the security of your Asterisk system seriously, you may end up paying—literally! Please take the time and effort to secure your system from toll fraud.

In the world of telecommuniations, the word extension usually refers to a numeric identifier given to a line that rings a particular phone. In Asterisk, however, an extension is far more powerful, as it defines a unique series of steps (each step containing an application) that Asterisk will take that call through. Within each context, we can define as many (or few) extensions as required. When a particular extension is triggered (by an incoming call or by digits being dialed on a channel), Asterisk will follow the steps defined for that extension. It is the extensions, therefore, that specify what happens to calls as they make their way through the dialplan. Although extensions can certainly be used to specify phone extensions in the traditional sense (i.e., extension 153 will cause the SIP telephone set on John's desk to ring), in an Asterisk dial plan, they can be used for much more.

The syntax for an extension is the word exten, followed by an arrow formed by the equals sign and the greater-than sign, like this:

    exten =>

This is followed by the name (or number) of the extension. When dealing with traditional telephone systems, we tend to think of extensions as the numbers you would dial to make another phone ring. In Asterisk, you get a whole lot more—for example, extension names can be any combination of numbers and letters. Over the course of this chapter and the next, we'll use both numeric and alphanumeric extensions.

	Tip
	Assigning names to extensions may seem like a revolutionary concept, but when you realize that many Voice-over-IP transports support (or even actively encourage) dialing by name or email address instead of only dialing by number, it makes perfect sense. This is one of the features that make Asterisk so flexible and powerful.

A complete extension is composed of three components:

These three components are separated by commas, like this:

    exten => name,priority,application()

Here's a simple example of what a real extension might look like:

    exten => 123,1,Answer()

In this example, the extension name is 123, the priority is 1, and the application is Answer(). Now, let's move ahead and explain priorities and applications.

Each extension can have multiple steps, called priorities. Each priority is numbered sequentially, starting with 1, and executes one specific application. As an example, the following extension would answer the phone (in priority number 1), and then hang it up (in priority number 2):

    exten => 123,1,Answer()
    exten => 123,2,Hangup()

Don't worry if you don't understand what Answer() and Hangup() are—we'll cover them shortly. The key point to remember here is that for a particular extension, Asterisk follows the priorities in order.

    exten => 123,1,Answer()
    exten => 123,n,do something
    exten => 123,n,do something else
    exten => 123,n,do one last thing
    exten => 123,n,Hangup()

5.1.3.2. Priority Labels

Starting with Asterisk version 1.2 and higher, common practice is to assign text labels to priorities. This is to ensure that you can refer to a priority by something other than it's number, which probably isn't known, given that dialplans now generally use unnumbered priorities. To assign a text label to a priority, simply add the label inside parentheses after the priority, like this:

    exten => 123,n(label),application()

	Warning
	A very common mistake when writing labels is to insert a comma between the 'n' and the '(', like this: exten => 123,n,(label),application() ;<-- THIS IS NOT GOING TO WORK This mistake will break that part of your dialplan, and you will get an error that the application cannot be found.

In the next chapter, we'll cover how to jump between different priorities based on dialplan logic. You'll be seeing a lot more of priority labels, and you will be using them a lot in your dialplans.

Applications are the workhorses of the dialplan. Each application performs a specific action on the current channel, such as playing a sound, accepting touch-tone input, dialing a channel, hanging up the call, and so forth. In the previous example, you were introduced to two simple applications: Answer() and Hangup(). You'll learn more about how these work momentarily.

Some applications, such as Answer()and Hangup(), need no other instructions to do their jobs. Other applications require additional information. These pieces of information, called arguments, can be passed on to the applications to affect how they perform their actions. To pass arguments to an application, place them between the parentheses that follow the application name, separated by commas.

Tip

Occasionally, you may also see the pipe character (|) being used as a separator between arguments, instead of a comma. Feel free to use whichever you prefer. For the examples in this book, we will be using the comma to separate arguments to an application, as the authors prefer the look of this syntax. You should be aware, however, that when Asterisk parses the dialplan, it converts any commas in the application arguments to pipes.

As we build our first dialplan in the next section, you'll learn to use applications (and their associated arguments) to your advantage.