How to Configure Teams User Call Forwarding and Delegation in PowerShell Using Set-CsUserCallingSettings

Architecture of Set-CsUserCallingSettings in Microsoft Teams Voice

Enterprise voice administration in Microsoft Teams requires granular control over how inbound calls route to end users, delegators, and response endpoints. While tenant-wide dial plans and voice routing policies govern broad telephony behaviour, individual call orchestration—including immediate call forwarding, simultaneous ringing (simulring), unanswered call destinations, and executive-assistant delegation—is managed at the identity level through the Set-CsUserCallingSettings cmdlet in the MicrosoftTeams PowerShell module.

Administrators frequently encounter operational requirements where telephony configurations must be adjusted programmatically without requiring end-user interaction. For instance, when an employee transitions to extended leave, an automated offboarding script can redirect inbound direct inward dialling (DID) calls to a departmental coverage group or voicemail. Similarly, executive support staff can be provisioned with call handling privileges across multiple accounts simultaneously.

The cmdlet interacts directly with the Teams Calling Service backend, updating user routing records stored within Microsoft 365. These settings govern how the Teams calling infrastructure handles Session Initiation Protocol (SIP) signalling when an inbound Public Switched Telephone Network (PSTN) or internal Voice over IP (VoIP) call targets the user’s line Uniform Resource Identifier (URI).

Prerequisites and PowerShell Session Initialisation

To inspect and modify calling configurations across tenant accounts, ensure the latest stable release of the MicrosoftTeams PowerShell module is installed. Executing calling configuration cmdlets requires administrative privileges, specifically the Teams Administrator, Skype for Business Administrator, or Global Administrator role within Microsoft Entra ID.

Install or verify the module and establish an authenticated administrative session using modern certificate-based or multi-factor authentication:

# Verify and install Microsoft Teams PowerShell module
Install-Module -Name MicrosoftTeams -Scope CurrentUser -Force -AllowClobber

# Connect to the tenant administration endpoint
Connect-MicrosoftTeams

Before modifying call routing rules for a specific identity, verify that the account possesses an active Microsoft Teams Phone standard licence and an assigned Enterprise Voice line URI. Modifying calling properties on unlicensed or non-voice-enabled accounts will result in execution exceptions.

Auditing Existing Calling Configuration via Get-CsUserCallingSettings

Prior to applying modifications, review the current state of call routing rules associated with the user account using Get-CsUserCallingSettings. This ensures existing delegation permissions or forwarding configurations are documented before alteration:

# Retrieve calling settings for a target user
Get-CsUserCallingSettings -Identity "[email protected]"

The cmdlet returns a structured object detailing the core routing states:

Identity             : [email protected]
IsForwardingEnabled  : False
ForwardingType       : Immediate
ForwardingTarget     : 
ForwardingTargetType : SingleTarget
IsUnansweredEnabled  : True
UnansweredTarget     : [email protected]
UnansweredTargetType : MyJail
UnansweredDelay      : 20
Delegates            : {}
Delegators           : {}

Key properties govern specific call phases:

• IsForwardingEnabled: A boolean switch indicating whether immediate forwarding or simultaneous ring is engaged.
• ForwardingType: Defines routing behaviour—either Immediate (bypassing the user’s endpoints) or Simultaneous (ringing endpoints and secondary targets concurrently).
• ForwardingTargetType: Identifies target structure, such as SingleTarget (individual user or PSTN number) or Group (call group).
• UnansweredDelay: Time in seconds (from 10 to 60 in 5-second increments) before an unanswered call triggers secondary routing.
• UnansweredTargetType: Destination for unanswered calls, typically Voicemail (displayed as MyJail in backend schema), SingleTarget, or Group.

Configuring Immediate Call Forwarding

Immediate forwarding bypasses all registered Teams desktop, mobile, and IP desk phone clients, instantly routing inbound calls to an alternate internal user, external PSTN telephone number, or voicemail service. This is particularly valuable during planned absences or organisational restructuring.

To forward all inbound calls immediately to a colleague’s user principal name (UPN):

# Forward all incoming calls directly to a colleague
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsForwardingEnabled $true `
    -ForwardingType Immediate `
    -ForwardingTarget "[email protected]" `
    -ForwardingTargetType SingleTarget

To route all inbound calls immediately to an external telephone number (such as an on-call mobile device), format the destination string in international E.164 notation:

# Forward all incoming calls to an external PSTN number
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsForwardingEnabled $true `
    -ForwardingType Immediate `
    -ForwardingTarget "+442079460912" `
    -ForwardingTargetType SingleTarget

To disable call forwarding and restore direct ringing to the user’s primary Teams clients, set -IsForwardingEnabled to false:

# Restore default ringing behaviour by disabling forwarding
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsForwardingEnabled $false

