Thu Oct 11 06:44:30 2012

Asterisk developer's documentation

Extensions.conf - the Dial Plan


; extensions.conf - the Asterisk dial plan
; Static extension configuration file, used by
; the pbx_config module. This is where you configure all your 
; inbound and outbound calls in Asterisk. 
; This configuration file is reloaded 
; - With the "dialplan reload" command in the CLI
; - With the "reload" command (that reloads everything) in the CLI

; The "General" category is for certain variables.  
; If static is set to no, or omitted, then the pbx_config will rewrite
; this file when extensions are modified.  Remember that all comments
; made in the file will be lost when that happens. 
; XXX Not yet implemented XXX
; if static=yes and writeprotect=no, you can save dialplan by
; CLI command "dialplan save" too
; If autofallthrough is set, then if an extension runs out of
; things to do, it will terminate the call with BUSY, CONGESTION
; or HANGUP depending on Asterisk's best guess. This is the default.
; If autofallthrough is not set, then if an extension runs out of 
; things to do, Asterisk will wait for a new extension to be dialed 
; (this is the original behavior of Asterisk 1.0 and earlier).
; If clearglobalvars is set, global variables will be cleared 
; and reparsed on an extensions reload, or Asterisk reload.
; If clearglobalvars is not set, then global variables will persist
; through reloads, and even if deleted from the extensions.conf or
; one of its included files, will remain set to the previous value.
; NOTE: A complication sets in, if you put your global variables into
; the AEL file, instead of the extensions.conf file. With clearglobalvars
; set, a "reload" will often leave the globals vars cleared, because it
; is not unusual to have extensions.conf (which will have no globals)
; load after the extensions.ael file (where the global vars are stored).
; So, with "reload" in this particular situation, first the AEL file will
; clear and then set all the global vars, then, later, when the extensions.conf
; file is loaded, the global vars are all cleared, and then not set, because
; they are not stored in the extensions.conf file.
; If priorityjumping is set to 'yes', then applications that support
; 'jumping' to a different priority based on the result of their operations
; will do so (this is backwards compatible behavior with pre-1.2 releases
; of Asterisk). Individual applications can also be requested to do this
; by passing a 'j' option in their arguments.
; User context is where entries from users.conf are registered.  The
; default value is 'default'
; You can include other config files, use the #include command
; (without the ';'). Note that this is different from the "include" command
; that includes contexts within other contexts. The #include command works
; in all asterisk configuration files.
;#include "filename.conf"
;#include <filename.conf>
;#include filename.conf
; You can execute a program or script that produces config files, and they
; will be inserted where you insert the #exec command. The #exec command 
; works on all asterisk configuration files.  However, you will need to
; activate them within asterisk.conf with the "execincludes" option.  They
; are otherwise considered a security risk.
;#exec /opt/bin/
;#exec /opt/bin/ --foo="bar"
;#exec </opt/bin/ --foo="bar">
;#exec "/opt/bin/ --foo=\"bar\""

