Setting Up Voicemail in Asterisk

Voicemail is one of the first things people ask about after getting phones to ring. Two applications do the work: VoiceMail() records messages, VoiceMailMain() lets users listen to them. Configuration lives in voicemail.conf.

A minimal voicemail.conf

Open /etc/asterisk/voicemail.conf and start with this:

[general]
format = wav|gsm
serveremail = asterisk@yourdomain.com
attach = yes
maxmsg = 100
maxsecs = 180
minsecs = 2
maxsilence = 5
silencethreshold = 128
maxgreet = 60

[zonemessages]
eastern = America/New_York|'vm-received' Q 'digits/at' IMp
central = America/Chicago|'vm-received' Q 'digits/at' IMp
pacific = America/Los_Angeles|'vm-received' Q 'digits/at' IMp

[default]
200 => 7391,Desk Phone,user@example.com,,tz=eastern
201 => 8254,Softphone,user2@example.com,,tz=eastern

The [general] section controls global behavior. The [zonemessages] section defines how timestamps are read back to users (so "received Tuesday at 3:15 PM" sounds right for their timezone). The [default] section is where mailboxes live.

Each mailbox line follows this format:

extension => password,name,email,pager,options

The password is what users enter to check their messages. Because VoiceMailMain() reads DTMF digits from the phone keypad, use a numeric PIN such as 7391. The email address gets notifications when new messages arrive (if you have mail configured on the server).

Applying the changes

After editing voicemail.conf, load the new mailboxes:

asterisk -rx "voicemail reload"

After editing extensions.conf (or any included dialplan file), load the new dialplan:

asterisk -rx "dialplan reload"

If you change PJSIP endpoint settings such as mailboxes, reload PJSIP as shown in the MWI section.

Connecting voicemail to the dialplan

The typical dialplan pattern: ring the phone, if nobody answers, send to voicemail.

[internal]
exten => 200,1,Dial(PJSIP/200,25)
same => n,GotoIf($["${DIALSTATUS}" = "NOANSWER"]?vm)
same => n,Hangup()
same => n(vm),VoiceMail(200@default,u)
same => n,Hangup()

VoiceMail(200@default,u) records a message in mailbox 200 in the [default] context. The u flag plays the "unavailable" greeting. If you want a "busy" greeting instead (for when the line is actually busy rather than unanswered), use b:

; Ring the phone, handle busy vs no-answer differently
exten => 200,1,Dial(PJSIP/200,25)
same => n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy)
same => n,GotoIf($["${DIALSTATUS}" = "NOANSWER"]?unavail)
same => n,Hangup()
same => n(unavail),VoiceMail(200@default,u)
same => n,Hangup()
same => n(busy),VoiceMail(200@default,b)
same => n,Hangup()

Letting users check their messages

Users need a way to dial in and listen to voicemail. VoiceMailMain() handles the entire menu: listen, save, delete, change greetings, change password.

[internal]
; Dial *98 to check voicemail
exten => *98,1,VoiceMailMain(${CALLERID(num)}@default)
same => n,Hangup()

; Dial *97 to check another mailbox (prompts for mailbox number)
exten => *97,1,VoiceMailMain(@default)
same => n,Hangup()

The first version auto-fills the mailbox based on caller ID, so extension 200 calling *98 goes straight to mailbox 200 and only needs the password. The second version prompts for a mailbox number first, useful for shared phones or checking messages from a conference room.

Message waiting indicators

MWI is the blinking light (or visual indicator on a softphone) that tells users they have new voicemail. PJSIP endpoints need the mailboxes setting to subscribe:

[200]
type = endpoint
context = internal
mailboxes = 200@default

Reload PJSIP to apply the endpoint changes:

asterisk -rx "pjsip reload"

When a new message arrives in mailbox 200, Asterisk sends a SIP NOTIFY to the phone. The phone lights up its message waiting lamp. When the user listens to all new messages, the light turns off.

If the light is not working, check two things: the mailboxes line matches the voicemail context (200@default in both pjsip.conf and voicemail.conf), and the phone actually supports MWI (most do, but some softphones need it enabled in their settings).

Email notifications

If the attach setting is yes in [general] and the mailbox has an email address, Asterisk sends an email with the recording attached every time someone leaves a message. The email includes the caller ID, timestamp, and duration.

This requires a working mail setup on the server. At minimum, you need sendmail or postfix installed and able to deliver outbound mail. Test it:

echo "test" | mail -s "voicemail test" you@example.com

