VMware ESXi and vSphere Cluster Management

Understanding voicemail.conf Sections in Asterisk

Learn how Asterisk voicemail.conf uses [general], [zonemessages], and mailbox contexts to control recording, timestamps, PINs, and email notifications.

voicemail.conf is the Asterisk configuration file for voicemail behavior and mailbox definitions. It controls shared recording and notification defaults, spoken timestamp profiles, and the mailboxes that callers reach when they leave messages.

This lesson explains the structure of the file, the responsibilities of each section, mailbox fields, timezone announcements, email attachments, and a practical validation process.

Purpose and structure of voicemail.conf

Asterisk uses INI-style configuration files. A section header is written inside square brackets, such as [general]. Settings normally use the form setting=value.

[general]
option=value

[zonemessages]
profile=Region/City|playback_options

[default]
mailbox => pin,full_name,email,pager_email,options

The file has three main configuration areas:

  • [general] contains global voicemail defaults shared by users unless a mailbox-specific setting overrides an applicable default.
  • [zonemessages] defines named timezone profiles used when Asterisk speaks the date and time associated with a message.
  • Mailbox context sections contain mailbox definitions. A context is a named section such as [default]; a deployment can use one context or several.

Section responsibilities

Section: [general] — What it configures: Shared voicemail policy — Typical contents: Audio formats, sender address, attachments, silence and duration limits — Scope: Global defaults

Section: [zonemessages] — What it configures: Timezone timestamp profiles — Typical contents: Region/city identifiers and announcement options — Scope: Profiles used by voicemail playback

Section: [default] or another mailbox context — What it configures: Individual mailboxes — Typical contents: Mailbox number, PIN, name, email addresses, overrides — Scope: Mailboxes in that context

Keeping global policy separate from mailbox data makes the file easier to manage. For example, an administrator can set one recording limit in [general] and then provide a different applicable option for a particular mailbox.

The [general] section

Entries in [general] establish defaults for voicemail users. Each entry follows setting=value; whitespace and accepted values depend on the Asterisk version and the option.

[general]
format=wav49|wav
serveremail=voice@example.org
attach=yes
maxsilence=20
maxmessage=200

Important [general] options

Option: format — Purpose: Select voicemail audio storage formats — Example value: wav49|wav — Operational effect: Messages are stored in the selected formats; those files can also be used when preparing email attachments

Option: serveremail — Purpose: Set the sender address for voicemail notification email — Example value: voice@example.org — Operational effect: Notification messages use this configured sender identity

Option: attach — Purpose: Control whether audio is attached to notification email — Example value: yes — Operational effect: A recorded message is included as an email attachment when mail delivery and filtering permit it

Option: maxsilence — Purpose: Set the maximum continuous silence interval — Example value: 20 — Operational effect: Recording can stop after 20 seconds of uninterrupted silence

Option: maxmessage — Purpose: Limit recording duration in seconds — Example value: 200 — Operational effect: A caller cannot record beyond 200 seconds

Audio formats

The format setting identifies the audio format or formats Asterisk should store for voicemail. Multiple formats can be listed using the syntax supported by the configuration, as in format=wav49|wav.

wav49 is a compact WAV-related format commonly seen in legacy Asterisk voicemail configurations. Do not assume that every format is available on every installation. Confirm that the selected formats are supported by the installed Asterisk system and its sound-file handling.

Format selection affects the message files that are stored and may affect the audio files included in notification emails. Test the resulting attachment with the email clients and mail filters used by your organization.

Email sender and attachments

serveremail specifies the sender address used for voicemail notification messages. The address and its domain should be valid for the host's mail transport, relay policy, and sender-authentication rules.

attach=yes enables audio attachments for voicemail notification email. It does not by itself configure outbound mail delivery. A working mail transport is still required, and a relay or recipient security policy may remove or block audio attachments.

Silence and message-length limits

maxsilence controls how much continuous silence can occur before Asterisk ends recording. A value of 20 permits up to 20 seconds of uninterrupted silence before silence-based termination can occur.

A zero silence limit disables silence-based recording termination. This does not remove the maximum message-duration limit.

maxmessage is the maximum permitted recording duration, measured in seconds. With maxmessage=200, the caller cannot record a message longer than 200 seconds even if the caller continues speaking.

Choose limits that fit the organization. A short silence threshold may cut off callers who pause naturally, while a very long threshold can create recordings containing unwanted quiet time. The maximum duration should be long enough for useful messages but constrained enough to protect storage and email capacity.

