Skip to content

Configure Music on Hold

Music on Hold (MoH) plays to callers when they're on hold, in a queue, parked, or transferring. UnifiedBX ships with default MoH but most installs swap in custom audio for branding (or to comply with licensing — most stock music can't legally be used commercially).

Before You Start

  • The audio files are ready and in a UnifiedBX-compatible format (mono 8 kHz 16-bit PCM WAV preferred — same as System Recordings).
  • The class of music makes sense for your use cases (one general "Hold Music" class is enough for most; create separate classes for queue-specific or seasonal music).

Steps

Add a new MoH class

  1. Go to System Attributes → Music on Hold.
  2. Click + Add Category (or + Add MoH Class depending on version).
  3. Fill in:
    • Category Name — e.g. default-music, holiday, sales-queue. Lowercase, no spaces.
    • Application — leave blank for "play files from the directory" (the normal case). Set only for streaming/external sources.
    • Format — wav is the safest, also supports gsm, ulaw, mp3 (with mp3 module).
  4. Click Submit.

Upload music files

  1. Click the new MoH class to enter it.
  2. Click Upload File and pick a converted WAV.
  3. Repeat for each file you want in the rotation.
  4. Files must be legal for commercial use — royalty-free music libraries or licensed tracks only. Stock Asterisk music is intended for testing.
  5. Click Submit when done.
  6. Click Apply Config.

Convert audio for MoH

sox input.mp3 -r 8000 -c 1 -e signed-integer -b 16 output.wav

Use the new MoH class

The new class is now a selectable option in:

  • Group Attributes → Queues → Music on Hold Class
  • Trunk Attributes → Inbound Routes → Music On Hold
  • Group Attributes → Ring Groups → Play Music On Hold (when set to MoH instead of Ring)
  • Other modules with MoH selectors

Set the desired class in each place; old default references will continue to use the default class.

Verify

Place a call into a queue with the new MoH class. While on hold, you should hear the new music looping.

asterisk -rx "moh show classes"
asterisk -rx "moh show files"

Files should appear under your new class.

Common Issues

  • Silent on hold. Class is empty (no files uploaded), files are wrong format, or Application is set when it shouldn't be. Check moh show files.
  • Audio is choppy / robotic. Wrong sample rate. Asterisk needs 8 kHz; auto-resample sometimes mangles. Pre-convert with sox.
  • "Default" class doesn't update with new files. You may have created a NEW class — confirm you're uploading to the right one.
  • One file plays, others skipped. File format issue (one is wrong). moh show files will tell you which Asterisk loaded.
  • Caller hears ringback instead of MoH. Music was set to Ring rather than a class. Pick the actual class.
  • Licensing violation worry. Use only royalty-free music or paid commercial licenses. The Asterisk default music is for testing only.