How to Configure Teams Inbound Blocked Number Patterns in PowerShell Using CsInboundBlockedNumberPattern

In enterprise telecommunications and customer support environments, spam calls, automated fraudulent robocalls, and abusive telephony traffic consume valuable agent bandwidth and degrade productivity. While individual users can manually block incoming numbers within their Microsoft Teams desktop or mobile client, large organisations require centralized, tenant-wide call blocking policies that intercept unwanted calls at the public switched telephone network (PSTN) gateway layer before phones ever ring. Microsoft Teams Phone provides native inbound call blocking through regular expression (regex) patterns. Using the Microsoft Teams PowerShell module with cmdlets such as New-CsInboundBlockedNumberPattern, Set-CsInboundBlockedNumberPattern, Get-CsInboundBlockedNumberPattern, and Test-CsInboundBlockedNumberPattern, voice administrators can deploy, manage, and test tenant-wide telephony blocklists.

How Microsoft Teams Evaluates Inbound Blocked Number Patterns

When an external PSTN call arrives at Microsoft Teams via Microsoft Calling Plans, Operator Connect, or Direct Routing Session Border Controllers (SBC), the Teams Phone infrastructure inspects the Calling Line Identity (CLI / Caller ID):

• Regular Expression Pattern Matching: The inbound number is matched against all active patterns configured in the tenant. Patterns support standard .NET regular expressions, allowing administrators to target single telephone numbers, whole area codes, international country prefixes, or invalid number formats (such as spoofed numbers with insufficient digits).
• Pre-Routing Interception: If a match is detected, Microsoft Teams terminates the call immediately without dispatching the session to user endpoints, auto-attendants, or call queues.
• Custom Inbound Routing Policy Integration: Blocked number patterns operate tenant-wide or can be referenced in conjunction with CsTeamsCallingPolicy to enforce specific handling rules for different user departments.

Connecting to the Microsoft Teams PowerShell Module

To administer tenant call blocking rules, open an elevated PowerShell window and sign in to Microsoft 365:

# Install the Microsoft Teams module if not already present
Install-Module -Name MicrosoftTeams -Scope CurrentUser -Repository PSGallery -Force

# Authenticate to the tenant
Connect-MicrosoftTeams

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

Auditing Existing Blocked Number Patterns

Before adding new regex rules, review the existing blocklist to avoid overlapping patterns or redundant expressions:

# List all currently configured blocked number patterns
Get-CsInboundBlockedNumberPattern

# Display patterns formatted with description and status
Get-CsInboundBlockedNumberPattern | Select-Object Identity, Pattern, Description, Enabled

Creating New Inbound Blocked Number Patterns

To block a specific telephone number or an entire number range, execute New-CsInboundBlockedNumberPattern, providing a unique description, a regex string, and a unique name identity:

# Block a single specific fraudulent telephone number
New-CsInboundBlockedNumberPattern -Description "Block known telemarketing scammer" `
    -Enabled $true `
    -Name "ScamCaller-UK" `
    -Pattern "^\+442079460999$"

# Block an entire international area code known for toll fraud
New-CsInboundBlockedNumberPattern -Description "Block international premium rate range" `
    -Enabled $true `
    -Name "Block-Premium-Range" `
    -Pattern "^\+248.*"

# Block invalid caller IDs with missing or non-E.164 formatting
New-CsInboundBlockedNumberPattern -Description "Block spoofed local numbers" `
    -Enabled $true `
    -Name "Block-Invalid-Format" `
    -Pattern "^(\+1)?(800|888|877)000.*"

Always construct regex expressions anchored with ^ (start of string) and $ (end of string) where matching exact numbers, and escape literal plus signs with \+ to adhere to E.164 telephone number formats.

Testing Blocked Number Patterns Before Deployment

To prevent accidentally blocking legitimate incoming customer or vendor calls, Microsoft Teams provides the Test-CsInboundBlockedNumberPattern cmdlet. This allows you to simulate whether a specific telephone number matches any active blocking rule:

# Test whether a specific incoming phone number will be blocked
Test-CsInboundBlockedNumberPattern -PhoneNumber "+442079460999"

# Test a legitimate incoming customer number to ensure it passes through
Test-CsInboundBlockedNumberPattern -PhoneNumber "+442079460123"

If the tested number matches a pattern, the cmdlet outputs the matching rule name and pattern details. If no rule matches, the command returns nothing, confirming the call will route successfully.

Modifying and Disabling Blocked Number Rules

If a pattern requires updating or needs to be temporarily paused without deletion, use Set-CsInboundBlockedNumberPattern:

# Temporarily disable an active blocked pattern
Set-CsInboundBlockedNumberPattern -Identity "ScamCaller-UK" -Enabled $false

# Update the regular expression pattern of an existing rule
Set-CsInboundBlockedNumberPattern -Identity "ScamCaller-UK" `
    -Pattern "^\+442079460(998|999)$"

Removing Obsolete Blocked Number Patterns

To permanently purge an obsolete pattern from the tenant directory, execute Remove-CsInboundBlockedNumberPattern:

# Remove a blocked number pattern
Remove-CsInboundBlockedNumberPattern -Identity "Block-Premium-Range"

Implementing centralized regex call blocking in Microsoft Teams Phone eliminates unwanted inbound interruptions, safeguards employee productivity, and reduces PSTN trunk saturation across enterprise voice networks.