http://www.voip-info.org/wiki/view/Asterisk+config+extensions.

conf

Asterisk config extensions.conf

Page Contents

 extensions.conf - This is your Dialplan

 Context Inclusion
 Extensions
 Predefined Extension Names
 Defining Extensions
 Example
 Variables and expressions
 Reloading
 One big file or several small?
 Forwarding to another Asterisk
 Controlling extensions.conf from outside
 Macro Examples
 Sip header manipulation examples
 Example files on the net
 See also
back to top

extensions.conf - This is your Dialplan

The configuration file "extensions.conf" contains the "dial plan" of Asterisk, the master plan of control
or execution flow for all of its operations. It controls how incoming and outgoing calls are handled and
routed. This is where you configure the behavior of all connections through your PBX.

The content of "extensions.conf" is organized in sections, which can be either for static settings and
definitions, or for executable dialplan components in which case they are referred to as contexts. The
settings sections are general and globals and the names of contexts are entirely defined by the
system administrator. A special type of contexts are macros, label by a userdefined name prefixed
with macro-. These are reusable execution patterns, like procedures in a programming language.
Every section in extensions.conf starts with the name of the section contained within square brackets.
This gives the extensions.conf file a similar structure to the traditional .ini file format of the Windows
world.

Asterisk Dialplan Planning - General discussion about organizing a dialplan

New in Asterisk v1.2: By default, there is a new option called "autofallthrough" in extensions.conf
that is set to yes. Asterisk 1.0 (and earlier) behavior was to wait for an extension to be dialed after
there were no more extensions to execute. "autofallthrough" changes this behavior so that the call is
terminated immediately with BUSY, CONGESTION, or HANGUP based on Asterisk's best guess. If you
are writing an extension for IVR, you must use the WaitExten application if "autofallthrough" is set to
yes.

[general]

 At the top of your extensions.conf file, you configure a few general settings in the section
headed [general]. For details, see:
 o Dialplan General Settings

[globals]

 Next, in the [globals] section, you may define global variables (or constants) and their initial
values. For details, see:
o Dialplan Global Variables
 Using Variables in Asterisk Dialplans

Contexts and Extensions

 After the [general] and [globals] categories, the remainder of the extensions.conf file is taken
up by the definition of the Dialplan. The Dialplan consists of a collection of contexts. Each
context consists of a collection of extensions. For an introduction to these topics, see:
o Introducing Contexts and Extensions

Extension Patterns

 When you define the extensions within a context, you may not only use literal numbers, not
only alphanumeric names, but also you may define extensions that match whole sets of dialed
numbers by using extension patterns. For more information about this, see:
o Extension Names and Patterns

Context Inclusion
One extension context can include the contents of another. For example, consider the following
contexts:

Context "default":
Extension Description
101 Mark Spencer
102 Wil Meadows
0 Operator

Context "local":
Extension Description
_9NXXXXXX Local calls
include => "default"

Context "longdistance":
Extension Description
_91NXXNXXXXXX Long distance calls
include => "local"

Here we have defined three extensions:

 The context default permits dialing three telephone extensions: Mark, Wil, and the Operator.
 The context local has one extension pattern to permit dialing 7-digit numbers only (local
calls), and also includes the context "default", thus also permitting a user to dial Mark, Wil, or
the Operator.
  The context long distance has one extension pattern to permit dialing a long-distance call,
and it also includes the context "local", thus permitting the user to make local calls and also to
dial the extensions of Mark, Wil or the Operator.

Using extension contexts, you can carefully control who has access to toll services.

If more than one pattern matches a dialed number, Asterisk may not use the one you expect. See Sort
Order of Extension Patterns.

Adding to an existing section (I believe this is a 1.4 feature; additional info on similar option are in
doc/configuration.txt of asterisk src tree)

[section]
label = value

[section](+)
label2 = value2

