How to Configure Teams Music on Hold Policies in PowerShell Using CsTeamsHoldMusicPolicy

In enterprise telecommunications and contact centre operations, the acoustic experience delivered to callers placed on hold is a fundamental extension of brand identity. In Microsoft Teams Phone, when a user places an external public switched telephone network (PSTN) call on hold or initiates a consultative transfer, the Microsoft cloud streams audio to the held caller. While Microsoft provides default synthesized music, organizations frequently require customized audio files—such as branded corporate announcements, informational messages, or professionally produced music—tailored to specific business units, executive desks, or customer-facing departments. Microsoft Teams Phone supports this capability through Teams Hold Music policies. Using the Microsoft Teams PowerShell module with cmdlets such as New-CsTeamsHoldMusicPolicy, Set-CsTeamsHoldMusicPolicy, Get-CsTeamsHoldMusicPolicy, and Grant-CsTeamsHoldMusicPolicy, voice administrators can deploy, assign, and audit custom Music on Hold (MoH) policies across the enterprise.

Architecture of Microsoft Teams Music on Hold (MoH)

The Microsoft Teams Phone Music on Hold framework operates at the tenant policy layer and integrates directly with media processors in the Microsoft cloud and connected Session Border Controllers (SBC):

• Global vs Custom Policies: By default, all enterprise users inherit the global (default) policy where standard Microsoft hold music is enabled. Administrators can create custom policies targeting specific user cohorts or departments.
• Audio Source Selection: Allows administrators to either utilize Microsoft’s default acoustic playlist or reference custom uploaded audio files.
• Audio File Formats: Custom audio files must be uploaded as 16-bit mono or stereo .wav or .mp3 files (encoded at 44.1 kHz or 48 kHz sampling rates) and assigned an audio file object ID in the Teams administrative storage service.
• Consultative Transfer and Call Park Integration: Hold music streams not only when an agent presses “Hold”, but also while orchestrating warm transfers or when callers reside inside Call Park orbits.

Connecting to the Microsoft Teams PowerShell Module

To administer tenant voice and telephony policies, launch an elevated PowerShell session and authenticate with appropriate administrative credentials:

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

# Authenticate to your Microsoft 365 tenant
Connect-MicrosoftTeams

Ensure the executing account holds the Teams Administrator role in Microsoft Entra ID.

Auditing Existing Hold Music Policies

Before creating new policies, review the currently deployed policies to inspect global defaults and existing custom assignments:

# List all configured Hold Music policies in the tenant
Get-CsTeamsHoldMusicPolicy

# Display formatted policy properties
Get-CsTeamsHoldMusicPolicy | Select-Object Identity, Description

Inspect the Global policy. If no custom policies have been deployed, all users inherit global default settings.

Creating a New Teams Hold Music Policy

To create a custom Hold Music policy, execute New-CsTeamsHoldMusicPolicy, specifying a unique policy identity name and description:

# Create a custom hold music policy for customer support teams
New-CsTeamsHoldMusicPolicy -Identity "Support-HoldMusic-Policy" `
    -Description "Custom branded hold music policy for customer support agents"

# Create a custom policy for executive suites
New-CsTeamsHoldMusicPolicy -Identity "Executive-HoldMusic-Policy" `
    -Description "Classical acoustic hold music for executive staff"

Uploading and Assigning Custom Audio Files

To associate a custom audio recording (such as a corporate brand jingle or product promotional message) with your newly created policy:

# Upload the custom audio file to Teams media storage
$audioFile = Import-CsOnlineAudioFile -FileName "Support_Branded_Audio.wav" `
    -Content ([System.IO.File]::ReadAllBytes("C:\Audio\Support_Branded_Audio.wav"))

# Assign the uploaded audio file ID to the Hold Music policy
Set-CsTeamsHoldMusicPolicy -Identity "Support-HoldMusic-Policy" `
    -AudioFileId $audioFile.Id

Verify that the audio file uploaded successfully and that its Id is correctly referenced in the policy properties using Get-CsTeamsHoldMusicPolicy -Identity "Support-HoldMusic-Policy".

Assigning the Hold Music Policy to Users

Once the policy is defined and bound to its audio source, assign it to individual employees or batch-assign it across security groups using Grant-CsTeamsHoldMusicPolicy:

# Assign the policy to an individual user
Grant-CsTeamsHoldMusicPolicy -Identity "[email protected]" -PolicyName "Support-HoldMusic-Policy"

# Batch assign the policy to all members of a department security group
$supportGroup = Get-MgGroupMember -GroupId "a8b7c6d5-..."
foreach ($member in $supportGroup) {
    Grant-CsTeamsHoldMusicPolicy -Identity $member.Id -PolicyName "Support-HoldMusic-Policy"
}

Confirm user assignment by querying user policy status:

# Inspect effective hold music policy on a specific user
Get-CsUserPolicyAssignment -Identity "[email protected]" -PolicyType TeamsHoldMusicPolicy

Revoking Policies and Reverting to Defaults

To remove a custom policy assignment from a user or delete an obsolete policy from the tenant directory:

# Revoke the policy from a user (reverting back to the Global policy)
Grant-CsTeamsHoldMusicPolicy -Identity "[email protected]" -PolicyName $null

# Delete the custom policy from the tenant directory
Remove-CsTeamsHoldMusicPolicy -Identity "Support-HoldMusic-Policy"

Configuring customized Hold Music policies in Microsoft Teams Phone guarantees brand consistency, delivers a professional acoustic environment for external callers, and enhances customer satisfaction across enterprise voice interactions.