Asterisk Extension Matching

Dialplan Extension Matching

"Match As You Go" dialing occurs in three situations:

  1. Interactive Voice Response (IVR) menus. This is the name given to any situation where Asterisk has answered a call and has (probably) played some tone or recorded message, and is now waiting for the user to dial digits on their keypad to select an option.
  2. Asterisk Disa (DISA). This is the application that will allow you to authenticate a user and then drop you into a context and wait for extensions, after authentication asterisk will behave (to the caller) exactly as it would to a standard telephone handset.
  3. standard telephone handsets connected by FXS interfaces. This is the situation where you lift an ordinary telephone handset, get a dialtone, and you start dialing digits. However, this does not usually apply in the case of FXS interfaces on an ATA — in this case the ATA has its own rules for collecting the number and Asterisk does not see digits "as you go" but only once the ATA has decided to send the entire dial string.

What is "Match As You Go" Dialing?

Consider a traditional landline telephone connected to your local exchange. When you lift the handset and start to dial, each digit is sent to the exchange immediately, and is processed immediately ("match as you go"). In contrast, consider the typical cell phone: you type the telephone number in, but it is only when you press the Send button that the telephone sends the number, all at once, to the exchange.

Once the call has been connected through, however, both types of telephones work the same way as far as any additional dialing goes. If, for example, you dial a company and are greeted by a voicemail system, any digits you dial — whether you're using a cell phone or an ordinary landline phone — are sent as you dial them, "match as you go" style.

For Asterisk, the "all at once" style of dialing is easy to process: Asterisk just checks whether the number dialed matches any of the extension patterns defined in the current Dialplan context. In contrast, "match as you go" is a little harder because it's not clear when you have finished dialing. On the one hand, you don't want Asterisk to wait around; you want it to process the number as soon as it can. But on the other hand, Asterisk might have to wait around if dialing more digits is going to affect how it handles your call.

Understanding how "match as you go" dialing is processed may be helpful for you in deciding how you allocate your extension numbers and how you define the extension patterns used to process dialed numbers.

How Asterisk Processes "Match As You Go" Dialing

When Asterisk is having to process a dialed number, the first thing Asterisk considers is: If you (the caller) were to dial another digit, would there be any extension patterns that could possibly match that number? Asterisk considers the number you've dialed so far and looks at the extension patterns defined for the context. If the answer to the question is yes, then Asterisk will wait to see whether you do indeed dial another digit — even if there is already a "complete" telephone number that matches what you've already dialed.

For example, let's say that you have

exten => 123,1,DoSomething(...)

exten => _XXX.,1,DoSomethingElse(...)

If you were to dial "123", Asterisk would wait to see if you dial another digit, because it is not clear whether you want extension 123 or, for example, extension 123999, which would match the second pattern defined.

Asterisk will check all the extension patterns defined for the current context — both the patterns defined directly in the current context as well any patterns defined in any contexts included using the include keyword. If there is at least one extension pattern that, if you did dial another digit, might match that number, then Asterisk will wait.

How long will Asterisk wait?

How long Asterisk will wait for more digits, before giving up and processing the number as dialed so far, depends on two factors. First of all, it depends on whether this is a new incoming connection or an established connection.

  • New incoming connections are those where Asterisk has not started processing any Dialplan commands for the call yet. For Zap channels, this means that someone has lifted the handset and started dialing a number, and Asterisk is processing each digit as the user dials it, to determine which extension in the Dialplan to go first.

    • For new incoming connections, the second factor affecting how long Asterisk waits for more digits before giving up is the type of channel that the call is coming in on. Each channel type determines its own timeout period. The Zap channel has a fixed timeout period of 3 seconds, and this can not be changed without modifying the source code and recompiling the Zap module (look for the variable 'matchdigittimeout' in asterisk/channels/chan_zap.c).

  • Established connections are those where Asterisk has already handled the initial connection, has jumped to an extension (even if just the s extension), has started processing commands there, has "run out of" commands to process, and is now waiting for the caller to dial something. Typically, one of the commands Asterisk will have just executed is the Background command to play a recorded message presenting an IVR menu, and Asterisk is now waiting for the caller to dial their menu chioce.

    • For established connections, the second factor affecting the timout period is the DigitTimeout value. The default digit timeout value is 5 seconds, but this can be changed using the DigitTimeout command.