In this case, the plus sign indicates that the second section (with the same name) is an addition to the
first section. The second section can be in another file (by using the #include statement). If the section
name referred to before the plus is missing, the configuration fails to load.

When Asterisk receives an incoming connection on a channel, Asterisk looks at the contextdefined for
that channel for commands telling Asterisk what it should do. The context defines different sets of
commands depending on what extension the user has dialed. For example, a context might provide
one set of commands for what to do if the user dials "123", and another set of commands for what to
do if the user dials "9", and another set of commands for what to do if the user dials any number
beginning with "555".

For some kinds of connections — such incoming calls from an outside telephone line — the user has
not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension
named "s" (for Start). Asterisk looks for an extension "number" s in the definition of the context for
that channel for instructions about what it should do to handle the call.

Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset
in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have
defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk
looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the
definition of a context in extensions.conf by putting the name of the context in square brackets on a
line by itself, like this:

[john]

For each context, you need to define one or more extensions that Asterisk uses to compare against the
number dialed. For each extension, you tell Asterisk what to do by listing a set of commands.

Extensions
An extension can be one of two types: a literal or a pattern.

A literal extension can be a number, like 123, and it can also contain the standard
symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension. Some telephone
keypads have the special DTMF keys labeled A, B, C and D, and extensions can be defined with these
letters too. In fact, the name of an extension can contain any letter or number as well as some
punctuation marks. Note that many VOIP telephones are able to "dial" extension "numbers" that may
be any arbitrary text string, such as "Office". It is perfectly permissible to define an extension with the
name Office in Asterisk.
Extension names may or may not be case sensitive. They are case sensitive in the sense that when
Asterisk is trying to match the extension a user dialed against the extensions defined for a context, the
extension must match, including case. So if a user dials extension "OFFICE" using their VOIP telephone,
Asterisk does not start executing the commands you have defined for an extension named "Office". On
the other hand, extension names are not case sensitive in the sense that you can not define different
extensions (in the one context) that have the same names differing only in case. So you can't define
one set of commands for extension "Office" and another set of commands for extension "OFFICE".

Predefined Extension Names

Asterisk uses some extension names for special purposes:

 i : Invalid
 s : Start
 h : Hangup
 t : Timeout
 T : AbsoluteTimeout
 a : Asterisk extension
 o : Operator
See Asterisk standard extensions for details.

Defining Extensions
Unlike a traditional PBX, where extensions are associated with phones, interfaces, menus, and so on, in
Asterisk an extension is defined as a list of commands to execute. The commands are generally
executed in the order defined by their "priority" tag, but some commands, such as
the Dial and GotoIfcommands, have the ability to redirect somewhere else, based on some condition.

When an extension is dialed, the command tagged with a priority of 1 is executed, followed by
command priority 2, and so on. This goes on until:

 the call is hung up,

 a command returns a result code of -1 (indicating failure),
 a command with the next higher priority doesn't exist (note: Asterisk does not "skip over"
missing priorities), or
 the call is routed to a new extension.

In the syntax of the extensions.conf file, each execution step in an extension is written in this format:

exten = extension,priority,Command(parameters)

where the equal sign can also be ornamented as an arrow, i.e., "=>", a form most often seen in many
examples.

Ok, so a "context" has a name, such as "john". And in each context, you can define one or more
"extensions". For each extension, you define a set ofcommands. So how do you define these
extensions and the commands to handle them? You need to edit the extensions.conf file with a text
editor. However, there are some tools available to help: GUI tool.

The components of an extension execution step or command line are the following:
  extension is the label of the extension, and can be either a literal constant string
(alphanumeric plus a few special symols allowed) or a dynamically evaluated pattern (see
below) to match many possible phone numbers, for example. Every command line that is part
of a given extensions has this same label.

 priority is usually an integer (see note, however). It's just a sequence number for each
command line of an extension. The first executable command of an extensions has the priority
"1", so when Asterisk transfers a call to an extension, it looks for a command with priority 1. If
there is not a line with a priority of 1, then the extension does not match the dialed number.
After executing the priority 1 command, Asterisk increments the priority to "2" unless the
command itself determines the next priority to be executed. If this next priority is not defined
in the extension, Asterisk finishes processing for this extension, even if there exists another
command with a priority higher than the missing one.

Note: Strings may also be used in place of priority in special situations (see Asterisk standard
extensions).

 command is the name of the command (also called an "application") to execute. See
the Asterisk Commands List.

 parameters depend on the command. Some commands take no parameters, in which case you
can omit the parentheses.

Example

exten => 123,1,Answer

exten => 123,2,Playback(tt-weasels)
exten => 123,3,Voicemail(44)
exten => 123,4,Hangup

This is the definiton of a single extension with name "123". When a call is made to extension 123,
Asterisk answers the call itself, play a sound file called "tt-weasels", give the user an opportunity to
leave a voicemail message for mailbox 44, and then hangup.

Note that Asterisk doesn't care about the order in which you put the lines in the extensions.conf file.
You could mix the lines into a different order, like this following example, and it would make no
difference because Asterisk uses the priority of each line to determine order of execution:

exten => 123,4,Hangup

exten => 123,1,Answer
exten => 123,3,Voicemail(44)
exten => 123,2,Playback(tt-weasels)

Other options for defining extensions include an option commonly referred to as the ex-girlfriend logic.
This logic matches the dialed extension irrespective of its origin based on the callerid of the person
calling it. For example:

exten => 123/100,1,Answer()

exten => 123/100,2,Playback(tt-weasels)
exten => 123/100,3,Voicemail(123)
exten => 123/100,4,Hangup()
This matches extension 123 and perform the following options ONLY if the Caller-ID Number of the
calling user is 100. This can also be accomplished with pattern matching, as seen below:

exten => 1234/_256NXXXXXX,1,Answer()

and so on...

This matches only 1234 if the Caller ID Number is something beginning with 256. This is very useful to
keep locals from dialing your toll-free number and charging you for the call.

You can even do this:

exten => s,1,Answer

exten => s/9184238080,2,Set(CALLERID(name)=EVIL BASTARD)
exten => s,2,Set(CALLERID(name)=Good Person)
exten => s,3,Dial(SIP/goodperson)

(thanks for pointing that out, Brian :) )

Basically the call comes in, at 2 you fork the people you don't like out, everybody else stays in the path
and at 3 everybody is back in the main path.

Syntax for defining a context: keywords exten, include, ignorepat and switch.

 How Does Asterisk Handle "Match As You Go" Dialing?

One of the banes of this method of storing the extension information is that if you need to insert or
delete a priority, you have to manually renumber all numbers after it and all label referrences to it. I'm
working on a utility to do this online: give it a try if you like

Since Asterisk 1.2 there is a new way to work around this. Number the first priority and "name" the
following priorities "n". See Asterisk Priorities for further details!

If you are not so familiar with Asterisk dialplan syntax, dialplan priorities, or you simply do not prefer
coding using text editors, you may find Visual Dialplan for Asterisk useful tool for your dialplan
development. Visual Dialplan for Asterisk is rapid dialplan development tool for Asterisk dialplan
development, it provides similar interface and approach like Visual Basic provides for rapid application
development for Windows platform (if you are more familiar the Windows environment like I am,
although there is Visual Dialplan for Linux too).
You may drag, drop and connect building blocks to make Asterisk dialplan. Then you may configure
building blocks to fine tune your dialplan.
Here is the same example above created using Visual Dialplan for Asterisk:

Download above example

Download Visual Dialplan for Asterisk
Variables and expressions
There is support for using variables using the ${VARIABLENAME} construct. You can also use
expressions with the $[EXPRESSION] construct, where expressions can be regular expressions,
comparision, addition, substraction and much more. See Asterisk variables for standard variables
and Asterisk readme.variables for an explanations of expressions.

For more information about using global variables and channel variables in extensions.conf, see

 Using Variables in Asterisk Dialplans

New in 1.2 are dialplan functions, see

 Using Functions in Asterisk Dialplans

Reloading
If you want to reload the dial plan after changes, without reloading all of Asterisk's config, use
the dialplan reload Asterisk CLI command.

Either connect to your asterisk process with asterisk -r or rasterisk and type in the command, or
send the command directly with:

asterisk -rx 'dialplan reload'

One big file or several small?

With the #include <filename> statement in extensions.conf, other files are included. This way you
can setup a system where extensions.conf is the main file, users.conf (SEE IMPORTANT NOTE BELOW)
contain your local users, services.conf contain various services, like conferencing. This way, the dial
plan may be easier to maintain, depending on the size of your setup. The #include
<filename> statement is not the same as the include <context>statement.
The #include statement works in all Asterisk configuration files.