; The "Globals" category contains global variables that can be referenced
; in the dialplan with the GLOBAL dialplan function:
; ${${GLOBAL(VARIABLE)}} or ${text${GLOBAL(VARIABLE)}} or any hybrid
; Unix/Linux environmental variables can be reached with the ENV dialplan
; function: ${ENV(VARIABLE)}
CONSOLE=Console/dsp				; Console interface for demo
IAXINFO=guest					; IAXtel username/password
TRUNK=Zap/G2					; Trunk interface
; Note the 'G2' in the TRUNK variable above. It specifies which group (defined
; in chan_dahdi.conf) to dial, i.e. group 2, and how to choose a channel to use in
; the specified group. The four possible options are:
; g: select the lowest-numbered non-busy Zap channel
;    (aka. ascending sequential hunt group).
; G: select the highest-numbered non-busy Zap channel
;    (aka. descending sequential hunt group).
; r: use a round-robin search, starting at the next highest channel than last
;    time (aka. ascending rotary hunt group).
; R: use a round-robin search, starting at the next lowest channel than last
;    time (aka. descending rotary hunt group).
TRUNKMSD=1					; MSD digits to strip (usually 1 or 0)
; If you load any other extension configuration engine, such as,
; your global variables may be overridden by that file.  Please take care to
; use only one location to set global variables, and you will likely save
; yourself a ton of grief.
; Any category other than "General" and "Globals" represent 
; extension contexts, which are collections of extensions.  
; Extension names may be numbers, letters, or combinations
; thereof. If an extension name is prefixed by a '_'
; character, it is interpreted as a pattern rather than a
; literal.  In patterns, some characters have special meanings:
;   X - any digit from 0-9
;   Z - any digit from 1-9
;   N - any digit from 2-9
;   [1235-9] - any digit in the brackets (in this example, 1,2,3,5,6,7,8,9)
;   . - wildcard, matches anything remaining (e.g. _9011. matches 
;	anything starting with 9011 excluding 9011 itself)
;   ! - wildcard, causes the matching process to complete as soon as
;       it can unambiguously determine that no other matches are possible
; For example the extension _NXXXXXX would match normal 7 digit dialings, 
; while _1NXXNXXXXXX would represent an area code plus phone number
; preceded by a one.
; Each step of an extension is ordered by priority, which must
; always start with 1 to be considered a valid extension.  The priority
; "next" or "n" means the previous priority plus one, regardless of whether
; the previous priority was associated with the current extension or not.
; The priority "same" or "s" means the same as the previously specified
; priority, again regardless of whether the previous entry was for the
; same extension.  Priorities may be immediately followed by a plus sign
; and another integer to add that amount (most useful with 's' or 'n').  
; Priorities may then also have an alias, or label, in 
; parenthesis after their name which can be used in goto situations
; Contexts contain several lines, one for each step of each
; extension, which can take one of two forms as listed below,
; with the first form being preferred. 
;exten => someexten,{priority|label{+|-}offset}[(alias)],application(arg1,arg2,...)
;exten => someexten,{priority|label{+|-}offset}[(alias)],application,arg1|arg2...
; Included Contexts
; One may include another context in the current one as well, optionally with a
; date and time.  Included contexts are included in the order
; they are listed.
; The reason a context would include other contexts is for their 
; extensions.
; The algorithm to find an extension is recursive, and works in this
; fashion: 
;	 first, given a stack on which to store context references, 
;           push the context to find the extension onto the stack...
;    a) Try to find a matching extension in the context at the top of 
;       the stack, and, if found, begin executing the priorities
;       there in sequence.
;    b) If not found, Search the switches, if any declared, in
;       sequence.
;    c) If still not found, for each include, push that context onto 
;       the top of the context stack, and recurse to a).
;    d) If still not found, pop the entry from the top of the stack; 
;       if the stack is empty, the search has failed. If it's not, 
;       continue with the next context in c).
; This is a depth-first traversal, and stops with the first context 
; that provides a matching extension. As usual, if more than one
; pattern in a context will match, the 'best' match will win.
; Please note that that extensions found in an included context are
; treated as if they were in the context from which the search began.
; The PBX's notion of the "current context" is not changed.
; Please note that in a context, it does not matter where an include
; directive occurs. Whether at the top, or near the bottom, the effect 
; will be the same. The only thing that matters is that if there is 
; more than one include directive, they will be searched for extensions 
; in order, first to last.
; Also please note that pattern matches (like _9XX) are not treated
; any differently than exact matches (like 987). Also note that the
; order of extensions in a context have no affect on the outcome.
; Timing list for includes is 
;   <time range>|<days of week>|<days of month>|<months>
; Note that ranges may be specified to wrap around the ends.  Also, minutes are
; fine-grained only down to the closest even minute.
;include => daytime|9:00-17:00|mon-fri|*|*
;include => weekend|*|sat-sun|*|*
;include => weeknights|17:02-8:58|mon-fri|*|*
; ignorepat can be used to instruct drivers to not cancel dialtone upon
; receipt of a particular pattern.  The most commonly used example is
; of course '9' like this:
;ignorepat => 9
; so that dialtone remains even after dialing a 9.

; Sample entries for extensions.conf
; List canonical entries here
;exten => 12564286000,1,Macro(stdexten,6000,IAX2/foo)
;exten => _125642860XX,1,Dial(IAX2/otherbox/${EXTEN:7})

; If you are an ITSP or Reseller, list your customers here.
;exten => _12564286000,1,Dial(SIP/customer1)
;exten => _12564286001,1,Dial(IAX2/customer2)

; If you are freely delivering calls to the PSTN, list them here
;exten => _1256428XXXX,1,Dial(Zap/G2/${EXTEN:7}) ; Expose all of 256-428 
;exten => _1256325XXXX,1,Dial(Zap/G2/${EXTEN:7}) ; Ditto for 256-325

; Context to put your dundi IAX2 or SIP user in for
; full access
include => dundi-e164-canonical
include => dundi-e164-customers
include => dundi-e164-via-pstn

; Just a wrapper for the switch
switch => DUNDi/e164

