How to Configure Teams Direct Routing PSTN Voice Routes in PowerShell Using CsOnlineVoiceRoute

In Microsoft Teams Phone System environments utilising Direct Routing, outbound Public Switched Telephone Network (PSTN) calls must be routed intelligently through certified Session Border Controllers (SBCs) to carrier telecommunications trunks. In the Microsoft Teams PowerShell administration module, outbound routing logic is governed by voice routes managed via the *-CsOnlineVoiceRoute cmdlets. A voice route pairs regular expression dialing patterns with one or more PSTN usages and prioritised gateway servers, determining exactly how numbers dialed by end-users are mapped to external SBCs.

Understanding Teams Direct Routing Voice Route Architecture

When a Microsoft Teams Phone user places an outbound telephone call, the Teams Phone routing engine evaluates policies and routes through a structured sequence:

1. Voice Routing Policy (CsOnlineVoiceRoutingPolicy): Identifies the user’s assigned PSTN usages (e.g., “National”, “International”, “Local”).
2. PSTN Usage Association: The routing engine inspects all configured voice routes matching the user’s authorized PSTN usages.
3. Regex Dial Pattern Match (NumberPattern): The evaluated destination telephone number (expressed in E.164 format) is matched against the regular expression defined in the voice route.
4. Priority Evaluation: If multiple matching routes share the same PSTN usage, the route with the lowest numeric priority value (e.g., 0 or 1) takes precedence.
5. Gateway Dispatch (OnlinePstnGatewayList): The call signaling is dispatched to the defined Session Border Controllers in prioritized order, supporting automated gateway failover and load balancing.

Connecting to the Microsoft Teams PowerShell Module

Managing voice routes requires the Microsoft Teams administrative module with Skype for Business or Teams Administrator permissions in Microsoft Entra ID. Launch an elevated PowerShell session and connect to your tenant:

# Install Microsoft Teams module if not already present
Install-Module -Name MicrosoftTeams -Force -AllowClobber

# Authenticate to the Microsoft Teams tenant
Connect-MicrosoftTeams

Inspecting Existing Online Voice Routes

To view all voice routes currently established within your Microsoft 365 tenant, execute:

Get-CsOnlineVoiceRoute

To inspect a specific voice route and format its key properties cleanly:

Get-CsOnlineVoiceRoute -Identity "UK-National-Route" | Select-Object Identity, Priority, NumberPattern, OnlinePstnUsages, OnlinePstnGatewayList | Format-List

A representative configuration output displays:

Identity              : UK-National-Route
Priority              : 1
NumberPattern         : ^\+44[1-9]\d{8,9}$
OnlinePstnUsages      : {UK-National}
OnlinePstnGatewayList : {sbc01.contoso.com, sbc02.contoso.com}

Creating a New Online Voice Route with New-CsOnlineVoiceRoute

To create a new voice route, administrators use the New-CsOnlineVoiceRoute cmdlet. When defining a route, you must specify the route identity, regular expression dial string pattern, assigned PSTN usage, and designated SBC gateways.

Example 1: Creating a National Outbound Route

The following command creates an outbound route matching UK national numbers (+44 followed by non-zero digits) and directs traffic to primary and secondary SBC gateways:

New-CsOnlineVoiceRoute -Identity "UK-National-Outbound" `
  -Priority 1 `
  -Description "Direct Routing for UK National E.164 numbers" `
  -NumberPattern '^\+44[1-9]\d{8,9}$' `
  -OnlinePstnUsages @{Add="UK-National"} `
  -OnlinePstnGatewayList @{Add="sbc01.contoso.com", "sbc02.contoso.com"}

Example 2: Creating an International Outbound Route

To establish an international route that catches all other international destinations excluding domestic ranges:

New-CsOnlineVoiceRoute -Identity "Global-International-Outbound" `
  -Priority 10 `
  -Description "Catch-all international route via redundant SBCs" `
  -NumberPattern '^\+(?:[2-9]\d{6,14}|1[2-9]\d{9})$' `
  -OnlinePstnUsages @{Add="International"} `
  -OnlinePstnGatewayList @{Add="sbc01.contoso.com", "sbc02.contoso.com"}

Modifying Existing Routes with Set-CsOnlineVoiceRoute

As network topologies change or new Session Border Controllers are deployed, administrators must update regex patterns, adjust priorities, or add fallback gateways.

Adding and Removing Gateways Dynamically

To append a third standby SBC (sbc-backup.contoso.com) without overwriting existing gateways:

Set-CsOnlineVoiceRoute -Identity "UK-National-Outbound" `
  -OnlinePstnGatewayList @{Add="sbc-backup.contoso.com"}

To decommission an obsolete SBC gateway from a route:

Set-CsOnlineVoiceRoute -Identity "UK-National-Outbound" `
  -OnlinePstnGatewayList @{Remove="sbc01.contoso.com"}

Updating Number Patterns and Priority

If you need to change route evaluation priority or adjust regular expression filtering:

# Change priority to 0 (highest precedence)
Set-CsOnlineVoiceRoute -Identity "UK-National-Outbound" -Priority 0

# Refine regex pattern to strictly match mobile ranges
Set-CsOnlineVoiceRoute -Identity "UK-National-Outbound" -NumberPattern '^\+447\d{9}$'

Testing and Validating Voice Routing Logic

Before applying routes to production enterprise voice users, administrators can validate how dialed digits resolve against tenant voice routes using the Test-CsEffectiveTenantDialPlan and voice routing diagnostics.

To verify which voice route matches an E.164 dialed string for an active user account:

$UserUPN = "[email protected]"
$DialedNumber = "+442079460999"

# Inspect effective voice routing policy assigned to user
$Policy = (Get-CsUserPolicyAssignment -Identity $UserUPN -PolicyType TeamsVoiceRoutingPolicy).PolicyName
Write-Output "User Voice Routing Policy: $Policy"

# Test matching routes for the dialed number
Get-CsOnlineVoiceRoute | Where-Object { $DialedNumber -match $_.NumberPattern } | Select-Object Identity, Priority, OnlinePstnUsages, OnlinePstnGatewayList | Sort-Object Priority

Removing Obsolete Voice Routes

When an outbound routing trunk is retired or replaced, decommission the route using Remove-CsOnlineVoiceRoute:

Remove-CsOnlineVoiceRoute -Identity "UK-National-Outbound" -Confirm:$false

By properly structuring regular expression number patterns, maintaining disciplined priority hierarchies, and pairing robust PSTN usages with redundant SBC gateway lists, network administrators ensure reliable and cost-effective voice delivery across global Microsoft Teams deployments.