VMware ESXi and vSphere Cluster Management

Configuring Asterisk Voicemail with voicemail.conf

Learn how to configure Asterisk voicemail.conf global settings, recording formats, time zones, mailbox contexts, email notifications, dialplan integration, and CLI verification.

voicemail.conf is Asterisk's primary configuration file for its VoiceMail system. It defines voicemail-wide defaults, recording and delivery behavior, time-zone announcements, and mailbox identities. It does not create a call route by itself: the dialplan must use the VoiceMail application to let callers leave messages and VoiceMailMain to let subscribers retrieve and manage them.

This lesson assumes that you can edit Asterisk configuration files, access the Asterisk CLI, and understand basic dialplan contexts and extensions. The usual file location is /etc/asterisk/voicemail.conf, although an installation may use a different configuration directory.

For a quick reference, see the voicemail.conf reference.

How voicemail.conf is organized

The file uses an INI-style structure. A section name appears in square brackets, and most settings use key=value syntax. Mailbox definitions use an arrow:

[section-name]
option=value
mailbox-number => mailbox-options

Blank lines and comments make a configuration easier to maintain. In the standard file, comments commonly begin with a semicolon. Keep comments focused on policy or intent, and do not place real PINs in comments or examples.

Section	Purpose	Representative settings	Relationship to other configuration
`general`	Voicemail-wide defaults	`format`, `serveremail`, `attach`, recording limits	Applies broadly unless a supported mailbox or system setting changes behavior
`zonemessages`	Named time-zone and announcement definitions	Berlin or New York zone labels and prompt sequences	Mailbox options refer to a zone label defined here
`default` or another mailbox context	Groups mailbox definitions	Mailbox number, PIN, name, email, and options	The dialplan must use the same context when addressing the mailbox

Global settings in the general section

The [general] section establishes defaults for recording and notification behavior.

[general]
format=wav|wav49
serveremail=voicemail@example.invalid
attach=yes
maxsilence=8
maxmessage=200

Option	Applies to	Meaning	Example value type	Operational impact
`format`	Recorded message files	A pipe-separated list of permitted audio formats	`wav\|wav49`	More formats improve compatibility but consume additional storage
`serveremail`	Notification messages	The sender identity used for voicemail-to-email messages	An email address	The mail system may require the address to be valid or authorized
`attach`	Email notifications	Controls whether the recording is included as an attachment	`yes` or `no`	Attachments increase message size and may raise confidentiality concerns
`maxsilence`	Recording behavior	A silence-detection threshold, measured in seconds	An integer such as `8`	A low value can end recordings during natural pauses; a high value can retain unwanted silence
`maxmessage`	Recording duration	The maximum voicemail length, in seconds	An integer such as `200`	Limits storage use and keeps recording policy predictable

Choosing recording formats

format accepts a pipe-separated list. wav is broadly useful for playback and external processing but generally requires more storage. wav49 is commonly associated with a WAV container carrying GSM-compressed audio. It can reduce storage and support common voicemail workflows, but compatibility should be tested with the phones, mail clients, and applications used by your organization.

Creating two representations means that a single message can consume more disk space. Select formats based on playback interoperability, storage capacity, backup volume, and any audio-processing requirements.

Email and recording policy

serveremail is the sender identity placed on notification messages; it is not a replacement for configuring a local mail transfer agent or SMTP relay. attach=yes tells Asterisk to include the audio when sending a notification, subject to the available mail configuration and message-size limits.

maxsilence helps stop a recording after sustained silence. Ambient noise, pauses, and the quality of the audio path affect the result, so test it with realistic calls. maxmessage is a hard maximum recording duration in seconds. Choose both values consistently with your storage budget, mail limits, and documented voicemail policy.

Time-zone announcements with zonemessages

When Asterisk tells a subscriber when a message arrived, it needs a named time zone. Use a location-based IANA time zone, such as Europe/Berlin, rather than an ambiguous abbreviation such as CET. IANA names represent regional rules, including daylight-saving changes.

