How to Configure Teams Call Hold Policies and Custom Music on Hold Using PowerShell CsTeamsCallHoldPolicy

When enterprise users place Public Switched Telephone Network (PSTN) or Voice over IP (VoIP) calls on hold or initiate a consultative transfer in Microsoft Teams Phone, callers hear audio playback rather than dead silence. By default, Microsoft Teams plays a standard, generic music on hold (MoH) audio track. However, enterprise organizations frequently require branded caller experiences, recorded announcements, customized music tracks, or complete suppression of hold audio for specific secure environments.

Administrators govern these call experiences across Microsoft Teams using the CsTeamsCallHoldPolicy PowerShell cmdlets. This guide explains how to inspect existing call hold policies, upload and reference custom audio files, configure policy profiles, and assign call hold governance to users and departments.

Understanding CsTeamsCallHoldPolicy Parameters

The CsTeamsCallHoldPolicy controls the auditory experience when an inbound or outbound call is placed on hold by a Teams user:

• MusicOnHoldEnabled: A boolean flag specifying whether music or audio playback is presented to callers placed on hold. If disabled, callers experience silence.
• AudioFileId: References a specific audio file previously uploaded and registered in the Microsoft 365 tenant repository.
• Granular Departmental Targeting: Enables custom corporate marketing audio for sales and customer support lines while applying neutral or silent policies for executive conference rooms.

Connecting to Microsoft Teams PowerShell

Open an elevated PowerShell prompt on your administrative workstation and connect to your Microsoft 365 tenant:

Connect-MicrosoftTeams

Verify that your administrative session is active and check the installed Teams module version:

Get-CsTenant | Select-Object DisplayName, TenantId

Inspecting Current Call Hold Policies

To inspect all configured call hold policies across your tenant, run:

Get-CsTeamsCallHoldPolicy

To view the default Global policy inherited by all tenant users:

Get-CsTeamsCallHoldPolicy -Identity Global | Format-List Identity, Description, MusicOnHoldEnabled, AudioFileId

In default tenant setups, MusicOnHoldEnabled is set to True, and AudioFileId is blank (indicating the default Microsoft system track is active).

Uploading and Registering Custom Audio Files

Before referencing a custom audio file in a call hold policy, the audio file must be uploaded to the tenant media repository. Supported formats include standard uncompressed WAV (PCM, 16-bit, 16 kHz or 44.1 kHz, mono or stereo) or MP3 files under 5 MB in size.

Upload the custom audio file using Import-CsOnlineAudioFile:

$content = [System.IO.File]::ReadAllBytes("C:\Audio\CorporateBrandedHoldMusic.wav")
$audioFile = Import-CsOnlineAudioFile -ApplicationId "CallHoldPolicy" -FileName "CorporateBrandedHoldMusic.wav" -Content $content

The upload command returns a unique Id guid. Save this identifier:

$audioFile.Id

Creating a Custom Branded Call Hold Policy

Create a new call hold policy referencing the newly uploaded audio file identifier:

New-CsTeamsCallHoldPolicy -Identity "BrandedCorporateHoldPolicy" -Description "Plays corporate marketing music on hold for external callers" -MusicOnHoldEnabled $true -AudioFileId $audioFile.Id

If you need an ultra-secure policy for compliance lines, legal departments, or contact centre supervisors where hold audio must be muted to ensure callers can easily discern agent resumption:

New-CsTeamsCallHoldPolicy -Identity "SilentHoldPolicy" -Description "Suppresses hold music; plays absolute silence" -MusicOnHoldEnabled $false

Modifying Existing Call Hold Policy Settings

To update an existing policy with a new audio file or toggle music playback, use Set-CsTeamsCallHoldPolicy:

Set-CsTeamsCallHoldPolicy -Identity "BrandedCorporateHoldPolicy" -MusicOnHoldEnabled $true -AudioFileId "NEW-GUID-HERE"

To revert the Global policy to enforce default system music on hold across all unassigned tenant users:

Set-CsTeamsCallHoldPolicy -Identity Global -MusicOnHoldEnabled $true -AudioFileId $null

Assigning Call Hold Policies to Users and Groups

Assign your branded policy to an individual user using Grant-CsTeamsCallHoldPolicy:

Grant-CsTeamsCallHoldPolicy -Identity "[email protected]" -PolicyName "BrandedCorporateHoldPolicy"

To assign the policy across an entire departmental group (such as a Customer Success security group in Microsoft Entra ID):

Grant-CsTeamsCallHoldPolicy -Group "Customer-Success-GroupID" -PolicyName "BrandedCorporateHoldPolicy" -Rank 1

To unassign an explicit policy from a user so they inherit the tenant Global baseline:

Grant-CsTeamsCallHoldPolicy -Identity "[email protected]" -PolicyName $null

Verifying Effective Policy Assignment

Confirm the active policy applied to a target user:

Get-CsUserPolicyAssignment -Identity "[email protected]" -PolicyType TeamsCallHoldPolicy

By leveraging CsTeamsCallHoldPolicy in PowerShell, organizations maintain consistent telecommunications branding and provide a polished, professional auditory experience for all callers placed on hold.