VMware ESXi and vSphere Cluster Management

Asterisk Dialplan Pattern Matching Examples

Learn how Asterisk dialplan patterns match dialed extensions with N, Z, X, bracket ranges, literal digits, and the dot wildcard.

An Asterisk dialplan is the call-routing logic that maps dialed extensions or patterns to actions. A dialed extension is the value selected by the caller, such as an internal number or an outside number.

Pattern matching lets one dialplan rule handle multiple possible values. An exact extension matches one specific value, while a pattern extension matches a set of values. A pattern extension always begins with an underscore character.

; Exact extension
exten => 5051,1,NoOp(Match only 5051)

; Pattern extension
exten => _NXXXXXX,1,NoOp(Match a seven-digit local number)

In the first entry, 5051 is literal and matches only that extension. In the second entry, the symbols describe which characters are allowed in each position.

Asterisk Pattern Symbols

Read a pattern from left to right. Literal digits must appear exactly as written. Tokens such as N, Z, and X each consume one character. A bracket expression also consumes one character. The dot wildcard consumes one or more characters after the part that precedes it.

How to Read Patterns from Left to Right

1. Ignore the leading underscore as a marker that tells Asterisk this is a pattern.
2. Identify literal digits. These create a fixed prefix or fixed portion of the value.
3. Count each N, Z, X, or bracket expression as one required character.
4. If the pattern ends in a dot, add at least one more character to the minimum length.

For example, _9ZXXXXXXX begins with a fixed 9. The next position is restricted by Z, and each of the seven X tokens accepts one digit. The fixed prefix narrows the possible values before the variable positions are considered.

Example: NANP-Style Seven-Digit Local Numbers

The pattern _NXXXXXX is commonly used for a North American Numbering Plan (NANP) seven-digit local-number format. NANP is a numbering system in which the first digit of a local seven-digit number is from 2 through 9.

exten => _NXXXXXX,1,NoOp(Match a seven-digit local number)

• N: the first digit must be 2 through 9.
• X X X X X X: the remaining six positions may each be any digit from 0 through 9.
• The pattern requires exactly seven digits total.

Example: A Prefixed Extension Pattern

An access prefix is a leading digit used to select a route, such as an outside-line prefix. The pattern _9ZXXXXXXX demonstrates a literal access prefix followed by a constrained number position.

exten => _9ZXXXXXXX,1,NoOp(Match a 9-prefixed number)

• The first character must be the literal digit 9.
• The second character is Z, so it must be a digit from 1 through 9.
• The remaining seven positions are X tokens and accept any digits from 0 through 9.
• The complete value has nine digits: one 9, one Z, and seven X positions.

Example: Fixed Prefix with a Variable Suffix

The pattern _5051. uses a literal prefix and a dot wildcard.

exten => _5051.,1,NoOp(Match values beginning with 5051)

• 5051 is a required literal prefix.
• The dot requires one or more additional characters after that prefix.
• A matching value must contain at least five characters total: the four literal digits plus at least one suffix character.

The dot is not an optional suffix marker. If the bare value 5051 must also be accepted, define an exact 5051 extension or create another explicit rule.

Example: Digit Range Matching

A bracket expression is a character range or set enclosed in brackets. In _7[1-3], the first digit is fixed and the second digit is selected from an inclusive range.

exten => _7[1-3],1,NoOp(Match extensions 71 through 73)

• 7 must be the first digit.
• [1-3] consumes exactly one second digit.
• The second digit can be 1, 2, or 3.

The matching extensions are 71, 72, and 73. Values such as 70, 74, and 711 do not match this two-character pattern.

A bracket range is more compact than writing separate exact extensions for 71, 72, and 73. Use separate exact entries when those extensions need different routing behavior; use the range when they share the same logic.

Example: Broad Digit-Led Wildcard

The pattern _X. combines one unrestricted digit position with a dot wildcard.

exten => _X.,1,NoOp(Match a multi-character digit-led value)

• X requires the first character to be a digit from 0 through 9.
• The dot requires at least one subsequent character.
• The pattern can therefore match digit strings longer than one digit.
• The pattern is broad and should be used cautiously because many digit-led values can satisfy it.

Pattern Matching Results at a Glance

Safe Dialplan Design

Broad patterns can unintentionally catch calls intended for more specific routing rules. For example, _X. can accept many values, including values that might eventually need a dedicated route. A narrowly defined prefix and fixed length usually makes the intended behavior easier to understand and test.

• Use literal digits and constrained tokens when the numbering plan permits it.
• Avoid a permissive wildcard when a smaller range or fixed length expresses the requirement.
• Place routing logic in the appropriate dialplan context so callers have only the permissions they should have.
• Test both values that should match and values that must not match.
• Start with NoOp() while testing which pattern is selected, then add the actual call-routing applications.

Testing Examples

These entries illustrate pattern syntax without performing a call:

[local]
exten => _NXXXXXX,1,NoOp(Match a seven-digit local number)
exten => _9ZXXXXXXX,1,NoOp(Match a 9-prefixed number)
exten => _5051.,1,NoOp(Match values beginning with 5051)
exten => _7[1-3],1,NoOp(Match extensions 71 through 73)
exten => _X.,1,NoOp(Match a multi-character digit-led value)

Use each pattern in an appropriate dialplan context. Send representative dial strings through that context and verify the expected NoOp() message. Include boundary cases such as a first digit of 1 for _NXXXXXX, a second digit of 0 for _9ZXXXXXXX, the bare value 5051, and the single digit 7 for _X..

Troubleshooting Common Mismatches

Exam-Relevant Notes

• A pattern extension begins with _; an exact extension does not need that marker.
• N means 2-9, Z means 1-9, and X means 0-9.
• A literal digit matches exactly the digit written in that position.
• A bracket expression such as [1-3] matches one digit from the specified range.
• Each single-character token consumes one character.
• A dot matches one or more following characters, so it is not an optional suffix.
• _NXXXXXX requires seven digits and excludes a leading 0 or 1.
• _X. is broad because it accepts any digit first and then any nonempty suffix; do not use it without considering what else it may catch.