Skip to content
Thirdlane

Music-on-Hold

Music-on-Hold (MoH) is what a caller hears while they are on hold, parked, or waiting in a queue - instead of silence, which makes people think the call has dropped. On this screen you build playlists: named groups of audio files (music, brand messages, or announcements) that the system plays while a caller waits. You can offer several playlists for different purposes - upbeat music for a sales queue, a message loop that promotes services, or a quieter track for support.

Music-on-Hold can be set at several levels and for different objects - system-wide, per Tenant, per Queue, and per User Extension. The most specific setting for a given call wins, so a queue or extension playlist overrides the tenant or system default.

Creating a playlist is a 2-step process: first create the Playlist, then add audio files to it.

Create Music-on-Hold Playlist

Name. Unique name for this Playlist.

Mode. Mode of music-on-hold. Valid modes include files, mp3, quietmp3, mp3nb, quietmp3nb, and custom. We suggest using “files” mode when possible.

Format. Codec to be used when playing this Playlist.

Application. Specify a command that will play Music-on-Hold. Only available if “custom” Mode is selected.

Random. Specifies that the files in the Playlist should be played in random order.

Options. Additional options for this Playlist.

Edit Music-on-Hold Playlist

Here you can modify all the attributes of an existing Playlist except th Name.

The bottom part of the screen allows you to upload files into the Playlist.

Building playlists via the REST API

Playlists and their audio can be created programmatically, which is useful for migrations or bulk uploads. Create the class first, then upload files into it:

Terminal window
curl "https://pbx.example.com/api/tenants/acme/musiconhold" \
  -X POST -H "X-API-Key: $TL_KEY" -H "Content-Type: application/json" \
  --data-binary '{ "class": "default", "format": "wav" }'


curl "https://pbx.example.com/api/tenants/acme/musiconhold/default/files" \
  -X POST -H "X-API-Key: $TL_KEY" -H "Content-Type: application/json" \
  --data-binary '{ "filename": "track1.wav", "audio_base64": "UklGR...", "reload": false }'

Uploaded audio is converted to the Asterisk-native format automatically. During a bulk run, send reload=false on each upload and finalize once with POST /api/tenants/{tenant}/musiconhold/reload. See the Data Migration and Import guide for details.

Best practices

  • Use files mode whenever possible (as suggested on the form) - it is the most reliable and does not depend on an external player.
  • Only use audio you are licensed to play. Commercial/radio music generally requires a license for on-hold use; royalty-free tracks or your own recordings avoid that problem.
  • Keep the loop long enough that callers do not hear the same few seconds repeat; a mix of music and short informational messages makes waiting feel shorter.
  • Turn on Random for a multi-track playlist so callers who hold often do not always hear the tracks in the same order.
  • Assign purpose-specific playlists at the Queue level rather than relying only on the system default.