; Locally to lookup, try looking for a local E.164 solution
; then try DUNDi if we don't have one.
include => dundi-e164-local
include => dundi-e164-switch
; DUNDi can also be implemented as a Macro instead of using 
; the Local channel driver. 
; ARG1 is the extension to Dial
; Extension "s" is not a wildcard extension that matches "anything".
; In macros, it is the start extension. In most other cases, 
; you have to goto "s" to execute that extension.
; For wildcard matches, see above - all pattern matches start with
; an underscore.
exten => s,1,Goto(${ARG1},1)
include => dundi-e164-lookup

; Here are the entries you need to participate in the IAXTEL
; call routing system.  Most IAXTEL numbers begin with 1-700, but
; there are exceptions.  For more information, and to sign
; up, please go to or
exten => _91700XXXXXXX,1,Dial(IAX2/${GLOBAL(IAXINFO)}${EXTEN:1}@iaxtel)

; The SWITCH statement permits a server to share the dialplan with
; another server. Use with care: Reciprocal switch statements are not
; allowed (e.g. both A -> B and B -> A), and the switched server needs
; to be on-line or else dialing can be severly delayed.
;switch => IAX2/user:[key]@myserver/mycontext

; International long distance through trunk
exten => _9011.,1,Macro(dundi-e164,${EXTEN:4})
exten => _9011.,n,Dial(${GLOBAL(TRUNK)}/${FILTER(0123456789,${EXTEN:${GLOBAL(TRUNKMSD)}})})

; Long distance context accessed through trunk
exten => _91NXXNXXXXXX,1,Macro(dundi-e164,${EXTEN:1})

; Local seven-digit dialing accessed through trunk interface

; Long distance context accessed through trunk interface
exten => _91800NXXXXXX,1,Dial(${GLOBAL(TRUNK)}/${EXTEN:${GLOBAL(TRUNKMSD)}})
exten => _91888NXXXXXX,1,Dial(${GLOBAL(TRUNK)}/${EXTEN:${GLOBAL(TRUNKMSD)}})
exten => _91877NXXXXXX,1,Dial(${GLOBAL(TRUNK)}/${EXTEN:${GLOBAL(TRUNKMSD)}})
exten => _91866NXXXXXX,1,Dial(${GLOBAL(TRUNK)}/${EXTEN:${GLOBAL(TRUNKMSD)}})

; Master context for international long distance
ignorepat => 9
include => longdistance
include => trunkint

; Master context for long distance
ignorepat => 9
include => local
include => trunkld

; Master context for local, toll-free, and iaxtel calls only
ignorepat => 9
include => default
include => trunklocal
include => iaxtel700
include => trunktollfree
include => iaxprovider

;Include parkedcalls (or the context you define in features conf)
;to enable call parking.
include => parkedcalls
; You can use an alternative switch type as well, to resolve
; extensions that are not known here, for example with remote 
; IAX switching you transparently get access to the remote
; Asterisk PBX
; switch => IAX2/user:password@bigserver/local
; An "lswitch" is like a switch but is literal, in that
; variable substitution is not performed at load time
; but is passed to the switch directly (presumably to
; be substituted in the switch routine itself)
; lswitch => Loopback/12${EXTEN}@othercontext
; An "eswitch" is like a switch but the evaluation of
; variable substitution is performed at runtime before
; being passed to the switch routine.
; eswitch => IAX2/context@${CURSERVER}

; Standard trunk dial macro (hangs up on a dialstatus that should 
; terminate call)
;   ${ARG1} - What to dial
exten => s,1,Dial(${ARG1})
exten => s,n,Goto(s-${DIALSTATUS},1)
exten => s-NOANSWER,1,Hangup
exten => s-BUSY,1,Hangup
exten => _s-.,1,NoOp

