Dial Plan

Dialplan - Routing Calls

[Ref: OpenBSD 5.5, Asterisk 1.8.11 (from ports), doxygen wiki ]

Table of Contents

The dialplan is configured in the file: /etc/asterisk/extensions.conf


The two configurations that will eat much of your time are the client/device configuration (either in sip.conf or iax.conf) and your dial plan.

As your dialplan grows, you either need a graphical GUI to manage it, or you find that isolating discrete segments will simplify readability, and maintainability.

Asterisk allows us to use discrete files to separate the structure or logic of our dialplan.

From doxygen

; You can include other config files, use the #include command
; (without the ';'). Note that this is different from the "include" command
; that includes context within other contexts. The #include works
; in all asterisk configuration files.
Segment Purpose
definitions Global Configurations should stay in extensions.conf
access Access Control List. We use the dialplan to provide (together with the userid/password) access privileges. We use a hierarchy of higher privileges inheriting lower privileges until all privileges in the hierarchy can make internal calls.
context Macros/Subroutines used by Dial applications.
diagnostics Enable user/support to dial extensions that allow them to get feedback on the PBX's performance.
pbxlocal Services/Extensions local to this system
trunk Trunk incoming call handling

extensions.conf comes with basic dialplan segments.


File: /etc/asterisk/extensions.conf

With the #include directive we will be separate related contexts into discrete files.

exten => *99,1,VoiceMailMain(${FILTER(0-9,${CALLERID(NUM)})})

exten => _1XX,1,Dial(SIP/${FILTER(0-9,${EXTEN})},12,tr)
 same => n,Voicemail(${FILTER(0-9,${EXTEN})})
 same => n,Hangup()

Users in our environment are used to ‘hunt groups’ (as differentiated from Automated Call Distributions Groups) where a call to one number will call other numbers if it isn’t picked up.

Unfortunately, the mechanism for creating a ‘hunt group’ is very messy, so one approach (without external programs) ‘injects’ the hunt group extensions just in front of our local PBX extensions.

This way, the mess is isolated into a single area.

; Simultaneous calls
exten => _1200,1,Dial(SIP/1200&SIP/1201&SIP/1202&SIP/1203,40)

; Staggered
exten => _1201,1,Dial(SIP/1201,40)
 same => n,Dial(SIP/1202&SIP/1203&SIP/1204,40)

Console Monitor

[Ref: extensions.conf Testing a pattern using dialplan show]

Monitor the dialplan behaviour through the Asterisk Console, and using dialplan show to review how Asterisk has interpreted your configuration settings.

*CLI> core show help dialplan
Command Description
dialplan reload Reload extensions and *only* extensions
dialplan show Show Dialplan
dialplan show [[exten@]context]
dialplan show chanvar Show channel variables
dialplan show globals Show global dialplan variables
  • show
  • show context

Informative Messages

[Ref: Variables] The verbose mode of the Asterisk Console will give you a lot of information, step-by-step feedback, but somethings require explicit notes, such as finding out what the actual status of a call returns. Use a NoOP(message) to display the status of a call.

File extract: extensions.conf

exten => _X.,1,NoOP(1st line)
  same => n,Dial(${EXTEN})
  same => n,NoOP(Status Return: ${DIALSTATUS})


Variables are referenced in the dialplan using the syntax:



System Variables are case sensitive, user-defined names are not case sensitive.


Global variables can be accessed by any channel at any time.


Shared variables can be accessed with the help of builtin function(s)

Local / Channel

Channel variables are configured using Set, and independence from other channels prevents collision between different calls.