A zonemessages entry contains a zone label, an IANA identifier, and a prompt sequence:

[zonemessages]
berlin=Europe/Berlin|'vm-received' Q 'digits/at' IMp

In this representative pattern, berlin is the label used by mailboxes, Europe/Berlin supplies the regional time-zone rules, and the prompt sequence tells Asterisk how to announce the received-message phrase, date, the word “at,” and the time. The exact prompt names and format specifiers depend on the Asterisk version and installed sound prompts. Use the syntax shipped with your version and test the spoken result; do not assume that every prompt token is available in every sound package.

A mailbox can reference the label with an option such as tz=berlin. The label must match exactly, and it must be defined under [zonemessages].

Mailbox contexts and definitions

A mailbox context is a section that namespaces mailbox definitions. The familiar [default] section is one context, but an administrator can create other contexts to separate departments or tenants. The fully qualified identity of a mailbox includes both its number and context, commonly written as 444@default.

[default]
; Use a non-production placeholder PIN in documentation.
444 => CHANGE-ME,Alex Morgan,alex@example.invalid,,tz=berlin

The standard fields are comma-separated. A common mailbox definition has the following structure:

Field position	Purpose	Example type	Security or validation notes
Mailbox number	Numeric identity dialed or supplied to voicemail applications	`444`	Must match the dialplan reference
PIN	Authentication code for subscriber access	A private numeric code	Use distinct, non-predictable values; never publish real PINs
Subscriber name	Display and spoken identity associated with the mailbox	`Alex Morgan`	Check spelling because it affects user-facing prompts
Email address	Notification recipient when email integration is enabled	`alex@example.invalid`	Validate the address and mail delivery path
Pager field	Legacy or optional notification field in the mailbox layout	Empty value: `,,`	Preserve the field position before later options
Optional attributes	Additional mailbox behavior	`tz=berlin`	Reference only labels and options supported by the installed Asterisk version

The empty field before tz=berlin is intentional: it preserves the pager position. A representative definition is therefore 444 => PIN,name,email,pager,options, often written with an empty pager field as 444 => CHANGE-ME,Alex Morgan,alex@example.invalid,,tz=berlin. Replace the placeholder with a real private PIN only on the server, and protect the file from unauthorized reading.

Subscriber email addresses affect where notifications are delivered. They do not guarantee delivery: Asterisk also needs a functioning local mail-transfer agent or SMTP path. Mailbox configuration alone does not create an extension, route, or subscriber login code.

Complete example and interpretation

[general]
format=wav|wav49
serveremail=pbx@example.invalid
attach=yes
maxsilence=8
maxmessage=200

[zonemessages]
berlin=Europe/Berlin|'vm-received' Q 'digits/at' IMp

[default]
444 => CHANGE-ME,Alex Morgan,alex@example.invalid,,tz=berlin

format=wav|wav49: Asterisk is configured to create two audio representations, improving compatibility at the cost of storage.
serveremail=pbx@example.invalid: Notifications use this PBX sender identity. The address must be accepted by the configured mail system in a real deployment.
attach=yes: Notification messages should include the recording, so administrators must consider mail-size limits and the sensitivity of voicemail audio.
maxsilence=8 and maxmessage=200: Sustained silence can end a recording, and no recording can exceed 200 seconds. These are policy examples, not universal defaults.
berlin=Europe/Berlin|...: The reusable label berlin maps to regional rules for Berlin and is used by the mailbox.
444 => ...: The mailbox number is 444, its context is default, and its context-qualified identity is 444@default.
Alex Morgan: This is the subscriber name used in mailbox behavior and prompts.
alex@example.invalid: This is the intended notification recipient in the example.
tz=berlin: Received-message announcements use the Berlin zone definition.

Connecting voicemail.conf to the dialplan

The VoiceMail dialplan application deposits a caller into a selected mailbox. The VoiceMailMain application gives a subscriber access to playback and message management. They represent separate journeys: leaving a message and checking messages.

