Asterisk Dialplan Patterns

Extension Names and Patterns

Warning

Do not use a pattern of _. as this will match everything including Asterisk special extensions like i, t, h, etc. Instead use something like _X. or _X which will not match __special__ extensions..

If, for some reason, you simply must use _. temporarily because nothing else will work, then turn on debugging and watch the CLI while a call is passing through that context, so you can see what the actual extension is. Then rewrite the context to either use that extension directly in place of _. or use a pattern that will catch that extension. As a last resort, if you don't need to preserve the extension, you may be able to use two contexts to get rid of the ambiguity (which still has some risk, but limits the time of exposure):

   [unknownextension]
   exten => _.,1,Goto(itmatches,s,1)
   .....
   [itmatches]
   exten => s,1,NoOp(Now using s extension)
   .....

Extension Names

Dialplan extensions can be simple numbers like "412" or "0". They can be alphanumeric names like "john" or "A93*". Although a typical telephone can't dial an extension called "john" (some can though), often your Dialplan logic will involve jumping from one extension to a different extension, and for those jumps you may define exension names with any name you like, as you don't wish them to be dialed directly.

Of course, touchtone telephones don't just have the digits 0 through 9, they also have * (star) and # ("pound" or "hash", depending on where in the world you live). And some touchtone (DTMF) telephones have the extra four "digits", A, B, C and D. If you have such handsets within your organization, there's nothing stopping you making use of those extra buttons for some special purpose of your own.

Note: To have an extension that is triggered by dialing the # symbol, you must use an extension pattern (see below). Asterisk does not recognize # as an ordinary 'digit', even though it appears on all DTMF telephones.

"Why do people in the US call the # symbol pound?" It doesn't seem to have anything to do with either money (e.g. the UK Pound Sterling) or with weight (lb).
Answer: Pound Sign

Extension Patterns

Extension names are not limited to single specific extension "numbers". A single extension can also match patterns. In the extensions.conf file, an extension name is a pattern if it starts with the underscore symbol (_). In an extension pattern, the following characters have special meanings:

Special Characters for Pattern Matching

   X          matches any digit from 0-9
   Z          matches any digit from 1-9
   N          matches any digit from 2-9
   [1237-9]   matches any digit or letter in the brackets
              (in this example, 1,2,3,7,8,9)
   [a-z]    matches any lower case letter (introduced in which Asterisk version?)
   [A-Z]    matches any UPPER case letter (introduced in which Asterisk version?)
   .          wildcard, matches one or more characters
   !          wildcard, matches zero or more characters immediately
              (only Asterisk 1.2 and later, see note)

Note: The exclamation mark wildcard, which is available only in Asterisk 1.2 and later, behaves specially — it will match as soon as can without waiting for the dialling to complete, but it will not match until it is unambiguous, and the number being dialled cannot match any other extension in the context. It was designed for use as follows, so that as soon as the digits dialled don't match '001800...' the outgoing telephone line will be picked up and overlap dialling will be used (with full audio feedback from 'earlyb3' etc.)

  Context "outgoing":
    Extension         Description
    _001800NXXXXXX    Calls to USA toll-free numbers made by VoIP
    _X!               Other calls via normal telco, with overlap dial.

Example

Consider the following context:

   Context "routing":
     Extension   Description
    _61XX        Dallas Office
    _63XX        Dallas Office
    _62XX        Huntsville Office
    _7[1-3]XX    San Jose Office
    _7[04-9]XX   Los Angeles Office

This context, given the name "routing", sends calls to various servers according to their extension. This organization has decided that all of their telephone extensions will be 4 digits long. If a user dials an extension beginning with 61 or 63, it would be sent to the Dallas office; 62 would go to the Huntsville office; anything starting with 71, 72, or 73 would go to San Jose, and anything starting with 70, 74, 75, 76, 77, 78 or 79 would go to the Los Angeles office.

More Example Patterns

   _NXXXXXX        matches a NANP 7 digit telephone number such as 555-1212
   _1NXXNXXXXXX    matches an area code and phone number preceeded by a one such as 1-860-555-1212
   _9011.          matches any string of at least five characters that starts with 9011,
                   but it does not match the four-character string 9011 itself.
   _9011!          matches 9011 too
   _#              matches a single # keypress

So what do you use instead of _. ? Many examples use this construct, but if you use it you may see a warning message in the log advising you to change _. to _X. But simply replacing _. with _X. doesn't always work, depending on the extension coming into the context. Usually ONE of the following will work in Asterisk 1.2 and later:

   _X!          matches any numeric pattern of one or more digits (but not * or #)
   _[*#0-9]!    same as previous entry but also includes * and # characters
   _[*0-9]!     same as the previous entry except excludes the # character
   s            if there is no pattern at all, then using s will often match

The s pattern can be useful for incoming calls where no DID is available and in certain other situations where the extension matches nothing.

Or, you can use a user defined pattern. Let's say you are jumping from one context to another and there is no particular reason to use a numeric pattern. You could use a statement like Goto(voicemail,s,1) and then use the s extension in the target context, which is perfectly valid. But, if you want to make your dial plan a little more readable (or for some other reason don't want to use s), you could instead do Goto(voicemail,vm,1) and then in the voicemail context actually use the vm extension, like this:

   [voicemail]
   exten => vm,1,NoOp(Entering Voicemail Context)
   .....

If, for some reason, you simply must use _. temporarily because nothing else will work, then turn on debugging and watch the CLI while a call is passing through that context, so you can see what the actual extension is. Then rewrite the context to either use that extension directly in place of _. or use a pattern that will catch that extension. As a last resort, if you don't need to preserve the extension, you may be able to use two contexts to get rid of the ambiguity (which still has some risk, but limits the time of exposure):

   [unknownextension]
   exten => _.,1,Goto(itmatches,s,1)
   .....
   [itmatches]
   exten => s,1,NoOp(Now using s extension)
   .....

Example URI dialing

[uri]
exten => _[a-z].,1,Macro(uridial,${EXTEN}@${SIPDOMAIN})
exten => _[A-Z].,1,Macro(uridial,${EXTEN}@${SIPDOMAIN})
exten => _X.,1,Macro(uridial,${EXTEN}@${SIPDOMAIN})

Now add the macro below into the extensions.conf in the area where you have your other macros defined:

[macro-uridial]
exten => s,1,NoOp(Calling remote SIP peer ${ARG1})
exten => s,n,Dial(SIP/${ARG1},120,tr)
exten => s,n,Congestion()

Asterisk splits everything past the “@” in the call and makes an ${EXTEN} variable and a ${SIPDOMAIN} variable. If we match an lowercase alpha character in the ${EXTEN} then we simply just dial the EXTEN@SIPDOMAIN and away you go!

Sort Order

If more than one pattern matches a dialed number, Asterisk may not use the one you expect. See:

Sort Order of Extension Patterns