How to Configure Teams Phone Unassigned Number Routing in PowerShell Using CsTeamsUnassignedNumberTreatment

In enterprise telecommunications and cloud telephony migrations, organizations frequently acquire broad direct inward dialling (DID) phone number ranges from telecom carriers or Microsoft Calling Plans. As employees depart, departments reorganize, or old numbers are decommissioned, dozens of purchased telephone numbers inevitably remain unallocated across the tenant. In standard PSTN routing, if an external caller dials an unallocated enterprise number, the carrier encounters an invalid subscriber error and returns a generic fast-busy tone or disconnect notification. Microsoft Teams Phone solves this problem through Unassigned Number Routing. Using the Microsoft Teams PowerShell module with cmdlets such as New-CsTeamsUnassignedNumberTreatment, Set-CsTeamsUnassignedNumberTreatment, and Get-CsTeamsUnassignedNumberTreatment, voice administrators can intercept incoming calls to unassigned numbers, play custom audio explanations or text-to-speech notifications, and automatically route callers to a centralized receptionist or call queue.

Role and Mechanics of Unassigned Number Routing in Teams Phone

When an incoming public switched telephone network (PSTN) call arrives at Microsoft Teams via Direct Routing Session Border Controllers (SBC), Operator Connect, or Microsoft Calling Plans, the Teams voice routing core attempts to match the destination number against active users, call queues, and auto-attendants. If no matching object is discovered:

• Pattern Evaluation: Microsoft Teams checks the destination number against configured Unassigned Number Treatments. Treatments evaluate incoming numbers using exact phone numbers or regular expression (regex) ranges.
• Routing Treatments: If a match is found, Teams applies one of three primary administrative actions:
  • Route to User: Redirects the call to a specific employee or operator.
  • Route to Voice Application: Forwards the caller to a designated resource account bound to an Auto Attendant or Call Queue.
  • Play Announcement: Streams a custom pre-recorded audio file (e.g. informing callers that the number is no longer active and providing alternative contact details) or reads a text-to-speech message before gracefully disconnecting the call.
• Priority Ordering: Each treatment rule is assigned an integer priority (e.g. 1, 2, 3). Lower numerical values take precedence, allowing administrators to establish specific rules for high-profile executive numbers while applying catch-all policies to entire DID ranges.

Connecting to the Microsoft Teams PowerShell Module

To administer tenant voice routing treatments, open an elevated PowerShell window and authenticate to Microsoft 365:

# Install or update the Microsoft Teams module
Install-Module -Name MicrosoftTeams -Scope CurrentUser -Repository PSGallery -Force

# Authenticate with administrative credentials
Connect-MicrosoftTeams

Confirm that your administrative account holds the Teams Administrator role in Microsoft Entra ID before executing voice cmdlets.

Auditing Existing Unassigned Number Treatments

Before creating new treatment rules, inspect the existing treatments configured within your tenant directory:

# List all configured unassigned number routing rules
Get-CsTeamsUnassignedNumberTreatment

# Display treatments formatted with priority and target type
Get-CsTeamsUnassignedNumberTreatment | Select-Object Identity, Priority, Pattern, TargetType, Target

Creating an Unassigned Number Treatment with Call Forwarding

To intercept calls to unassigned numbers and route them directly to a centralized reception auto-attendant or operator queue, execute New-CsTeamsUnassignedNumberTreatment:

# Retrieve the Object ID of the central reception resource account
$receptionAccount = Get-CsOnlineUser -Identity "[email protected]"

# Create a rule routing an entire unassigned DID block to reception
New-CsTeamsUnassignedNumberTreatment -Identity "Unassigned-DID-Block-Routing" `
    -Description "Route unassigned London DIDs to central reception" `
    -Pattern "^\+442079460[0-9]{3}$" `
    -TargetType "Application" `
    -Target $receptionAccount.Identity `
    -Priority 1

In this example, the regular expression ^\+442079460[0-9]{3}$ matches any incoming call within the range +442079460000 through +442079460999 that is not actively assigned to a licensed user.

Creating an Announcement-Only Treatment for Decommissioned Numbers

For high-profile executive lines or legacy customer support numbers that have been permanently retired, configure an announcement treatment playing a custom audio message:

# Create a treatment playing an audio notification before disconnect
New-CsTeamsUnassignedNumberTreatment -Identity "Retired-Executive-Line" `
    -Description "Play announcement for decommissioned executive number" `
    -Pattern "^\+442079460111$" `
    -TargetType "Announcement" `
    -CustomAudioFileId "3b8a1c9e-4d2f-4a1b-8e3c-9a1b2c3d4e5f" `
    -Priority 2

Modifying Priority and Rule Definitions

If you need to adjust priority order, update regular expressions, or reassign routing targets, use Set-CsTeamsUnassignedNumberTreatment:

# Adjust the priority of an existing treatment rule
Set-CsTeamsUnassignedNumberTreatment -Identity "Retired-Executive-Line" -Priority 1

# Re-verify the updated priority ordering
Get-CsTeamsUnassignedNumberTreatment | Sort-Object Priority | Select-Object Priority, Identity, Pattern

Testing and Validating Unassigned Number Routing

To verify that an unassigned number correctly triggers the intended treatment rule, simulate call routing within PowerShell using the Test-CsTeamsUnassignedNumberTreatment cmdlet:

# Test routing for an unassigned number within the configured range
Test-CsTeamsUnassignedNumberTreatment -PhoneNumber "+442079460555"

# Verify that an actively assigned employee DID is ignored by the rule
Test-CsTeamsUnassignedNumberTreatment -PhoneNumber "+442079460123"

The command returns the matching treatment identity and target properties, confirming that calls will route seamlessly.

Removing Obsolete Treatment Rules

When unassigned number blocks are returned to the carrier or reallocated for direct user assignment, dismantle obsolete treatments using Remove-CsTeamsUnassignedNumberTreatment:

# Safely remove a treatment rule
Remove-CsTeamsUnassignedNumberTreatment -Identity "Retired-Executive-Line"

Configuring Unassigned Number Routing in Microsoft Teams Phone eliminates jarring dead-end calls, captures customer inquiries directed to outdated numbers, and delivers a polished telecommunications experience across enterprise organizations.