How to Configure Teams Voice Routing Policies Using PowerShell CsOnlineVoiceRoutingPolicy

In enterprise unified communications and telephony, Microsoft Teams Phone System connects users to the Public Switched Telephone Network (PSTN) via Direct Routing, Operator Connect, or Microsoft Calling Plans. When organizations deploy Direct Routing—pairing on-premises Session Border Controllers (SBCs) or cloud telecommunication providers with Teams—outbound call authorisation and least-cost call routing are governed by Online Voice Routing Policies. Managed through the CsOnlineVoiceRoutingPolicy cmdlet family in Microsoft Teams PowerShell, these policies dictate which PSTN usages an enterprise voice-enabled user can access, determining whether outbound international calls, emergency calls, or local extensions successfully bridge to the PSTN.

Architecture of Microsoft Teams Direct Routing and Voice Routing Policies

In Microsoft Teams Direct Routing, telephone call establishment relies on an interconnected tripartite routing hierarchy:

• Online Voice Routing Policy: Assigned directly to users or security groups. Acts as the user-facing security boundary containing a prioritised collection of PSTN Usages.
• PSTN Usage Records: Abstract strings (e.g. UK-Local, International-Approved, Emergency-999) that link voice routing policies to specific voice routes.
• Online Voice Routes: Concrete routing definitions specifying regular expression (regex) dial patterns (such as ^\+44(\d+)$) and the priority list of connected Session Border Controllers (PstnGatewayList) capable of terminating the call.

When an enterprise voice user dials a phone number, Teams checks the user’s assigned CsOnlineVoiceRoutingPolicy, iterates through the listed PSTN usages in numerical order, evaluates matching regex voice routes, and dispatches the SIP INVITE packet to the designated SBC.

Connecting to Teams PowerShell Module

To audit and manage voice routing policies, launch Windows PowerShell with administrative privileges and authenticate against your Microsoft 365 tenant:

# Install Microsoft Teams module if needed
Install-Module -Name MicrosoftTeams -Scope CurrentUser -Repository PSGallery -Force

# Authenticate against tenant
Connect-MicrosoftTeams

Ensure your administrative identity holds the Teams Administrator or Skype for Business Administrator Entra ID role.

Auditing Existing Online Voice Routing Policies

To inspect all voice routing policies currently deployed across the tenant:

Get-CsOnlineVoiceRoutingPolicy

To inspect the Global tenant-wide default policy and its assigned PSTN usages:

Get-CsOnlineVoiceRoutingPolicy -Identity Global | Select-Object Identity, OnlinePstnUsages, Description

To audit all available tenant-wide PSTN usage records:

(Get-CsOnlinePstnUsage).Usage

Creating a Custom Online Voice Routing Policy

Rather than permitting unrestricted international calling globally, administrators establish segmented policies—such as domestic-only calling for standard office personnel and unrestricted international routing for executive directors.

To create a new policy restricted to domestic UK calling and emergency services:

New-CsOnlineVoiceRoutingPolicy -Identity "VRP-UK-DomesticOnly" `
    -OnlinePstnUsages @("Emergency-Services", "UK-National", "UK-Mobile") `
    -Description "Permits UK domestic, national, and emergency dialing via London SBC."

To create a comprehensive policy with international permissions and secondary failover usages:

New-CsOnlineVoiceRoutingPolicy -Identity "VRP-International-Executive" `
    -OnlinePstnUsages @("Emergency-Services", "UK-National", "UK-Mobile", "International-Tier1", "Backup-PSTN") `
    -Description "Full international and domestic routing for executive leadership."

Modifying PSTN Usages and Order in Existing Policies

Because Teams processes PSTN usages strictly in sequential list order, the order of usage tags determines routing priority and carrier failover.

To update an existing policy or reorder PSTN usages:

# Replace existing usages with an updated prioritized array
Set-CsOnlineVoiceRoutingPolicy -Identity "VRP-UK-DomesticOnly" `
    -OnlinePstnUsages @("Emergency-Services", "UK-National", "UK-Mobile", "UK-Freephone")

To append or remove a single usage without rewriting the entire array:

# Append a new usage
Set-CsOnlineVoiceRoutingPolicy -Identity "VRP-UK-DomesticOnly" -OnlinePstnUsages @{Add="Shared-Dialout"}

# Remove an unapproved usage
Set-CsOnlineVoiceRoutingPolicy -Identity "VRP-UK-DomesticOnly" -OnlinePstnUsages @{Remove="UK-Mobile"}

Assigning Voice Routing Policies to Users and Security Groups

Once created, assign the voice routing policy to enterprise voice-enabled users.

To assign a policy to an individual user:

Grant-CsOnlineVoiceRoutingPolicy -Identity "[email protected]" -PolicyName "VRP-UK-DomesticOnly"

To assign a voice routing policy across an entire department using Entra ID Security Groups:

New-CsGroupPolicyAssignment -GroupId "e5f8a912-4c33-4b67-a890-112233445566" `
    -PolicyType OnlineVoiceRoutingPolicy `
    -PolicyName "VRP-UK-DomesticOnly" `
    -Rank 1

To verify the effective voice routing policy applied to a user:

Get-CsUserPolicyAssignment -Identity "[email protected]" | Where-Object { $_.PolicyType -eq "OnlineVoiceRoutingPolicy" }

Testing Voice Routing Logic via Test-CsEffectiveTenantDialPlan

Before rolling out policies to live production users, simulate outbound call routing in PowerShell to confirm that dialed numbers match expected voice routes and gateway gateways:

Test-CsEffectiveTenantDialPlan -Identity "[email protected]" -DialedNumber "+442079460912"

Decommissioning Voice Routing Policies

To revert a user back to the tenant-wide Global policy:

Grant-CsOnlineVoiceRoutingPolicy -Identity "[email protected]" -PolicyName $null

To remove a custom policy that is no longer in use:

Remove-CsOnlineVoiceRoutingPolicy -Identity "VRP-International-Executive"

Configuring structured voice routing policies using CsOnlineVoiceRoutingPolicy ensures robust carrier failover, cost-effective call termination, and uninterrupted PSTN access across Microsoft Teams Phone deployments.