Music on Hold Configuration

Music on Hold (MOH) plays audio to callers when they are placed on hold, waiting in a queue, or parked. Asterisk supports multiple MOH classes, each pointing to a different directory of audio files.

MOH Class Definition (musiconhold.conf)

[default]
mode = files
directory = moh
sort = random

[company]
mode = files
directory = company/mohmp3
sort = random

[queue-sales]
mode = files
directory = custom/sales-moh
sort = alpha

Directory Setup

# Default MOH directory (usually pre-populated)
ls /var/lib/asterisk/moh/

# Create custom MOH directories
mkdir -p /var/lib/asterisk/company/mohmp3
mkdir -p /var/lib/asterisk/custom/sales-moh

# Upload audio files (WAV, MP3, or other supported formats)
cp company-jingle.wav /var/lib/asterisk/company/mohmp3/
cp sales-promo-1.wav /var/lib/asterisk/custom/sales-moh/
cp sales-promo-2.wav /var/lib/asterisk/custom/sales-moh/

Assigning MOH to Endpoints (pjsip.conf)

[1001](endpoint-internal)
auth = 1001-auth
aors = 1001
callerid = Alice Smith <1001>
moh_suggest = company

Using MOH in Dialplan

[queues]
; Queue with custom MOH class
exten => 100,1,Answer()
 same => n,Set(CHANNEL(musicclass)=queue-sales)
 same => n,Queue(sales,,,,120)
 same => n,Hangup()

; Explicit MOH during a hold/transfer
exten => 200,1,Answer()
 same => n,Set(CHANNEL(musicclass)=company)
 same => n,Dial(PJSIP/1001,30)
 same => n,Hangup()

Verify and Reload

*CLI> moh reload
*CLI> moh show classes
*CLI> moh show files

How it works

1. mode = files: Asterisk reads audio files from the specified directory. This is the simplest and most common mode. Other modes include custom (pipe audio from an external command like mpg123) and mp3nb (non-blocking MP3 streaming).
2. directory: Relative paths are resolved from /var/lib/asterisk/. So directory = moh means /var/lib/asterisk/moh/. You can also use absolute paths.
3. sort: random shuffles the playlist each time. alpha plays files in alphabetical order. randstart starts at a random position but plays sequentially from there.
4. moh_suggest: Set on a PJSIP endpoint to specify which MOH class the caller hears when this endpoint puts them on hold. The phone sends a re-INVITE with sendonly SDP, and Asterisk starts playing the suggested MOH class.
5. CHANNEL(musicclass): Overrides the MOH class for the current channel in the dialplan. This takes priority over moh_suggest from the endpoint.

Tips

• At least one audio file must exist in the directory or the MOH class will fail to load. Check with moh show files.
• Convert audio to Asterisk-native format for best performance: sox input.mp3 -r 8000 -c 1 output.wav.
• For streaming internet radio, use mode = custom with application = /usr/bin/mpg123 -q -s --mono -r 8000 http://stream-url.
• The default class is used when no specific class is requested. Always keep it populated.
• Queue MOH is set with the musicclass parameter in queues.conf, or by setting CHANNEL(musicclass) before calling Queue() in the dialplan.
• Test MOH from the CLI: channel originate PJSIP/1001 application MusicOnHold company plays the "company" class to extension 1001.