A working reference for engineers operating NetSapiens® dial plans. This isn’t a deep theoretical guide; it’s the page you keep open in another tab while you build a routing rule and want to confirm the syntax, the order of evaluation, and which pattern to use for which call type.

If you’re debugging an existing rule that isn’t matching, our NetSapiens® dial plan & match rule troubleshooting guide is the companion piece — it covers the five failure modes that catch most engineers. This cheat sheet is the reference for writing new rules cleanly.

Dial plans in 60 seconds

A NetSapiens® dial plan is an ordered list of match rules attached to a tenant (or to a higher-level domain). When a call’s dialed digits are evaluated, the dial plan walks top-down through its rules. The first rule whose match pattern fits the dialed digits wins. That rule’s translation (if any) rewrites the destination digits, and its route directs the call.

That ordering — top-down, first-match-wins — is the single most important thing to internalise. Most routing bugs are precedence bugs.

Match rule anatomy

Every match rule has three jobs:

  1. Match. A digit-string pattern that fits the source dialed digits.
  2. Translate. Optional — rewrite the destination digits before routing.
  3. Route. Point the call at a destination (trunk, user, IVR, queue, external number).

The match and translate steps are where syntax lives. The route step is where the rule is wired into the rest of the platform.

Match pattern syntax

The pattern is a digit string with wildcards. Common building blocks:

  • 1NXXNXXXXXX — fixed 1 + 10 NANPA digits (US/Canada with country code)
  • NXXNXXXXXX — bare 10 NANPA digits (US/Canada without country code)
  • 011* — international prefix followed by any digits
  • * — any digit string (catch-all; use carefully)
  • [1-9]XXXX — first digit 1-9, then any four (5-digit extension range)
  • 911 — exact literal

Where N = any digit 2-9, X = any digit 0-9, * = any sequence of digits. The exact syntax can vary slightly by NetSapiens® version; the dial-plan editor will accept what it accepts.

Translation operators

Translation rewrites the destination digits. The common operators:

  • Strip leading digits. Drop the first N digits from the dialed string.
  • Prepend digits. Insert a fixed prefix at the start (e.g. prepend 1 to a 10-digit NANPA number for E.164 carriers).
  • Replace the entire destination with a fixed string (used for short-codes routing to internal services).

Translation runs after matching, before routing. The route destination receives the translated digits.

Order of evaluation — the precedence rule

The dial plan walks rules top-down. The first match wins. The implications:

  • Specific rules go above generic rules. A rule that matches 911 exactly must sit above a rule that matches *. Otherwise the catch-all absorbs the 911 call.
  • Long patterns generally go above short patterns. A 10-digit NANPA rule (NXXNXXXXXX) should sit above a 4-digit extension rule (XXXX) if you want full numbers to win when both could match a short dialed string. But this isn’t a universal rule — think about which intent should win.
  • One rule should match exactly one call type. If a rule matches several call types, the routing logic gets ambiguous and the post-cutover debugging gets expensive.

When in doubt, write the test case before you write the rule. The dial-plan tester will tell you in seconds which rule is winning a given call.

The seven patterns you build over and over

These are the call types most multi-tenant operators wire into every tenant’s dial plans. Each has a standard pattern.

1. Internal extension dial

Pattern matches a typical extension length (e.g. XXXX for 4-digit extensions). Routes to the user lookup. No translation needed.

2. NANPA outbound (10-digit US/Canada)

Pattern matches NXXNXXXXXX. Translation typically prepends 1 to get to E.164 (1NXXNXXXXXX) before routing to the outbound carrier. Some operators leave the digits alone and let the carrier handle normalisation — depends on the carrier’s expectations.

3. NANPA outbound with leading 1

Pattern matches 1NXXNXXXXXX. No translation. Routes to the outbound carrier.

4. International outbound

Pattern matches 011* (US carrier convention) or matches starting with +. Translation strips the access prefix and replaces with country code formatting expected by the carrier. Routes to the international carrier.

5. Toll-free

Pattern matches 1[8][0-9][0-9]NXXXXXX (8XX patterns) or matches against the toll-free prefix list maintained by your carrier. Often routes to a specific toll-free trunk for billing reasons.

6. 911 / emergency

Pattern matches 911 exactly. Routes through the E911 path with the correct caller location handling. This rule must sit above all generic rules. If a catch-all absorbs 911, you have a serious problem.

7. Inbound DID to user or IVR

Pattern matches the inbound DID exactly (or a range of DIDs). Translation may strip the DID and replace with an internal target. Routes to a user, queue, or IVR.

Common pitfalls

The mistakes we see most often when reviewing dial plans:

  • Greedy wildcard rules placed too high. A * catch-all near the top of the dial plan eats every call below it. Catch-alls belong at the bottom.
  • Precedence inverted between specific and generic. A 10-digit NANPA rule placed below a 1XXX extension range means dialed numbers route into the extension lookup and fail.
  • Translation that strips too much. Stripping a leading 1 on what was actually an extension (14XX) gives nonsense routing. Match the pattern tightly enough that the translation only fires when you want it to.
  • Time-of-day conditions that don’t unwind. A rule that only applies during business hours needs an explicit complement for after-hours, or the call falls through to the next rule (which may or may not be what you want).
  • Untested change pushed live. The dial-plan tester takes seconds. Use it on every change. The cost of a wrongly-routed 911 call vastly exceeds the cost of one minute of testing.

Testing

The NetSapiens® dial-plan tester lets you feed in a sample dialed string from the perspective of a specific tenant or user, and tells you which rule matches and what the translation produces. Use it:

  • Before deploying a new rule, to confirm the intended call matches it.
  • Before deploying a new rule, to confirm common adjacent calls (911, internal extensions, the call type above and below it in the dial plan) still match what they should.
  • When you receive an unexpected-routing ticket, to confirm whether the dial plan is the culprit or whether the issue is downstream (carrier, codec, NAT).

A tested change isn’t always a correct change, but an untested change is almost always a regression in waiting.

What we run for resellers

Dial-plan engineering is one of the highest-frequency operational tasks for NetSapiens® resellers. Routine outbound rate changes, new toll-free additions, IVR menu updates, hunt-group reorganisations, time-of-day overlays for holidays — all of these are dial-plan work, and all of them are easy to break. Our team handles dial-plan changes for resellers as part of white-label Tier 1–4 NetSapiens® support — every change documented, audit-logged, and tested in a staging tenant before it lands in production.

For the broader operational picture, see the NetSapiens® support and operations overview.

Independence and disclosure

VoIP Support Pro is an independent provider of support services for the NetSapiens® platform. We are not affiliated with, endorsed by, or sponsored by NetSapiens® or Crexendo, Inc. NetSapiens® is a registered trademark of Crexendo, Inc. Syntax details in this cheat sheet are accurate to typical NetSapiens® deployments; the platform’s own documentation remains the canonical source for any version-specific behaviour.