Number Plan Regex Mapping for Complex International E.164 Dial Strings

How-To-Articles
1

Number Plan Regex Mapping for Complex International E.164 Dial Strings

Executive Summary & Architectural Context

Contact centers rarely operate in a single country. When an agent in the United States attempts to transfer a call to a supplier in Germany, they naturally dial 011 49 151 XXXXXXXX (the US international exit code 011, plus the German country code 49). However, if that Genesys Cloud environment is terminating its SIP traffic via an Edge in Frankfurt, the local German carrier expects the number as 00 49 151... or strictly +49151....

If the dial string doesn’t perfectly match the carrier’s expectation, the SIP INVITE fails with a 404 Not Found or 484 Address Incomplete.

The architectural solution in Genesys Cloud is the Number Plan. A Number Plan acts as a regex-driven translation layer. It intercepts whatever digits the human agent types, sanitizes them, normalizes them to a global E.164 standard, and passes the normalized string to the Outbound Route. This masterclass details how to construct non-trivial Regex logic to handle complex international dialing translations.

Prerequisites, Roles & Licensing

  • Licensing: Available on all Genesys Cloud CX tiers.
  • Roles & Permissions: Telephony > Number Plan > Edit.
  • Platform Dependencies:
    • An understanding of the exact digit format required by your outbound SIP carrier.

The Implementation Deep-Dive

1. The Goal of E.164 Normalization

E.164 is the international standard for phone numbers. It dictates that every number should begin with a +, followed by the country code, followed by the subscriber number, with no spaces or hyphens. Maximum 15 digits.
Example: +442071838750.

If your Number Plan successfully normalizes all agent input into strict E.164, your Outbound Routes only ever have to match one pattern (^+), drastically simplifying your routing table.

2. Building the Number Plan

Navigate to Admin > Telephony > Sites (or Number Plans if managing globally). Add a new Number Plan.

Scenario A: The North American “Forgetful” Agent

Agents in the US frequently forget to dial the 1 for long distance. They just type 312-555-0199.

  1. Match Type: Regular Expression
  2. Match Expression: ^([2-9]\d{2}[2-9]\d{6})$
    • Logic: This looks for exactly 10 digits, ensuring the area code doesn’t start with a 0 or 1.
  3. Normalized Number: +1$1
    • Logic: We explicitly add the +1 prefix, and append $1 (the captured 10 digits from the regex).

Scenario B: The International Exit Code (011)

US agents are trained to dial 011 for international calls.

  1. Match Type: Regular Expression
  2. Match Expression: ^011(\d{7,15})$
    • Logic: This looks for 011 at the start of the string, followed by 7 to 15 digits (the country code + subscriber number). It captures everything after the 011 in group $1.
  3. Normalized Number: +$1
    • Logic: We strip the 011, insert a +, and append the rest of the number. The string 011442071838750 instantly becomes +442071838750.

Scenario C: The European “Double Zero” Exit Code

European agents are trained to dial 00 for international calls.

  1. Match Type: Regular Expression
  2. Match Expression: ^00(\d{7,15})$
  3. Normalized Number: +$1

Scenario D: National Dialing in the UK

A UK agent dialing a local mobile number will dial 07700 900077.

  1. Match Type: Regular Expression
  2. Match Expression: ^0([1-9]\d{8,9})$
    • Logic: UK national numbers start with a 0. The actual subscriber number follows. We want to drop the leading 0, capture the rest, and prepend the UK country code.
  3. Normalized Number: +44$1

3. Assigning the Number Plan

Number Plans must be assigned to the specific Site where the agents physically sit (or where their phones are logically anchored).

  1. Go to the Site configuration.
  2. Select the Number Plans tab.
  3. Add your custom plans.
  4. Ordering is Critical: Genesys Cloud evaluates Number Plans from top to bottom. Place your highly specific Regex matches (like the UK local dial string) at the top, and your generic global matches (like an explicit ^+ match) at the bottom.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Internal Extension Clashes

If your company uses 4-digit internal extensions (e.g., 4000), and your Number Plan has a poorly written Regex like ^4\d{3}$ that normalizes it to a public E.164 number (+18005554000), agents will be unable to dial each other internally.

  • Solution: Always use the Extension match type for internal dialing, and ensure the Extension Number Plan is placed above any generic Regex plans in the Site evaluation order.

Edge Case 2: The E.164 Carrier Requirement

While standardizing on E.164 is a best practice inside Genesys Cloud, some legacy SIP carriers will actively reject a SIP INVITE if the Request-URI contains a +.

  • Troubleshooting: If you normalized everything to +44207..., but your carrier requires 0044207..., the call will fail with a 404.
  • Solution: Do not change your Number Plan. The Number Plan’s job is internal normalization. To fix the carrier issue, you must go to the Outbound Route or the Trunk settings, and configure the Calling Details translation to explicitly strip the + and prepend the 00 right before the packet leaves the Edge.

Official References