Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:49:24 2009

## Asterisk developer's documentation

# Extensions.conf - the Dial Plan

## Extensions.conf

    ;
    ; 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 "extensions reload" command in the CLI
    ; - With the "reload" command (that reloads everything) in the CLI

    ;
    ; The "General" category is for certain variables.
    ;
    [general]
    ;
    ; 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
    ;
    static=yes
    ;
    ; if static=yes and writeprotect=no, you can save dialplan by
    ; CLI command 'save dialplan' too
    ;
    writeprotect=no
    ;
    ; 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 (strongly recommended).
    ;
    ; 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).
    ;
    autofallthrough=yes
    ;
    ; 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.
    ;
    clearglobalvars=no
    ;
    ; 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.
    ;
    priorityjumping=no
    ;
    ; 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"

    ; The "Globals" category contains global variables that can be referenced
    ; in the dialplan with ${VARIABLE} or ${ENV(VARIABLE)} for Environmental
    ; variables,
    ; ${${VARIABLE}} or ${text${VARIABLE}} or any hybrid
    ;
    [globals]
    CONSOLE=Console/dsp				; Console interface for demo
    ;CONSOLE=Zap/1
    ;CONSOLE=Phone/phone0
    IAXINFO=guest					; IAXtel username/password
    ;IAXINFO=myuser:mypass
    TRUNK=Zap/g2					; Trunk interface
    ;
    ; Note the 'g2' in the TRUNK variable above. It specifies which group (defined
    ; in zapata.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)
    ;TRUNK=IAX2/user:pass@provider

    ;
    ; 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.  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.
    ;
    ;[context]
    ;exten => someexten,priority[+offset][(alias)],application(arg1,arg2,...)
    ;exten => someexten,priority[+offset][(alias)],application,arg1|arg2...
    ;
    ; Timing list for includes is
    ;
    ;   <time range>|<days of week>|<days of month>|<months>
    ;
    ;include => daytime|9:00-17:00|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
    ;
    ;
    [dundi-e164-canonical]
    ;
    ; List canonical entries here
    ;
    ;exten => 12564286000,1,Macro(stdexten,6000,IAX2/foo)
    ;exten => _125642860XX,1,Dial(IAX2/otherbox/${EXTEN:7})

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

    [dundi-e164-via-pstn]
    ;
    ; 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

    [dundi-e164-local]
    ;
    ; 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

    [dundi-e164-switch]
    ;
    ; Just a wrapper for the switch
    ;
    switch => DUNDi/e164

    [dundi-e164-lookup]
    ;
    ; 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.
    ;
    [macro-dundi-e164]
    ;
    ; ARG1 is the extension to Dial
    ;
    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 www.gnophone.com or www.iaxtel.com
    ;
    [iaxtel700]
    exten => _91700XXXXXXX,1,Dial(IAX2/${IAXINFO}@iaxtel.com/${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.
    ;
    [iaxprovider]
    ;switch => IAX2/user:[key]@myserver/mycontext

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

    [trunkld]
    ;
    ; Long distance context accessed through trunk
    ;
    exten => _91NXXNXXXXXX,1,Macro(dundi-e164,${EXTEN:1})
    exten => _91NXXNXXXXXX,n,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})

    [trunklocal]
    ;
    ; Local seven-digit dialing accessed through trunk interface
    ;
    exten => _9NXXXXXX,1,Dial(${TRUNK}/${EXTEN:${TRUNKMSD}})

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

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

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

    [local]
    ;
    ; Master context for local, toll-free, and iaxtel calls only
    ;
    ignorepat => 9
    include => default
    include => parkedcalls
    include => trunklocal
    include => iaxtel700
    include => trunktollfree
    include => iaxprovider
    ;
    ; 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}

    [macro-stdexten];
    ;
    ; 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(u${ARG1})		; 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(b${ARG1})			; 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

    [macro-stdPrivacyexten];
    ;
    ; 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(u${ARG1})		; 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(b${ARG1})			; 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

    [demo]
    ;
    ; 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,${CONSOLE})

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

    exten => 1236,1,Dial(Console/dsp)		; Ring forever
    exten => 1236,n,Voicemail(u1234)		; 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/guest@pbx.digium.com/s@default)	; 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

    ;
    ; 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)

    ;[mainmenu]
    ;
    ; 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
    ;
    ;[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)

    [default]
    ;
    ; 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/${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(u6245)		; Voicemail (unavailable)
    ;exten => 6245,s+1,Hangup			; s+1, same as n
    ;exten => 6245,dial+101,Voicemail(b6245)	; Voicemail (busy)
    ;exten => 6361,1,Dial(IAX2/JaneDoe,,rm)		; ring without time limit
    ;exten => 6389,1,Dial(MGCP/aaln/1@192.168.0.14)
    ;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)
    ;
    ; 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 "show applications" at your
    ; friendly Asterisk CLI prompt.
    ;
    ; 'show application <command>' will show details of how you
    ; use that particular application in this file, the dial plan.
    ;