Music on Hold Configuration

Music on Hold (MOH) plays audio to callers when they are placed on hold, waiting in a queueAn Asterisk call queue (app_queue) that parks incoming calls and distributes them to logged-in agents according to a chosen ring strategy., 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 PJSIPThe modern SIP channel driver in Asterisk (chan_pjsip), replacing the older chan_sip. Configured in pjsip.conf using endpoints, AORs, auths, and transports. endpointIn PJSIP configuration, the SIP entity Asterisk communicates with: a phone, trunk, or other user agent. Defined by an endpoint section in pjsip.conf. 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. CHANNELA single call leg passing through Asterisk. Channels represent connections to endpoints and are what dialplan applications act on.(musicclass): Overrides the MOH class for the current channel in the dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition →. 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 dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition →.
• Test MOH from the CLI: channel originate PJSIP/1001 application MusicOnHold company plays the "company" class to extensionA dialplan entry that matches a dialed number or pattern within a context and triggers a sequence of prioritized steps. 1001.