Getting started with 8x8 Geo Routing

The 8x8 Geo Routing application lets you route incoming calls by area code across your 8x8 Work PBXs and 8x8 Contact Center tenants. This article covers how to install the portal and configure geo routing for 8x8 Work and Contact Center.

Applies to

• 8x8 Work (PBX): Admins

• 8x8 Contact Center: Admins

• 8x8 Geo Routing & Call Blocking portal

Before you begin

You must install the Geo Routing & Call Blocking from the 8x8 App Store before you can use the portal. Installing the app enables access for your account and provisions your account automatically.

1. Open the 8x8 App Store at https://appstore.8x8.vc/. You can also reach it from your 8x8 Admin Console.

2. Find and open the Geo Routing & Call Blocking application tile in the PS container.

3. Click Install App.

4. Read and accept the Terms and Conditions.

5. Click Install.

6. Select the default access:

   • No Access: Only administrators will have access to the applications.

   • All Scopes: All users will have access to the applications.

   • Selected Scopes: Only the users or groups you choose will have access to the applications.

7. After configuring access, you are returned to the Geo Routing & Call Blocking application page. Click the Open App button.

8. When prompted, authorize the app with your token. This connects the app to your account and provisions your account.

Once installation is complete, open the portal and continue with the steps in the next sections of this article.

Note

If the portal tells you that you do not have access, confirm the app is installed from the App Store. Access is granted as part of installation.

Navigate the portal

• Choose the feature you want to configure from the navigation: 8x8 Work Geo Routing or 8x8 Contact Center Geo Routing.

• Use the list on the left to pick the PBX (8x8 Work) or Tenant (Contact Center) you want to configure.

• Each page includes a collapsible Help & How to use section with a quick reference.

Note

Depending on your plan, geo routing may be limited (for example, 10 geo routing entries). When you reach the limit, a banner appears with an option to request an upgrade. Contact your 8x8 representative to unlock unlimited entries.

8x8 Work Geo Routing

This application routes calls to an extension or external number based on the caller’s area code.

Note

8x8 must enable your tenant and extension for this solution before you begin.

Step 1: Configure your geo-routing extension

Before you can add any area-code entries, you must set up a geo-routing extension. This extension is the entry point that triggers area-code-based routing.  

1. Select your PBX from the list on the left.

2. Click Configure geo-routing extension.

3. Fill in the following fields:    

   • Geo-Routing Extension: the extension that triggers geo routing when called (for example, 1000). Must be alphanumeric only.

   • Default Extension/Forward Number: the fallback destination used when no area code matches (for example, 2000 or +15551234567).

4. Click Enable Geo-Routing. The system deploys this configuration to your PBX.

Note

You cannot create or rename an entry with the area code DEFAULT. The default destination is managed in the configuration, not as a regular entry.

Step 2: Add area code entries

1. Click + Create Entry.

2. Enter the Area Code and the Forward Number / Extension the call should route to.

3. Click Save.

Tip

A plain 3-digit area code (for example, 415) works exactly as before. To route by country code — or any custom pattern — enter a regular expression instead. For example, ^44.* matches any caller from the UK (country code 44), regardless of the rest of the number. A regex is matched against the caller's full number, so include an end anchor ($) or wildcard (.*) to control how much of the number must match — a bare ^44 with no end anchor can match more than intended.

Edit or delete entries

• To edit an entry, click the pencil icon, change the values, and click Save. 

• To delete an entry, click the trash icon and confirm.

Bulk upload by CSV

1. To add many entries at once, click Bulk upload. Use the following CSV format:
   areaCode,extOrFwdNum
   415,2000
   212,3000

2. Drag and drop your file (or click to browse). A preview shows the number of valid and invalid rows before you confirm with import. 

3. Use the Export to download your current entries as a CSV.

8x8 Contact Center Geo Routing

Route calls to a contact center queue based on the caller’s area code and a routing option. A routing option maps to a specific routing scenario in your IVR.  

Step 1: Save your Action Request Token

1. Select your Tenant from the list on the left.

Note

To find your Action Request Token:

• Open Configuration Manager for Contact Center from the My Applications page.

• Select “Integration” from the left-hand navigation panel.

• Select API Token from the top menu.

  • If an Action Request Token is populated, copy the token to be pasted in the Geo Routing Action Token field. CAUTION: If there is a token in this field, do NOT click New Token. This will break any other configuration using the Action Request Token.

  • If the Action Request Token field is empty, click the New Token button, then copy the token to be pasted in the Geo Routing Action Token field.

2. Click Update in the Token field and paste your Action Request Token.

3. Click Save Token.

Step 2: Configure a default path for each option

An Option is a collection of configured area code <-> Queue ID mappings with a default path that the IVR script uses to determine where the call should be routed. For example, a call hitting the “Internal Sales IVR” may have area code 207 route to Queue ID 109, and calls to the “Tech Support” IVR may have area code 207 route to Queue ID 110. In this case, area code 207 needs to be configured with two Options, one for Internal Sales and another for Tech Support. The entries would look like this:

• Internal Sales: Area Code = 207, Queue ID = 109, Option = 1

• Tech Support: Area Code = 207, Queue ID = 110, Option = 2

The Internal Sales and Tech Support IVR scripts are configured to use the area code <-> Queue mapping based on the Option called from the IVR. The configuration for this is in the Connect to your IVR section below.

Each option needs its own default path (the queue used when no area code matches for that option).

1. Click Configure default path (or + Add default path if one already exists).

2. Enter the Option (for example, 1) and the Default Queue ID (for example, queue-123).

   Note

   The Queue ID is found in Configuration Manager for Contact Center in the Queues/Scripts container. Find the Queue name; the Queue ID is in the ID column corresponding to the Queue name.

3. Click Save Default Path.

Step 3: Add area code entries

1. Click + Create Entry.

2. Enter the Area Code, the Queue ID to route matching callers to, and the default path Option number.

3. Click Save.

Tip

A plain 3-digit area code (for example, 415) works exactly as before. To route by country code — or any custom pattern — enter a regular expression instead. For example, ^44.* matches any caller from the UK (country code 44), regardless of the rest of the number. A regex is matched against the caller's full number, so include an end anchor ($) or wildcard (.*) to control how much of the number must match — a bare ^44 with no end anchor can match more than intended.

Note

If you try to add an entry for an option that has no default path yet, you are prompted to create the default path for that option first.

Connect to your IVR

Geo routing is triggered by a script attached to the channel you want to route. You can include any pre-routing logic or objects you like in that script (for example, a business-hours check or an initial greeting) — geo routing takes over once the call reaches the forwarding node described below.

1. Open the script attached to the channel you want to route (in the Configuration Manager) and add any pre-routing logic you want before the call reaches geo routing.

2. Add a “Forward to External IVR” node at the point where you want geo routing to take over.

3. Set the node's value to AdvIvr8x8_v2-gRoute_OPTION, replacing OPTION with your option number (for example, AdvIvr8x8_v2-gRoute_1).

When a call reaches that node, it is routed according to the area code entries and default path configured for that option.

Warning

The value AdvIvr8x8_v2-gRoute_OPTION is case-sensitive, and OPTION must match the option number configured for this default path and its area code entries exactly, or the call will not route as expected.

Bulk upload by CSV

1. Click Bulk upload to add many entries at once. Use the following CSV format:
   option,areaCode,queueId
   1,415,queue-123
   1,212,queue-456

2. Use Export to download your current entries.

8x8 Geo Routing: frequently asked questions