Designing International Toll-Free Number (ITFN) Routing Tables for Global Inbound Access

How-To-Articles
1

Designing International Toll-Free Number (ITFN) Routing Tables for Global Inbound Access

What This Guide Covers

This guide details the architectural patterns for configuring International Toll-Free Number (ITFN) routing in Genesys Cloud CX to ensure seamless inbound access across multiple jurisdictions. You will configure routing policies that dynamically resolve caller location, bypass geographic restrictions, and apply region-specific compliance logic. The end result is a resilient telephony architecture where a single global number or a set of regional ITFNs routes callers to the correct skill-based agents without requiring manual intervention or exposing the caller to cross-border surcharges.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 1, 2, or 3 with Telephony enabled. ITFNs are part of the standard telephony package but require Global Calling add-on for certain international destinations.
  • Permissions:
    • Telephony > Trunk > Edit
    • Telephony > Number > Edit
    • Routing > Queue > Edit
    • Routing > Flow > Edit
  • External Dependencies:
    • A supported ITFN provider (e.g., Bandwidth, Twilio, or Genesys native ITFN partners).
    • Regulatory approval for the target jurisdictions (e.g., FCC registration for US/Canada, Ofcom for UK).
  • Knowledge Base Assumptions: Familiarity with Architect flow construction, JSONata expressions, and SIP trunk provisioning.

The Implementation Deep-Dive

1. Provisioning and Validating ITFN Inventory

The foundation of international routing is the correct provisioning of numbers. Unlike local DIDs, ITFNs (such as +800, +808, +809) are virtualized resources that do not map to a physical switch location. They require a “home” jurisdiction for billing and regulatory purposes, even though the call can originate globally.

Architectural Reasoning:
You must select the “home” jurisdiction carefully. If you provision a +800 number with a US home jurisdiction, the carrier will attempt to bill the US entity for the termination. If the call originates in a country that does not support US-based ITFN termination (e.g., certain parts of Africa or South America), the call will fail at the carrier level, not at the Genesys level.

Configuration Steps:

  1. Navigate to Admin > Telephony > Numbers.
  2. Click Add Number.
  3. Select International Toll-Free as the number type.
  4. Choose the specific ITFN prefix (e.g., +800).
  5. Select the Home Country. This is the critical decision point.
    • Recommendation: Use the country with the largest expected call volume or the primary legal entity for billing.
  6. Assign the number to a Trunk that supports international traffic.

The Trap: The “Home Country” Mismatch
A common misconfiguration is provisioning a +800 number with a US home country and expecting it to work for callers in Brazil. Many Brazilian carriers do not support US-based +800 termination. The call will drop immediately with a 488 Not Acceptable Here or 503 Service Unavailable response.
Mitigation: Before provisioning, consult the carrier’s ITFN support matrix. If you require global reach, you must provision separate ITFNs for different regions (e.g., a +800 for Americas, a +808 for Europe/Asia) and use DNS-based or SIP-header-based routing to direct callers to the appropriate number.

2. Designing the Routing Flow for Geographic Resolution

Once the numbers are provisioned, you must design the Architect flow to handle the inbound call. The core challenge with ITFNs is that the from address in the SIP INVITE may not accurately reflect the caller’s physical location, especially if the caller is using a mobile network that masks the origin.

Architectural Reasoning:
You cannot rely solely on the from number for routing logic. Mobile roaming and VoIP services often obscure the true geographic origin. You must use a combination of the from number’s country code and the via headers in the SIP INVITE to determine the caller’s region. This allows you to apply region-specific compliance rules (e.g., recording consent) and routing strategies (e.g., routing to local agents to reduce latency).

Configuration Steps:

  1. Create a new Architect Flow.
  2. Add a Set Data block to capture the caller’s country code.
    • Use the expression: getFromNumber().substring(0, 3) to extract the country code.
  3. Add a Condition block to branch based on the country code.
    • Example: if (countryCode == '+1') { route to US Queue } else if (countryCode == '+44') { route to UK Queue }
  4. Add a Set Data block to capture the caller’s region for compliance.
    • Use the expression: getFromNumber().substring(0, 2) to extract the country prefix.

The Trap: Relying on from Number for Mobile Callers
Mobile callers often have a from number that does not match their current location. If a US traveler calls from the UK, their from number may still be +1. If you route based solely on the from number, you will route them to a US agent, potentially incurring high international charges for the agent side and failing to provide local language support.
Mitigation: Use the via headers in the SIP INVITE to determine the caller’s location. The via header contains the IP address of the caller’s carrier, which can be geolocated. However, this requires advanced parsing in Architect. A simpler approach is to use a Geolocation API to determine the caller’s location based on the from number’s carrier information.

