VMware ESXi and vSphere Cluster Management

Asterisk Dialplan Pattern Matching

Learn how Asterisk extension patterns use X, Z, N, ranges, and periods to match internal extensions, number ranges, and variable-length dialed numbers.

Asterisk dialplan patterns let one extension definition handle multiple dialed numbers. Instead of writing the same call flow separately for 950, 951, 952, and every other number in a range, you can describe the shared numbering rule once.

A dialplan is Asterisk's call-routing logic: it maps a dialed extension to ordered application steps. An extension can be a dialable identifier or a dialplan entry that triggers call-processing instructions. A context is a named group of extensions that controls which routing rules are available to a channel.

Pattern matching is useful for internal extension blocks, number ranges, outbound dialing rules, and numbering plans that allow variable-length numbers. It reduces duplication, but patterns should be as restrictive as the numbering plan requires.

Literal Extensions and Pattern Extensions

A literal extension is written exactly as the identifier it should match. For example, 950 represents that specific extension. If every number from 950 through 959 needs the same call flow, defining all ten extensions separately repeats configuration.

An extension pattern begins with an underscore. The underscore tells Asterisk that the extension identifier contains matching tokens rather than being a literal name.

exten => 950,1,Answer()       ; literal extension
exten => _95X,1,Answer()     ; extension pattern

Extension identifiers can contain more than numeric digits. The tokens described here are intended for numeric dialing, where each token represents one or more positions in a dialed value.

Pattern Tokens

Fixed digits in a pattern must match exactly. In _95X, the first character after the underscore must be 9, the second must be 5, and the third must satisfy X.

A bracket range such as [3-6] contributes one character position. The range is inclusive, so it accepts 3, 4, 5, and 6, but not 2 or 7.

The X, Z, and N tokens are all single-character wildcards with different allowed digit sets. X allows zero, while Z excludes zero and N excludes both zero and one.

Exact-Length Matching

A pattern made only from fixed digits and single-character tokens has an exact length. The pattern _95X contains two fixed digits and one X position, so it matches exactly three-digit values beginning with 95.

• 950, 955, and 959 match.
• 95 does not match because it is too short.
• 9555 does not match because it is too long.
• 960 does not match because its second digit is not 5.

Variable-Length Matching with a Period

The period token matches one or more characters. Appending it changes an exact prefix pattern into a variable-length pattern.

_95X.

This pattern still requires 9, then 5, then one digit for X. It additionally requires at least one character after that X position. Therefore, 950 does not match, but 9500 does. The period is not the same as X: X consumes exactly one digit, while the period consumes one or more characters.

Use a period only when the dialing plan genuinely permits an indeterminate trailing portion. A broad variable-length pattern can match destinations that were not intended to use the route.

Replacing Repetitive Dialplan Entries

Suppose extensions 950 through 959 should all answer, play the same prompt, and hang up. The repetitive approach defines the same application sequence for each literal extension:

[local]
exten => 950,1,Answer()
 same => n,Playback(hello-world)
 same => n,Hangup()

; Repeat the same call flow separately for 951 through 959.

The repeated definitions handle the required numbers, but every future change must be made in multiple places. A single pattern expresses the numbering rule and the shared behavior:

[local]
exten => _95X,1,Answer()
 same => n,Playback(hello-world)
 same => n,Hangup()

This pattern accepts 950 through 959 because X accepts every digit from 0 through 9. The same Answer(), Playback(), and Hangup() flow applies to every matching extension.

Dialplan Syntax in Context

Pattern extensions are placed inside a named context. An exten declaration has three important parts: the extension or pattern, the priority, and the application.

exten => extension-or-pattern,priority,application(arguments)

In the example, _95X is the pattern, 1 is the first priority, and Answer() is the application. Priorities determine the order of operations. The same => n form means “continue with the next priority for the same extension.”

• Answer() answers the incoming channel.
• Playback(hello-world) plays the hello-world audio prompt.
• Hangup() ends the call.

For a variable-length route, the context can contain:

[local]
exten => _95X.,1,Answer()
 same => n,Playback(hello-world)
 same => n,Hangup()

More Pattern Examples

Restricting the First Digit with a Range

_[3-6]00

This matches 300, 400, 500, and 600. It does not match 200, 700, or 3000. The bracket expression supplies exactly one digit, followed by two literal zeros.

Using N and Z

_NXX
_ZXX

In _NXX, the first digit must be 2 through 9, while the next two digits may be any digits. In _ZXX, the first digit must be 1 through 9, so 0 is excluded but 1 is allowed.

Pattern Design Guidance

• Choose the most restrictive pattern that satisfies the intended numbering plan.
• Use literal prefixes to identify the intended destination block.
• Use N, Z, or bracket ranges when only some digits are valid.
• Use variable-length matching only when additional trailing characters are genuinely allowed.
• Test valid boundary values and invalid near-matches before deployment.
• Review broad patterns carefully, especially patterns ending in a period, because they can route unintended destinations.

Troubleshooting Pattern Matches

An Expected Number Is Rejected

Check whether the dialed value has exactly three characters and begins with 95. The pattern _95X does not accept a shorter or longer value, and it does not accept a different prefix. Use an exact-length pattern only for three-digit values; select another pattern if the numbering plan allows another length.

A Four-Digit Value Does Not Match

_95X accounts for only three positions. Count the two literal digits and the one X position. If a four-digit value such as 9555 is valid, use _95X. only when the additional trailing portion is part of the intended route.

A Pattern Matches Too Many Destinations

A broad wildcard, particularly a trailing period, may be permitting unintended values. List representative valid and invalid dial strings, then compare each character with the pattern. Narrow the pattern with fixed digits, N, Z, or bracket ranges where possible.

The Extension Is Treated as a Literal

If an entry such as 95X is interpreted as a literal name, inspect the characters before the comma and priority. The initial underscore is required: write _95X.

A Range Fails at a Boundary

Test both endpoints and values immediately outside them. For _[3-6]00, test 300 and 600 as valid boundaries, then 200 and 700 as invalid outside values. Correct the bracket expression if the written range does not describe the intended inclusive set.

Exam- and Deployment-Relevant Notes

• The underscore marks a pattern; without it, the identifier is treated as a literal extension name.
• X matches exactly one digit from 0 through 9.
• Z matches exactly one digit from 1 through 9.
• N matches exactly one digit from 2 through 9.
• [3-6] matches one digit in the inclusive range 3 through 6.
• A fixed-digit and single-token pattern has an exact length.
• A period matches one or more characters and changes the length behavior of the pattern.
• Pattern matching reduces duplicated dialplan code, but overly broad patterns can create unintended routes.

For related study, see Asterisk pattern matching.