; Standard extension macro:
;   ${ARG1} - Extension  (we could have used ${MACRO_EXTEN} here as well
;   ${ARG2} - Device(s) to ring
exten => s,1,Dial(${ARG2},20)			; Ring the interface, 20 seconds maximum
exten => s,2,Goto(s-${DIALSTATUS},1)		; Jump based on status (NOANSWER,BUSY,CHANUNAVAIL,CONGESTION,ANSWER)

exten => s-NOANSWER,1,Voicemail(${ARG1},u)	; If unavailable, send to voicemail w/ unavail announce
exten => s-NOANSWER,2,Goto(default,s,1)		; If they press #, return to start

exten => s-BUSY,1,Voicemail(${ARG1},b)		; If busy, send to voicemail w/ busy announce
exten => s-BUSY,2,Goto(default,s,1)		; If they press #, return to start

exten => _s-.,1,Goto(s-NOANSWER,1)		; Treat anything else as no answer

exten => a,1,VoicemailMain(${ARG1})		; If they press *, send the user into VoicemailMain

; Standard extension macro:
;   ${ARG1} - Extension  (we could have used ${MACRO_EXTEN} here as well
;   ${ARG2} - Device(s) to ring
;   ${ARG3} - Optional DONTCALL context name to jump to (assumes the s,1 extension-priority)
;   ${ARG4} - Optional TORTURE context name to jump to (assumes the s,1 extension-priority)`
exten => s,1,Dial(${ARG2},20|p)			; Ring the interface, 20 seconds maximum, call screening 
						; option (or use P for databased call screening)
exten => s,2,Goto(s-${DIALSTATUS},1)		; Jump based on status (NOANSWER,BUSY,CHANUNAVAIL,CONGESTION,ANSWER)

exten => s-NOANSWER,1,Voicemail(${ARG1},u)	; If unavailable, send to voicemail w/ unavail announce
exten => s-NOANSWER,2,Goto(default,s,1)		; If they press #, return to start

exten => s-BUSY,1,Voicemail(${ARG1},b)		; If busy, send to voicemail w/ busy announce
exten => s-BUSY,2,Goto(default,s,1)		; If they press #, return to start

exten => s-DONTCALL,1,Goto(${ARG3},s,1)		; Callee chose to send this call to a polite "Don't call again" script.

exten => s-TORTURE,1,Goto(${ARG4},s,1)		; Callee chose to send this call to a telemarketer torture script.

exten => _s-.,1,Goto(s-NOANSWER,1)		; Treat anything else as no answer

exten => a,1,VoicemailMain(${ARG1})		; If they press *, send the user into VoicemailMain

; Paging macro:
;       Check to see if SIP device is in use and DO NOT PAGE if they are
;   ${ARG1} - Device to page

exten => s,1,ChanIsAvail(${ARG1}|js)			; j is for Jump and s is for ANY call
exten => s,n,GoToIf($[${AVAILORIGCHAN} = ""]?fail:autoanswer)
exten => s,n(autoanswer),Set(_ALERT_INFO="RA")			; This is for the PolyComs
exten => s,n,SIPAddHeader(Call-Info: Answer-After=0)	; This is for the Grandstream, Snoms, and Others
exten => s,n,NoOp()					; Add others here and Post on the Wiki!!!!
exten => s,n,Dial(${ARG1}||)
exten => s,n(fail),Hangup

; We start with what to do when a call first comes in.
exten => s,1,Wait(1)			; Wait a second, just for fun
exten => s,n,Answer			; Answer the line
exten => s,n,Set(TIMEOUT(digit)=5)	; Set Digit Timeout to 5 seconds
exten => s,n,Set(TIMEOUT(response)=10)	; Set Response Timeout to 10 seconds
exten => s,n(restart),BackGround(demo-congrats)	; Play a congratulatory message
exten => s,n(instruct),BackGround(demo-instruct)	; Play some instructions
exten => s,n,WaitExten			; Wait for an extension to be dialed.

exten => 2,1,BackGround(demo-moreinfo)	; Give some more information.
exten => 2,n,Goto(s,instruct)

exten => 3,1,Set(LANGUAGE()=fr)		; Set language to french
exten => 3,n,Goto(s,restart)		; Start with the congratulations

exten => 1000,1,Goto(default,s,1)
; We also create an example user, 1234, who is on the console and has
; voicemail, etc.
exten => 1234,1,Playback(transfer,skip)		; "Please hold while..." 
					; (but skip if channel is not up)
exten => 1234,n,Macro(stdexten,1234,${GLOBAL(CONSOLE)})

exten => 1235,1,Voicemail(1234,u)		; Right to voicemail

exten => 1236,1,Dial(Console/dsp)		; Ring forever
exten => 1236,n,Voicemail(1234,b)		; Unless busy

; # for when they're done with the demo
exten => #,1,Playback(demo-thanks)	; "Thanks for trying the demo"
exten => #,n,Hangup			; Hang them up.

; A timeout and "invalid extension rule"
exten => t,1,Goto(#,1)			; If they take too long, give up
exten => i,1,Playback(invalid)		; "That's not valid, try again"

; Create an extension, 500, for dialing the
; Asterisk demo.
exten => 500,1,Playback(demo-abouttotry); Let them know what's going on
exten => 500,n,Dial(IAX2/	; Call the Asterisk demo
exten => 500,n,Playback(demo-nogo)	; Couldn't connect to the demo site
exten => 500,n,Goto(s,6)		; Return to the start over message.

; Create an extension, 600, for evaluating echo latency.
exten => 600,1,Playback(demo-echotest)	; Let them know what's going on
exten => 600,n,Echo			; Do the echo test
exten => 600,n,Playback(demo-echodone)	; Let them know it's over
exten => 600,n,Goto(s,6)		; Start over

;	You can use the Macro Page to intercom a individual user
exten => 76245,1,Macro(page,SIP/Grandstream1)
; or if your peernames are the same as extensions
exten => _7XXX,1,Macro(page,SIP/${EXTEN})
; System Wide Page at extension 7999
exten => 7999,1,Set(TIMEOUT(absolute)=60)
exten => 7999,2,Page(Local/Grandstream1@page&Local/Xlite1@page&Local/1234@page/n|d)

; Give voicemail at extension 8500
exten => 8500,1,VoicemailMain
exten => 8500,n,Goto(s,6)
; Here's what a phone entry would look like (IXJ for example)
;exten => 1265,1,Dial(Phone/phone0,15)
;exten => 1265,n,Goto(s,5)

;	The page context calls up the page macro that sets variables needed for auto-answer
;	It is in is own context to make calling it from the Page() application as simple as 
;	Local/{peername}@page
exten => _X.,1,Macro(page,SIP/${EXTEN})

; Example "main menu" context with submenu
;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
;include => default
;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)

; By default we include the demo.  In a production system, you 
; probably don't want to have the demo there.
include => demo

; An extension like the one below can be used for FWD, Nikotel, sipgate etc.
; Note that you must have a [sipprovider] section in sip.conf
;exten => _41X.,1,Dial(SIP/${FILTER(0123456789,${EXTEN:2})}@sipprovider,,r)

; Real extensions would go here. Generally you want real extensions to be
; 4 or 5 digits long (although there is no such requirement) and start with a
; single digit that is fairly large (like 6 or 7) so that you have plenty of
; room to overlap extensions and menu options without conflict.  You can alias
; them with names, too, and use global variables

;exten => 6245,hint,SIP/Grandstream1&SIP/Xlite1,Joe Schmoe ; Channel hints for presence
;exten => 6245,1,Dial(SIP/Grandstream1,20,rt)	; permit transfer
;exten => 6245,n(dial),Dial(${HINT},20,rtT)	; Use hint as listed
;exten => 6245,n,Voicemail(6245,u)		; Voicemail (unavailable)
;exten => 6245,s+1,Hangup			; s+1, same as n
;exten => 6245,dial+101,Voicemail(6245,b)	; Voicemail (busy)
;exten => 6361,1,Dial(IAX2/JaneDoe,,rm)		; ring without time limit
;exten => 6389,1,Dial(MGCP/aaln/1@
;exten => 6390,1,Dial(JINGLE/caller/callee) ; Dial via jingle using labels
;exten => 6391,1,Dial(JINGLE/ ;Dial via jingle using asterisk as the transport and calling mogorman.
;exten => 6394,1,Dial(Local/6275/n)		; this will dial ${MARK}

;exten => 6275,1,Macro(stdexten,6275,${MARK})	; assuming ${MARK} is something like Zap/2
;exten => mark,1,Goto(6275|1)			; alias mark to 6275
;exten => 6536,1,Macro(stdexten,6236,${WIL})	; Ditto for wil
;exten => wil,1,Goto(6236|1)

;If you want to subscribe to the status of a parking space, this is
;how you do it. Subscribe to extension 6600 in sip, and you will see
;the status of the first parking lot with this extensions' help
;exten => 6600,hint,park:701@parkedcalls
;exten => 6600,1,noop
; Some other handy things are an extension for checking voicemail via
; voicemailmain
;exten => 8500,1,VoicemailMain
;exten => 8500,n,Hangup
; Or a conference room (you'll need to edit meetme.conf to enable this room)
;exten => 8600,1,Meetme(1234)
; Or playing an announcement to the called party, as soon it answers
;exten = 8700,1,Dial(${MARK},30,A(/path/to/my/announcemsg))
; For more information on applications, just type "core show applications" at your
; friendly Asterisk CLI prompt.
; "core show application <command>" will show details of how you
; use that particular application in this file, the dial plan. 
; "core show functions" will list all dialplan functions
; "core show function <COMMAND>" will show you more information about
; one function. Remember that function names are UPPER CASE.

Generated on Thu Oct 11 06:44:30 2012 for Asterisk - the Open Source PBX by  doxygen 1.5.6