3. Implementing Region-Specific Compliance Logic

International calls are subject to varying privacy laws. The European Union’s GDPR, for example, requires explicit consent for call recording. The US has varying state laws, with some requiring one-party consent and others requiring all-party consent.

Architectural Reasoning:
You must implement a compliance check early in the flow, before any recording begins. This check must be dynamic, based on the caller’s determined location. If the caller is in a region that requires consent, you must play a consent message and wait for a response. If the caller does not consent, you must disable recording for the duration of the call.

Configuration Steps:

  1. Add a Condition block after the geographic resolution.
  2. Check if the caller’s region requires consent.
    • Example: if (region == 'EU') { require consent }
  3. If consent is required, add a Play Prompt block with a consent message.
  4. Add a Collect Input block to wait for the caller’s response.
    • Configure the block to accept a single digit (e.g., 1 for yes, 2 for no).
  5. Add a Condition block to branch based on the response.
    • If 1, continue to the queue.
    • If 2, set a variable recordingDisabled = true and continue to the queue.
  6. In the Queue configuration, set the Recording option to Conditional.
    • Use the expression: if (recordingDisabled == true) { no } else { yes }

The Trap: Hardcoding Consent Logic
A common misconfiguration is hardcoding the consent logic for a single region. If you expand your business to a new region with different compliance requirements, you must update the flow. This is error-prone and time-consuming.
Mitigation: Use a Data Table or External API to store the compliance requirements for each region. This allows you to update the compliance logic without changing the flow.

4. Configuring Queue Routing for International Agents

International agents must be available to handle calls from their respective regions. You must configure the queue to route calls to agents based on their skill set and availability.

Architectural Reasoning:
You must use Skill-Based Routing to ensure that callers are routed to agents who speak their language and are familiar with their regional regulations. You must also use Time Zone Awareness to ensure that agents are available during the caller’s business hours.

Configuration Steps:

  1. Create a Queue for each region.
  2. Add Skills to the queue (e.g., English-US, French-FR).
  3. Assign Agents to the queue based on their skills and availability.
  4. Configure the Routing Strategy to Longest Idle Agent.
  5. Configure the Wrap-Up Time to ensure that agents have time to complete post-call tasks.

The Trap: Ignoring Time Zone Differences
A common misconfiguration is ignoring time zone differences. If you route a call from the US to an agent in the UK, the agent may be asleep. This results in long wait times and poor customer experience.
Mitigation: Use Time Zone Awareness in the queue configuration. Configure the queue to only route calls to agents who are available in the caller’s time zone.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Carrier-Level Blocking of ITFNs

The Failure Condition:
The call fails with a 488 Not Acceptable Here or 503 Service Unavailable response. The caller hears a fast busy signal or a recording stating that the number is not available.

The Root Cause:
The carrier in the caller’s country does not support the ITFN prefix. For example, a caller in Japan may not be able to reach a US-based +800 number.

The Solution:
Provision a separate ITFN for the caller’s region. Use DNS-based routing to direct the caller to the appropriate ITFN. If DNS-based routing is not possible, use a SIP Header to identify the caller’s region and route the call to the appropriate ITFN.

Edge Case 2: Mobile Roaming Masking

The Failure Condition:
The caller is routed to the wrong region. For example, a US traveler calling from the UK is routed to a US agent.

The Root Cause:
The from number in the SIP INVITE is the caller’s home number, not their current location. The Architect flow routes based on the from number.

The Solution:
Use the via headers in the SIP INVITE to determine the caller’s location. The via header contains the IP address of the caller’s carrier, which can be geolocated. If geolocation is not possible, use a Geolocation API to determine the caller’s location based on the from number’s carrier information.

Edge Case 3: Compliance Violations

The Failure Condition:
The call is recorded without the caller’s consent. This results in a compliance violation and potential legal liability.

The Root Cause:
The compliance logic is not dynamic. The flow does not check the caller’s region before recording.

The Solution:
Implement a dynamic compliance check in the Architect flow. Use a Data Table or External API to store the compliance requirements for each region. If the caller is in a region that requires consent, play a consent message and wait for a response. If the caller does not consent, disable recording for the duration of the call.

Official References