> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hold music on held outbound calls

> What the called party hears when you hold a connected outbound call, which track plays, the organization-level hold-music override, and when a held caller hears silence instead.

# Hold music on held outbound calls

When you press **Hold** on a connected outbound call, the person you
called hears your organization's hold music instead of dead silence.
Taking the call off hold stops the music immediately and reconnects
your audio. Recording and live transcription continue exactly as they
do on an unheld call, and holding never drops or redirects the call:
it only changes what the far end hears while the call is held.

## What the called party hears

* Your organization's hold music loops to the called party for as
  long as the call is held.
* Unhold stops the music at once; the conversation resumes where it
  left off.
* Recording and live transcription keep running during the hold.
* The bridge between you and the called party stays up for the whole
  hold, so nothing needs to be re-dialed or re-bridged on unhold.

## Scope and limits

Hold music on hold applies to outbound calls that you dialed and that
are bridged. When you hold, the platform identifies the called party's
leg on the live call and plays the track to that leg. The limits below
are by design, not defects:

* **Outbound bridged calls only.** Inbound calls are unchanged:
  placing an inbound caller on hold mutes your side and the caller
  hears silence.
* **A bridged callee leg is required.** If the call has no dialed leg
  to play to (for example, a direct agent session that never placed an
  outbound call), the call stays on silent hold.
* **Playback is best-effort.** If the music track cannot be started
  for any reason, the call is still held, just without music, exactly
  as before this feature shipped. A hold never fails because hold
  music failed.

## Which music plays

The track is resolved in this order:

1. **Your organization's hold-music override.** This is the same
   organization setting that warm transfer plays while a caller waits
   on a consultation leg. It accepts two shapes:
   * A plain `https://` URL to an audio file you host. The URL is
     checked before playback: links that point at private or internal
     addresses, or that fail validation, are refused and the platform
     default plays instead. The same applies to values longer than
     2,048 characters.
   * An uploaded audio asset handle (`audio:asset:<fileId>`, in the
     shape your uploads return). The playable link is re-signed per
     call, so an uploaded track never expires while configured. If the
     asset no longer exists, the platform default plays.
2. **The platform default hold track**, when no override is set or the
   override was refused.

There is no dedicated dashboard field for the organization-level
override today: the dashboard's hold-music fields are per queue, per
IVR node, and per conference. The organization value lives in your
organization settings' voice block, `hold_music_url`, set wherever you
update organization settings, including the Organizations API.

## Hold-treatment map

Orbit plays hold music in several places, each with its own source.
Use this map when changing what callers hear while held:

| Where the caller is held | What plays | Where it is set |
| - | - | - |
| Waiting in an ACD queue | That queue's own `holdMusicUrl`, else the platform default | Per queue, see [Voice queues](https://docs.orbit.devotel.io/guides/voice-queues.md) |
| Parked in the lobby | The park lobby's platform hold track | See [Call park lobby](https://docs.orbit.devotel.io/guides/voice-call-park-lobby.md) |
| Held during a warm-transfer consultation | The org `hold_music_url` override, else the platform default | Organization settings, voice block |
| Held by you on an outbound call (this page) | The org `hold_music_url` override, else the platform default | Organization settings, voice block |

The last two rows share one override: setting it once changes both
warm-transfer holds and manually held outbound calls. Per-queue hold
music applies to neither. An IVR node's own hold settings apply only
while the caller is inside that node.

## Troubleshooting

**The caller hears silence when I hold them.**
Expected whenever one of the scope limits applies: the call is
inbound, the call has no bridged callee leg, or the track could not
start on this call. The call is still correctly held; only the music
is absent. This is the designed fallback, not a fault.

**The wrong music plays.**
Check whether your organization has a hold-music override set: when
present and valid it replaces the platform default on warm-transfer
holds and manually held outbound calls. If you expected a queue's
music on a held outbound call, note that `holdMusicUrl` applies only
to callers waiting in that queue; see the map above.

**Is this the same as `[pause:Xs]` in prompts?**
No. `[pause:Xs]` is a prompt-authoring cue that inserts silence
between prompts while a flow plays audio to a caller; it does not
control what a held caller hears. Hold treatment is covered on this
page; prompt cues are covered in
[Prompt delivery cues](https://docs.orbit.devotel.io/guides/voice-prompt-delivery-cues.md).

## Recording and consent posture

Hold music is tenant-configured content: you choose the audio and are
responsible for having the rights to play it. Recording and live
transcription continue on held calls, so your recording-consent
posture applies during hold exactly as during the conversation; see
[Recording consent](https://docs.orbit.devotel.io/compliance/recording-consent.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.