Voicemail message recording and delivery policy

Recording policy and delivery policy are connected:

  • format determines the audio files Asterisk stores and the audio material available for delivery.
  • attach determines whether notification email should include a voicemail audio attachment.
  • maxsilence can end a recording when the caller remains quiet continuously for the configured interval.
  • maxmessage imposes an absolute recording-duration ceiling in seconds.

For example, the settings below allow two storage formats, attach the recording to notification email, stop after 20 seconds of continuous silence, and cap each message at 200 seconds:

[general]
format=wav49|wav
serveremail=voice@example.org
attach=yes
maxsilence=20
maxmessage=200

Mailbox-specific options can override applicable global defaults. Use overrides deliberately: they are useful for exceptions, but too many per-mailbox policies make troubleshooting harder.

The [zonemessages] section

[zonemessages] defines named timezone profiles for spoken voicemail timestamps. A profile tells Asterisk which timezone rules to use and how to phrase the received-message timestamp.

The general entry pattern is:

custom_zone_name=region/city|playback_options

The name on the left is chosen by the administrator. It is a profile label, not necessarily a city name. The region/city value is an IANA timezone identifier, such as Europe/Berlin. IANA identifiers refer to timezone rules, including offset changes and daylight-saving behavior.

On many Linux systems, available timezone definitions are installed below:

/usr/share/zoneinfo

If an exact place name is unavailable, choose an equivalent region/city identifier whose timezone rules match the subscriber's location. Matching the rules is more important than matching the display name.

The text after the pipe character contains timezone playback options. These tokens control the prompts and time format used when Asterisk announces a message timestamp. A prompt token can select the received-message announcement, and the R option is associated with 24-hour clock playback.

Timezone and timestamp announcement example

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

Timezone profile components

Component: berlin — Example: berlin — Meaning: Administrator-selected profile name

Component: IANA timezone identifier — Example: Europe/Berlin — Meaning: Timezone rules used for the timestamp

Component: Received-message prompt — Example: 'vm-received' — Meaning: Prompt token for announcing that the message was received

Component: Additional prompt — Example: Q 'digits/at' — Meaning: Prompt and wording controls for the spoken timestamp

Component: Clock-format option — Example: R — Meaning: Enables 24-hour time rendering

In this example, berlin is only the local profile name. Europe/Berlin supplies the actual timezone rules. The quoted prompt token selects the received-message announcement, while Q, digits/at, and R control the announcement wording and clock representation according to the installed Asterisk prompt behavior.

Assign the appropriate timezone profile to a mailbox or use it through the voicemail playback behavior required by the installed Asterisk version. A profile is useful when subscribers should hear timestamps in their local time rather than the server's timezone. Verify the assignment with a test voicemail.

Mailbox context sections

Mailbox definitions belong in user-defined context sections. [default] is the conventional context:

[default]
1001 => 4321,Ada Example,ada@example.org

A small deployment may use only [default]. Larger systems can use multiple contexts to separate departments, tenants, customers, or different voicemail policies.

The mailbox context is operationally significant. A voicemail application looks up a mailbox by its number and context. Asterisk commonly uses the default context when the application call does not supply a context explicitly. In a multi-context system, explicitly naming the context avoids ambiguity.

Mailbox definitions use the => operator followed by comma-separated fields:

mailbox => pin,full_name,email,pager_email,options

Mailbox entry fields

Position: Before => — Field: Mailbox number — Meaning: Identifier used to locate the voicemail box, commonly the extension number — Example: 1001 — Required or optional: Required

Position: 1 — Field: PIN or password — Meaning: Numeric credential used to access the mailbox — Example: 4321 — Required or optional: Normally required for protected access

Position: 2 — Field: Subscriber display name — Meaning: Name associated with the mailbox for prompts or notification context — Example: Ada Example — Required or optional: Commonly supplied; behavior for omission depends on version and use

Position: 3 — Field: Primary email address — Meaning: Destination for full voicemail notifications — Example: ada@example.org — Required or optional: Optional if email notification is not needed

Position: 4 — Field: Pager or mobile email — Meaning: Destination for short alert notifications — Example: alert@example.org — Required or optional: Optional

Position: 5 and later — Field: Per-mailbox options — Meaning: Overrides for applicable defaults or mailbox behavior — Example: Version-appropriate option data — Required or optional: Optional