DO NOT USE users.conf as a filename anymore! This is now a "reserved" filename as of Asterisk 1.4!
In general, it is a good idea to divide your extensions.conf file up into subcomponents but put those
files in a subdirectory (don't clutter up /etc/asterisk). For example, have a directory /etc/asterisk/exts
and use #include <exts/...>

Sample extensions.conf using the #include statement

#include "my-extra-config-file"
[globals]
ALL=Zap/1&SIP/1000&SIP/1001

[default]
exten => s,1,Answer
exten => s,2,Playback(welcome-message)
exten => s,3,Goto(context-in-include-file,s,1) ;
go to context defined in included file

Forwarding to another Asterisk

Syntax:
[iaxprovider]
switch => IAX2/user:[key]@server/context

Specifies forwarding to another server. The user and key needs to be defined in the iax.conf file of the
server which is called. The context is a context in the called servers extensions.conf.

 See Asterisk - dual servers for an example

Controlling extensions.conf from outside

 Asterisk extensions from mysql
 as with all .conf files you can use the #include statement to include another file

Macro Examples
Using a macro to create extensions

[globals]
PHONE1=Zap/1
PHONE2=SIP/6002

[macro-oneline]
exten => s,1,Dial(${ARG1},20,t)
exten => s,2,Voicemail(u${MACRO_EXTEN})
exten => s,3,Hangup
exten => s,102,Voicemail(b${MACRO_EXTEN})
exten => s,103,Hangup

[local]
exten => 6601,1,Macro(oneline,${PHONE1})
exten => 6602,1,Macro(oneline,${PHONE2})

 Asterisk dial plan - working example: Real world example

 An expanded example showing integrations with a Panasonic KSU ivr

Sip header manipulation examples

These examples may be beneficial when interfacing Asterisk with a Nortel SST or an Acme Packet SBC.

Sending RFC-3323 compliant privacy headers in sip calls

ftp://ftp.rfc-editor.org/in-notes/rfc3323.txt

exten => _9.,1,SIPAddHeader(P-Asserted-Identity: <sip:+1${CALLERID(num)}\;user=phone>)

exten => _9.,n,SIPAddHeader(Privacy: user\; header\; session)
exten => _9.,n.SetCallerPres(prohib_not_screened) ; this might not be needed --- needs further testing
exten => _9.,n,Set(CALLERID(num)=)
exten => _9.,n,Set(CALLERID(name)=Anonymous)
exten => _9.,n,Dial(SIP/+${EXTEN:1}@sipcarrier)
exten => _9.,n,Hangup()

Sending RFC-3325 compliant privacy headers in sip calls

ftp://ftp.rfc-editor.org/in-notes/rfc3325.txt

exten => _9.,1,SIPAddHeader(P-Preferred-Identity: <sip:+1${CALLERID(num)}\;user=phone>)

exten => _9.,n,SIPAddHeader(Privacy: id)
exten => _9.,n.SetCallerPres(prohib_not_screened) ; this might not be needed --- needs further testing
exten => _9.,n,Set(CALLERID(num)=)
exten => _9.,n,Set(CALLERID(name)=Anonymous)
exten => _9.,n,Dial(SIP/+${EXTEN:1}@sipcarrier)
exten => _9.,n,Hangup()

Sending Sip Diversion headers (spawned from dialplan as macro)

[macro-diversion-header]
exten => s,1,SIPAddHeader(Diversion: <tel:+{ARG1}>\;reason=user=busy\;screen=no\;privacy=off)
Tip: With vim syntax highlighting highlights correct dialplan syntax and may ease dialplan design
through these visual aids.

Example files on the net

 How to set up a SIP trunk in the Asterisk PBX - Basic setup How-To/tutorial, SIP trunk and
dialplan, to dial out, and in. With full example configuration files.
 John Todd, Loligo.com: http://www.loligo.com/asterisk/current/extensions.conf

 Tilghman Lesher: http://asterisk.drunkcoder.com/extensions.conf

 planetWayne: Ideas for Home Based Asterisk Systems

See also
 AEL: The Asterisk Extension Language
 AEL2: The Asterisk Extension Language v2.
 Asterisk Configuration files
 Asterisk config sip.conf: sip.conf sample configurations
 Asterisk Dialplanner - A Java-based point-and-click web tool to help you create your dialplan.
 Asterisk - dual servers: How to connect to an extension in another Asterisk server over IAX.
 Asterisk handbook (draft) includes a good explanation and many examples
 Asterisk how to dial plan: How to build a dial plan
 Asterisk tips and tricks
 Dialplan Commands
 Dialplan Renumberer Utility - Beta resource for renumbering your dialplan if you have to
insert/delete a priority.
 Extension Names and Patterns
 http://www.astautodialer.com - AstPlanDesigner (part of AstAutoDialer) - A graphical tool to
draw and visualize your Asterisk dial plan!
 International numbering plans and phone number analysis
 radp - Ruby Asterisk Dial Plan generator (create your dialplans with ruby)
 Sort Order of Extension Patterns
 Using Variables in Asterisk Dialplans
 Using Functions in Asterisk Dialplans
 vim syntax highlighting for extensions.conf