In enterprise telecommunications and contact centre operations, distributing incoming customer calls efficiently across teams of customer service agents or technical support engineers is vital for business success. Within Microsoft Teams Phone System, call distribution is handled by Call Queues. A Call Queue holds incoming calls in line, plays customized greetings and music on hold, and routes callers to available agents using sophisticated routing algorithms. While basic queues can be created via the Microsoft Teams admin center, enterprise-scale rollouts, automated branch deployments, and disaster recovery configurations require PowerShell automation. In the Microsoft Teams PowerShell module, administrators configure Call Queues using the *-CsCallQueue cmdlets.
Understanding Microsoft Teams Call Queue Architecture
A Microsoft Teams Call Queue relies on several core architectural building blocks:
- Resource Account (Application Instance): A disabled Microsoft Entra ID identity assigned a Teams Phone Resource Account license. It anchors the queue’s direct phone number (DID) or receives transfers forwarded from Auto Attendants.
- Agent Call Distribution Groups: Agents are assigned to queues via Microsoft 365 Groups, Security Groups, or distribution lists. Individual users can also opt in or out of taking queue calls based on presence.
- Routing Algorithms:
- Attendant Routing: Rings all available agents in the queue simultaneously.
- Serial Routing: Rings agents one by one in a specified sequence.
- Round Robin: Distributes incoming calls equally so each agent receives an equal share of call attempts.
- Longest Idle: Routes the incoming call to the agent who has been idle the longest.
- Conference Mode: Pre-connects agents into a conference bridge to eliminate call pick-up delay and improve audio handoff performance.
- Call Overflow and Timeout Failsafes: Enforces thresholds for maximum callers allowed in the queue and maximum wait duration before transferring callers to voicemail, another queue, or an external number.
Connecting to the Microsoft Teams PowerShell Module
Managing Call Queues requires Teams Administrator privileges in Microsoft 365. Launch an elevated PowerShell session and connect:
# Install Microsoft Teams module if required
Install-Module -Name MicrosoftTeams -Force -AllowClobber
# Authenticate to tenant
Connect-MicrosoftTeams
Inspecting Existing Call Queues
To list all Call Queues currently active in your tenant:
Get-CsCallQueue
To inspect detailed configuration properties for a specific Call Queue:
Get-CsCallQueue -Identity "a1b2c3d4-e5f6-7890-abcd-ef0123456789" | Select-Object Name, RoutingMethod, ConferenceMode, PresenceBasedRouting, OverflowThreshold, TimeoutThreshold | Format-List
Creating a New Call Queue with New-CsCallQueue
To create a new Call Queue programmatically, use the New-CsCallQueue cmdlet. Before creation, identify your target agent distribution group and music on hold audio file.
Example 1: Creating a Customer Support Call Queue with Longest Idle Routing
The following example creates a Support Call Queue utilizing Longest Idle routing, enabling Conference Mode, enforcing presence-based routing, and configuring overflow rules:
# Query Microsoft 365 Group holding agents
$Group = Get-Team -DisplayName "Customer Support Tier 1"
# Create the Call Queue
$NewQueue = New-CsCallQueue `
-Name "Customer-Support-Queue" `
-RoutingMethod LongestIdle `
-DistributionLists @($Group.GroupId) `
-ConferenceMode $true `
-PresenceBasedRouting $true `
-AgentAlertTime 20 `
-OverflowThreshold 15 `
-OverflowAction DisconnectWithBusy `
-TimeoutThreshold 180 `
-TimeoutAction DisconnectWithBusy
Write-Output "Call Queue Created: $($NewQueue.Identity)"
Example 2: Creating a Sales Queue with Attendant Routing and Voicemail Overflow
For sales lines where all phones should ring at once and unanswered calls should fail over to shared voicemail:
# Retrieve shared voicemail group ObjectId
$SalesGroup = Get-Team -DisplayName "Enterprise Sales"
# Create call queue with Voicemail overflow
New-CsCallQueue `
-Name "Sales-Direct-Queue" `
-RoutingMethod Attendant `
-DistributionLists @($SalesGroup.GroupId) `
-ConferenceMode $true `
-PresenceBasedRouting $true `
-AgentAlertTime 15 `
-TimeoutThreshold 120 `
-TimeoutAction TransferCallToTarget `
-TimeoutActionTarget (New-CsCallQueueCallableEntity -Identity $SalesGroup.GroupId -Type SharedVoicemail)
Associating Resource Accounts and Telephone Numbers
To enable external callers to reach the Call Queue directly over the PSTN, link the Call Queue to an application instance holding an assigned phone number:
# Query Resource Account ObjectId
$ResourceAccount = Get-CsOnlineApplicationInstance -UserPrincipalName "[email protected]"
# Bind Resource Account to Call Queue
New-CsCallQueueApplicationInstanceAssociation `
-CallQueueId $NewQueue.Identity `
-ApplicationInstanceId $ResourceAccount.ObjectId
Modifying Existing Call Queues with Set-CsCallQueue
Administrators frequently need to adjust alert times, toggle conference mode, or alter routing strategies on established queues:
# Retrieve existing queue object
$Queue = Get-CsCallQueue -Identity $NewQueue.Identity
# Update agent alert ring duration to 30 seconds
$Queue.AgentAlertTime = 30
# Switch routing method to Round Robin
$Queue.RoutingMethod = "RoundRobin"
# Commit modifications
Set-CsCallQueue -Instance $Queue
Removing a Call Queue
When decommissioning a Call Queue, disassociate all assigned resource accounts before deleting the queue:
# Remove Resource Account association
Remove-CsCallQueueApplicationInstanceAssociation `
-CallQueueId $NewQueue.Identity `
-ApplicationInstanceId $ResourceAccount.ObjectId
# Remove Call Queue
Remove-CsCallQueue -Identity $NewQueue.Identity -Confirm:$false
By leveraging PowerShell’s CsCallQueue cmdlets, enterprise voice engineers can automate large-scale call centre deployments, maintain consistent ring metrics, and implement resilient call distribution across Microsoft Teams Phone deployments.