If that arrives, voicemail email will work. If not, fix your mail configuration first.

You can also have Asterisk delete the voicemail after emailing it, so the mailbox never fills up:

[default]
200 => 7391,Desk Phone,user@example.com,,tz=eastern|delete=yes

This is useful when users treat email as their primary voicemail interface and never dial in to check messages.

Voicemail contexts

The [default] context in the examples above is just a name. You can create as many contexts as you need. Each one is an independent group of mailboxes with its own numbering space.

Why use multiple contexts

Extension numbers only need to be unique within a context. If you have two tenants sharing one Asterisk server and both want extension 100, separate contexts solve it:

[tenant-a]
100 => 5100,Reception A,reception@tenant-a.com,,tz=eastern
101 => 5101,Sales A,sales@tenant-a.com,,tz=eastern

[tenant-b]
100 => 5100,Reception B,reception@tenant-b.com,,tz=pacific
101 => 5101,Sales B,sales@tenant-b.com,,tz=pacific

VoiceMail(100@tenant-a,u) and VoiceMail(100@tenant-b,u) are completely separate mailboxes with separate greetings, passwords, and message stores.

Departmental separation

Even on a single-tenant system, contexts can separate departments so each group has its own voicemail settings:

[sales]
300 => 1300,Alice,alice@company.com,,tz=eastern
301 => 1301,Bob,bob@company.com,,tz=eastern

[support]
400 => 1400,Carol,carol@company.com,,tz=eastern
401 => 1401,Dave,dave@company.com,,tz=eastern

The dialplan routes to the correct context:

[internal]
exten => _3XX,1,Dial(PJSIP/${EXTEN},25)
same => n,GotoIf($["${DIALSTATUS}" = "NOANSWER"]?vm)
same => n,Hangup()
same => n(vm),VoiceMail(${EXTEN}@sales,u)
same => n,Hangup()

exten => _4XX,1,Dial(PJSIP/${EXTEN},25)
same => n,GotoIf($["${DIALSTATUS}" = "NOANSWER"]?vm)
same => n,Hangup()
same => n(vm),VoiceMail(${EXTEN}@support,u)
same => n,Hangup()

; Sales team checks voicemail
exten => *98,1,VoiceMailMain(${CALLERID(num)}@sales)
same => n,Hangup()

This matters when different departments need different email templates, retention policies, or timezone settings. Each context can have its own delete=yes, timezone, and notification behavior through the per-mailbox options.

MWI with non-default contexts

If you use a context other than [default], the PJSIP endpoint's mailboxes line must match:

[300]
type = endpoint
context = internal
mailboxes = 300@sales

The format is always mailbox@context. If these do not match between pjsip.conf and voicemail.conf, the MWI light will not work.

Recording custom greetings

Users can record their own greetings through the VoiceMailMain() menu (option 0 from the main menu, then option 1 for unavailable or 2 for busy). But you can also record greetings from the CLI for initial setup:

asterisk -rx "voicemail show users"

This lists all configured mailboxes. Greetings are stored as files in the mailbox directory, typically /var/spool/asterisk/voicemail/default/200/. The unavailable greeting is unavail.wav and the busy greeting is busy.wav.

Common problems

"No such voicemail context" means the context name in VoiceMail(200@default) does not match any section header in voicemail.conf. Usually a typo.

Messages record but email never arrives. Check /var/log/mail.log. Asterisk hands the message to the system mailer and does not report failures loudly. If mail -s "test" you@example.com does not arrive, voicemail email won't either.

MWI light stays off. The mailboxes value in pjsip.conf must exactly match the mailbox@context format in voicemail.conf. Some softphones also need MWI explicitly enabled in their account settings.

maxsilence cuts off messages too early. Callers who pause while thinking get disconnected. Increase it, but keep it under 10 or pocket dials will fill the mailbox with empty recordings.

Password rejected. The password in voicemail.conf is only the initial password. By default, when a user changes it through the VoiceMailMain() menu, Asterisk writes the new PIN back to voicemail.conf. If you have set passwordlocation=spooldir, the PIN is stored in /var/spool/asterisk/voicemail/default/200/secret.conf instead. To reset, edit voicemail.conf (or remove secret.conf) and run voicemail reload.

What to read next

• Voicemail with Email Notification for a more detailed email setup
• Voicemail.conf Configuration Reference for every option in the config file
• VoiceMail() application reference for all flags and arguments
• VoiceMailMain() application reference for the user-facing menu