Configuring Simultaneous Ringing (Simulring)

Simultaneous ringing allows inbound calls to alert the user’s primary Teams endpoints while simultaneously ringing an alternate destination. If the user fails to answer on their computer or desk phone, an external mobile or backup contact alerts simultaneously.

Execute the following syntax to ring an external telephone number alongside the user’s Teams clients:

# Enable simultaneous ringing to an external mobile number
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsForwardingEnabled $true `
    -ForwardingType Simultaneous `
    -ForwardingTarget "+447700900145" `
    -ForwardingTargetType SingleTarget

Simultaneous ringing can also target internal peers or call delegate groups by specifying their corresponding SIP addresses or group objects.

Adjusting Unanswered Call Routing and Delay Timers

When inbound calls ring a user without being answered, Microsoft Teams routes the call according to unanswered rules. By default, calls divert to voicemail after 20 seconds. Administrators can alter the timeout window or redirect unanswered calls to alternate recipients.

To change the unanswered timer to 30 seconds and route unanswered calls directly to voicemail:

# Configure unanswered calls to divert to voicemail after 30 seconds
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsUnansweredEnabled $true `
    -UnansweredTargetType Voicemail `
    -UnansweredDelay 30

To route unanswered calls to a colleague instead of voicemail after a 15-second delay:

# Route unanswered calls to another user after 15 seconds
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsUnansweredEnabled $true `
    -UnansweredTargetType SingleTarget `
    -UnansweredTarget "[email protected]" `
    -UnansweredDelay 15

Managing Call Delegation and Executive-Assistant Relationships

Call delegation enables designated assistants (delegates) to make and receive telephone calls on behalf of an executive (delegator). While the delegator settings can be viewed via Get-CsUserCallingSettings, delegate relationships are provisioned and modified using dedicated companion cmdlets: New-CsUserCallingDelegate, Set-CsUserCallingDelegate, and Remove-CsUserCallingDelegate.

To assign an assistant as a delegate with full permissions to place calls, answer calls, and modify forwarding rules:

# Add a delegate with call handling and administrative permissions
New-CsUserCallingDelegate -Identity "[email protected]" `
    -Delegate "[email protected]" `
    -MakeCalls $true `
    -ReceiveCalls $true `
    -ManageSettings $true

Once the delegate relationship is established, configure the executive’s calling settings so incoming calls ring both the executive and their delegates simultaneously:

# Configure simultaneous ring targeting assigned delegates
Set-CsUserCallingSettings -Identity "[email protected]" `
    -IsForwardingEnabled $true `
    -ForwardingType Simultaneous `
    -ForwardingTargetType Group `
    -ForwardingTarget "MyDelegates"

To audit all assigned delegates and verify their active permission flags:

# Retrieve list of delegates and associated permissions
(Get-CsUserCallingSettings -Identity "[email protected]").Delegates | Format-Table -Property Id, MakeCalls, ReceiveCalls, ManageSettings

If an assistant transitions out of a support role, remove their delegation assignment cleanly:

# Remove delegate rights from target assistant
Remove-CsUserCallingDelegate -Identity "[email protected]" `
    -Delegate "[email protected]"

Troubleshooting Common Execution and Telephony Errors

When administering calling settings programmatically, several common operational errors may arise:

• User Not Found or Not Enterprise Voice Enabled: If Set-CsUserCallingSettings returns an error indicating the user cannot be resolved or is not configured for calling, verify that (Get-CsOnlineUser -Identity $User).EnterpriseVoiceEnabled returns True and an E.164 LineURI is provisioned.
• External PSTN Forwarding Blocked by Policy: If forwarding to an external telephone number fails to complete when dialled, inspect the user’s assigned TeamsCallingPolicy. Ensure the AllowCallForwardingToPhone parameter is set to $true:

  # Verify calling policy settings for external forwarding
  Get-CsTeamsCallingPolicy -Identity (Get-CsOnlineUser -Identity "[email protected]").TeamsCallingPolicy | Select-Object Identity, AllowCallForwardingToPhone, AllowCallForwardingToUser

• Invalid E.164 Number Format: External forwarding targets must strictly adhere to the international E.164 format (e.g. +442079460123). Omitting the leading plus sign or including hyphens, parentheses, or spaces causes validation errors during cmdlet execution.
• Delay Interval Constraints: The -UnansweredDelay parameter only accepts integers between 10 and 60 that are divisible by 5 (10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60). Passing values such as 18 or 42 results in parameter validation exceptions.

By integrating Set-CsUserCallingSettings into administrative runbooks and automated lifecycle processes, IT teams maintain consistent telephony governance, streamline user onboarding, and ensure mission-critical inbound voice routing remains uninterrupted across the enterprise.