What Does Asterisk Do Next?

  • (a) Asterisk waited for more digits but didn't get any within the timeout period, or
  • (b) Asterisk did not find any extension patterns that, if you were to dial more digits, could match your number,
then Asterisk will consider the question: does the number you have dialed currently match any extension patterns in the current context or any included contexts?

Yes: Jump to the first matching extension. More than one extension pattern may match the number dialed; Asterisk simply takes the first match it finds.

(:exclaim:) Asterisk does not consider the extension patterns in the order that you define them. So the "first match" might not be what you expect. See Sort Order of Dialplan Extension Patterns.

No: If the number you have dialed is invalid in the current context, then what action Asterisk takes depends on which of two situations it is in:

1. If this is a new, incoming connection, then Asterisk will return an appropriate "invalid number" signal to the caller. How this signal is sent depends on the channel type; if it is a Zap channel, you'd hear a congestion tone. For VOIP channels, Asterisk would send an appropriate control signal to the caller, and their telephone equipment will indicate the invalid number in whatever way they do it: they might display the message "invalid number" on a screen, or make some particular sound. Note that in this situtation — a new, incoming connection — no Dialplan commands have yet been executed. You have no scripting control over the behavior of Asterisk in how it handles an invalid number; Asterisk does not jump to the i extension in this situation.

2. If, on the other hand, this is an established connection — Asterisk has jumped to an extension, started executing commands (e.g. playing a recorded message giving the user a set of IVR menu options), and has "run out of" commands, and so is waiting for the user to dial something (e.g. to select a menu option), then dialing an invalid number will cause Asterisk to jump to the i extension, if it exists. If the i extension is not defined in that context, Asterisk will hang up.


FooBar Incorporated wants their incoming telephone calls to be answered with a voice message welcoming the caller and inviting them to choose which extension they want. FooBar has six telephone extensions. Their extension numbers are 1, 2, 21, 22, 31, 32. So this is the context created for incoming calls for FooBar Incorporated:

exten => s,1,Background(welcome-to-foobar-incorporated)
exten => 1,1,Dial(Zap/1)
exten => 2,1,Dial(Zap/2)
exten => 21,1,Dial(Zap/3)
exten => 22,1,Dial(Zap/4
exten => 31,1,Dial(Zap/5)
exten => 32,1,Dial(Zap/6)

When you call FooBar, Asterisk plays the "welcome-to-foobar-incorporated.gsm" sound file. After that, having run out of commands to execute, it waits for you to dial something. This is what Asterisk would do if you dialed various options:

Number Dialed Asterisk's Action
1 Immediately performs Dial (Zap/1)
2 Waits for timeout, then performs Dial(Zap/2)
21 Immediately performs Dial (Zap/3)
22 Immediately performs Dial (Zap/4)
3 Waits for timeout, then hangs up.
31 Immediately performs Dial (Zap/5)
32 Immediately performs Dial (Zap/6)
4 Immediately hangs up.

Note that when a caller tries to dial extension 2, they are not connected immediately. Asterisk waits to see if the caller dials more digits, to determine whether the caller wants extension 2 or 21 or 22. As callers would like to be connected immediately if possible, it would be more user-friendly to avoid using ambiguous extension numbers.

If FooBar Incorporated doesn't want callers to be disconnected if they dial an invalid number, then they need to define an "i" extension for this context. At the same time, they should consider adding a t extension too.

(:question:) How does overlap dialing fit in here?

See Also

Asterisk | Asterisk Configuration | The Dialplan - extensions.conf
Created by: JazEzork, Last modification: Tue 26 of Dec, 2006 (18:08 UTC) by ott1309
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+