Fields are positional. If an earlier optional field is omitted but a later field is needed, retain the comma delimiters so the value remains in the correct position. For example, an empty pager field must still leave its separator before an options field. Consult the documentation for the installed Asterisk version when using advanced mailbox options.

Protect mailbox PINs and the configuration file itself. Mailbox definitions may contain credentials, personal names, and email addresses. Use appropriate file ownership and permissions, and avoid exposing the file through backups or general user access.

Building a basic voicemail configuration

The following example combines global defaults, a Berlin timezone profile, and a mailbox in the default context:

[general]
format=wav49|wav
serveremail=voice@example.org
attach=yes
maxsilence=20
maxmessage=200

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

[default]
1001 => 4321,Ada Example,ada@example.org

Here is what happens:

  1. Mailbox 1001 is identified by the same number commonly used for the subscriber's extension.
  2. 4321 is the mailbox PIN. In a real deployment, use a non-obvious credential and protect it.
  3. Ada Example is the subscriber name.
  4. ada@example.org receives the full voicemail notification.
  5. The mailbox inherits the applicable global audio, attachment, silence, and duration settings.
  6. Because attach=yes is enabled, a recorded message is included with notification email when the mail transport and recipient policies allow attachments.

A dialplan can target the mailbox and context explicitly:

same => n,VoiceMail(1001@default)

VoiceMail is an Asterisk dialplan application that sends a caller to a mailbox for recording or voicemail access, depending on how it is invoked. In this example, 1001 is the mailbox and default is the context. Both must match the configuration entry.

Validation and operational checklist

  • Confirm that every selected audio format is supported by the installed Asterisk system.
  • Verify that serveremail uses a sender address and domain accepted by the configured mail transport.
  • Check mailbox email addresses for spelling and valid formatting.
  • Protect voicemail PINs and configuration-file permissions.
  • Confirm that timezone identifiers exist on the host and correspond to the subscriber's actual timezone rules.
  • Verify that the intended timezone profile is assigned or used for the mailbox's voicemail playback.
  • Reload or restart the relevant Asterisk configuration after editing, following the procedure appropriate to the installed version and local operating practices.
  • Place a test call and leave a message.
  • Listen for the spoken timestamp and verify its local time and clock format.
  • Test natural pauses to confirm that maxsilence does not end messages too early.
  • Test a long recording to confirm the maxmessage limit.
  • Verify that the notification arrives and that its audio attachment is present and playable.

Troubleshooting common problems

Timestamps use the wrong local time

Check whether the mailbox is using the wrong profile, whether the region/city identifier is incorrect, or whether the host lacks the expected timezone data. Compare the configuration with entries below /usr/share/zoneinfo, select a region/city identifier with the correct offset and daylight-saving rules, and leave a test voicemail.

Email arrives without the recording

Confirm that the effective configuration has attach=yes. If it does, inspect the mail transport and recipient filtering policies because they may remove or block audio attachments. Also verify that the selected stored format produces a file that the recipient can handle.

Recording ends too soon

Review maxsilence and maxmessage. Increase the silence interval if callers pause naturally, or use a zero silence limit when silence-based termination is inappropriate. Increase the maximum duration only when organizational policy and storage capacity permit it. Test with realistic pauses.

Asterisk says the mailbox does not exist

Match the mailbox number exactly to the VoiceMail argument, verify the context, and apply the configuration reload required by the installation. An explicit target such as 1001@default helps avoid selecting the wrong context.

Notification email is not delivered

Check the mailbox email field, the serveremail sender identity, outbound mail permissions, relay settings, and local mail-service logs. After correcting the issue, place another test call and verify delivery.

Key points for administrators

  • voicemail.conf separates shared defaults, timestamp profiles, and mailbox data.
  • [general] controls organization-wide defaults such as formats, email sender, attachments, silence, and maximum duration.
  • [zonemessages] maps administrator-selected profile names to IANA timezone identifiers and timestamp prompts.
  • A mailbox context, often [default], determines where Asterisk looks for mailbox definitions.
  • Mailbox fields are positional, so omitted values must preserve comma delimiters.
  • Use explicit mailbox contexts in dialplan applications when more than one context exists.
  • Always validate with a real test call, including recording behavior, timestamp playback, and email delivery.

For related configuration work, see the sections of the voicemail.conf file and then apply the same mailbox and context concepts when configuring voicemail applications in the dialplan.