; Illustrative dialplan references
same => n,VoiceMail(444@default)
same => n,VoiceMailMain(444@default)

The exact extension and call-flow logic depend on the dialplan. The important rule is that the mailbox number and context supplied to the application must match the definition in voicemail.conf. For example, VoiceMail(444@default) addresses mailbox 444 in the default context. A configured mailbox does not automatically make unanswered calls reach voicemail or create a voicemail access extension.

Exam-relevant distinction: voicemail.conf defines voicemail resources; the dialplan decides when callers invoke VoiceMail and how subscribers invoke VoiceMailMain.

Reloading and verifying the configuration

After saving the file, use the Asterisk CLI to reload voicemail settings rather than restarting the entire PBX:

voicemail reload

Then list the users recognized by the running Asterisk instance:

voicemail show users

Command	When to use it	Expected result	What a failure suggests
`voicemail reload`	After editing `voicemail.conf`	The voicemail configuration is reread without a full PBX restart	Syntax errors, wrong file path, wrong running instance, or a module/configuration problem
`voicemail show users`	After reloading or when diagnosing a mailbox	The mailbox number, context, name, and recognized mailbox information are listed	The mailbox was not parsed, is under an unintended context, or the reload was not applied

Inspect the listing for the expected mailbox number, context-qualified identity, subscriber name, and other information that your Asterisk version displays. Do not treat this command as proof that email delivery works: validate the recipient and sender settings separately and inspect mail logs.

After a successful reload, place a real test call. Confirm that the dialplan reaches the intended mailbox, a message is recorded, the subscriber can retrieve it, and any expected email notification arrives.

Troubleshooting common problems

Mailbox is missing from the user listing

Check the mailbox delimiter, field order, and section header.
Confirm that the mailbox is under the intended context, such as [default].
Run voicemail reload and inspect CLI warnings.
Run voicemail show users and verify the context-qualified identity.
Make sure you are inspecting the Asterisk instance and configuration path that actually serve calls.

Caller reaches voicemail but the mailbox is unavailable

Compare the VoiceMail argument with the mailbox number and context in the file.
Confirm that the mailbox appears in voicemail show users.
Check the console during the test call for application errors and malformed mailbox identifiers.

Recording exists but no email arrives

Validate the mailbox email field and the serveremail value.
Confirm that the desired attachment behavior is enabled.
Check SMTP or local mail-transfer configuration and its logs.
Send a short test message; a longer recording may exceed a mail-system size limit.

Message date or time is wrong

Confirm that the mailbox's tz label exactly matches a zonemessages entry.
Verify the IANA identifier, such as Europe/Berlin, is appropriate for the subscriber.
Check the prompt sequence and installed sound prompts for the running Asterisk version.
Test around daylight-saving transitions when local rules matter.

Recordings end too soon or run too long

Review maxsilence and test normal speech with realistic pauses.
Review maxmessage, whose unit is seconds.
Investigate the audio path if callers experience unexpected silence.
Adjust values according to documented voicemail policy, then reload and retest.

Operational and security checks

Verify that the Asterisk process can write to voicemail storage and that the filesystem has sufficient free space.
Plan retention, quotas, backups, and monitoring as the mailbox count grows.
Confirm that the mail-transfer agent or SMTP relay is reachable and authorized to send from serveremail.
Use distinct, non-predictable PINs. Replace default or weak credentials.
Do not expose PINs in documentation, source control, tickets, backups shared outside the administration team, or configuration exports.
Consider whether attaching voicemail audio to email is appropriate for the organization's confidentiality and compliance requirements.

End-to-end validation checklist

Review section headers and mailbox field order, including the pager field position.
Check that every mailbox time-zone label exists in [zonemessages].
Reload with voicemail reload.
Confirm the mailbox with voicemail show users.
Place a call through the deposit route and leave a short message.
Retrieve the message with the subscriber's VoiceMailMain route.
Verify recording storage, playback, notification recipient, and mail logs.
Document the chosen limits, retention policy, backup plan, and PIN-management process without documenting the PIN values themselves.