extensions.conf

extensions.conf - this is the configuration file, where have to make your dial plans

The extensions.conf file is one of the most used and most important configuration file in Asterisk PBX - it contains the dialplan. What is a dialplan? The dialplan , or we can say "the heart of the Asterisk System", defines how Asterisk PBX will handle incoming and outgoing calls, it also contains all extension numbers. The dialplan is divided in sections called contexts. Every context consists from more than one extensions. What is an extension? The extension is the telephone number, it can be numbers, letters or both. Every extension has a priority and an application. With the help of contexts we can organize our dialplan.

In general a dialplan looks like this:

[general]
--> some settings go here

[globals]
--> definition of some global variables go here

[context1]
-->extension 1, priority 1, application
-->extension 1, priority 2, application

--> extension helpdesk, priority 1, application
...
[context2]
--> extension 999, priority 1, application
--> extension 999, priority 1, application



2. Contexts

2.1 [general]

The first context in the extensions.conf file is [general], 3 configuration options can be set here:

static= yes | no - For now only the option yes is implemented, (so setting it to no won't have any effect) and if static=yes and writeprotect=no , then you can save dialplan from the CLI command 'save dialplan'.

More on this in the (upcoming) tutorial on the CLI commands. (The CLI is the interactive asterisk shell, where you could a.o. change your dialplan and save it without altering the extensions.conf file.)

writeprotect = yes | no - This option is require if you want to have ability to save dialplan changes from the CLI command.
autofallthrough=yes|no - If this option is set, after finishing with things to do, Asterisk will hang up the call. If not set, Asterisk will wait for another extension to be dialed. It is highly recommended this option to be set to yes.

2.2 [globals]

In context [globals] you can specify your own variables,
that can be used later in extensions. Note that a global variable
name is not case sensitive, so ${MYVAR} and ${mYvaR} are the same.
The way to write global variable in section [globals] is:

The_name_of_my_variable => The_variable's_value

Example:

[general]
static=yes
writeprotect=no

[globals]
MyMusicOnHold => /mp3/Mozart.mp3

2.3 "Real" call contexts

With the exception of [general] and [globals] everything else is consider as call contexts. The basic look of contexts is:

[context_name]
exten => some_exten_number,priority,application(arg1,arg2,...)
exten => some_exten_number,priority,application,arg1|arg2...
exten => some_pattern,priority,application(arg1,arg2,...)

But what is the purpose of the 'context' ? Inside a context, you could build an IVR menus (Interactive Voice Response) using extensions, you could define a specific context for every department of you company (Accounting, Support, etc)

Using different contexts, the Accounting team would call to their supervisor john when hitting 123, and the support team would call head of support 'alice' when pressing 123.

The support team might be able to do outgoing calls, but the account team could be restricted to only internal calls.

Or incoming calls from clients could be all sent to a waiting Queue, while internal calls between collegues will go straight to the collegue without queing.

So with the help of the contexts it's very easy to manage all assigned telephone numbers.

Example:

[general]
; ...skip...

[globals]
; ...skip...


[Helpdesk]
exten => 323206,1,Dial(SIP/Helpdesk_agent01)
; ...skip...

[Accounting]
exten => 443307,1,Dial(IAX2/Accounting_agent01)
; ...skip...

IVR menu example:

[default]
exten => steve,1,Dial(SIP/steve);
exten => mark,2,Dial(SIP/mark);

[mainmenu]
exten => s,1,Answer
exten => s,n,Background(thanks) ; "Thanks for calling press 1 for sales, 2 for support, ..."
exten => s,n,WaitExten
exten => 1,1,Goto(submenu,s,1)
exten => 2,1,Hangup

[submenu]
exten => s,1,Ringing ; Make them comfortable with 2 seconds of ringback
exten => s,n,Wait,2
exten => s,n,Background(submenuopts) ; "Thanks for calling the sales ;department. Press 1 for steve, 2 for..."
exten => s,n,WaitExten
exten => 1,1,Goto(default,steve,1)
exten => 2,1,Goto(default,mark,2)

Lets have a closer look at what the lines above do exactly.

Any call arriving in the mainmenu context, will first go to the s extension. (why ? Read on and you will find the answer below in the predefined extensions section)

exten => s,1,Ringing:

The first priority in this s extension is extension 1, this will just provide some ringing sound to the caller.

exten => s,n,Wait,2:

The second priority in extension s, is the wait application with parameter 2, which would just wait for 2 seconds, and as a result give ringing for 2 seconds before playing the audio file "submenuopts" to the caller as defined in the 3rd priority. (exten => s,n,Background(submenuopts))

exten => s,n,WaitExten:

The 4th priority will wait for the caller to enter some digits, (such as press 1 for steve, press 2 for mark), the keys pressed by the caller will be the new extension. (if the person presses 1, the call will go to extension 1, priority 1, if the person presses 2, the call would go to extension 2, priority 2)

Lets assume the caller pressed 2:

exten => 2,1,Goto(default,mark,2):

The caller pressed 2 and the call flow will now go to the default context, extension mark, priority 2.

exten => mark,2,Dial(SIP/mark);
In this last step, it would dial the sip user mark. (as defined in sip.conf)

3. Extension

Extension = telephone number? Yes, in general it is true.There are three types of extensions : litteral, predifined and pattern.

The litteral extensions can contain in their name: numbers (0-9), letters A,B,C,D (some hardphones have these letters) or all letters (a-z). Are extension names case sensitive? Yes and no. They are case sensitive when Asterisk have to match a user dialed extension to the extensions that are defined in a context. Extension names are not case sensitive when you try define two extensions (in one context) with same name but different case (you can not do this).

There are several predefined extension names:

- i - Invalid
- s - Start
- h - Hangup
- t - Timeout
- T - AbsoluteTimeout
- o - Operator

Example:

some example

If extension name starts with '_', it is consider as pattern.
For the extension that use pattern, some characters have special meaning:

- X - any digit from 0-9
- Z - any digit from 1-9
- N - any digit from 2-9
- [12679] - any digit in the brakets (in the example: 1,2,6,7,9)
- . - (dot) wildcard, matches everything remaining
( _1234. - matches anything strating with 1234 excluding 1234 itself).

Note: Do not use '_.', because it will match everything even the predefined extensions!!!

Example:

_359ZXXXXXX - This will match all dilaed extensions that start with 359, and are 10 digits long( including 359)
_0XXX. - This will match all dialed extensions that begin with 0 and are minimum 5 digits long (including 0)

So you can see that with help of patterns you can group calls as national, international or local, the only thing you must do is to write the pattern.

4. Other very useful stuff included in extensions.conf

4.1 ignorepad

Another option that can be set is ignorepat. This option instructs drivers
to not cancel dialtone upon receipt specified pattern:
Example:

ignorepat => 8 - dialtone will remain after pressing 8

4.2 switch

Switch option permits a server to share his dialplan with
another server (ServerA>ServerB). Note that reciprocal switch
statements are not allowed (ServerA>ServerB and ServerB>ServerA).

switch => IAX2/:[]@/

Note that and need to be declared in iax.conf
of the remote server ().

4.3 include

You can include all numbers from one context to another context. To do that use:

include => some_context_to_be_included

Except context you can include another configuration file. To do this you have to use '#include':

#include "some_file_to_be_included.conf"