VMware ESXi and vSphere Cluster Management

Using the Asterisk VoiceMailMain Application

Learn how to configure Asterisk VoiceMailMain for mailbox login, message retrieval, greeting management, authentication, testing, and troubleshooting.

VoiceMailMain is the Asterisk dialplan application that lets voicemail subscribers log in to their mailboxes and manage them. After authentication, a user can listen to messages, move between message folders, save or delete messages, change mailbox options, and record personal greetings.

This guide assumes that you already understand basic Asterisk dialplan concepts and have created voicemail mailboxes. For message deposit, use the related voicemail applications and routing concepts appropriate to your deployment.

What VoiceMailMain Does

A mailbox is a voicemail account identified by a mailbox number. It has an authentication password, message storage, and voicemail settings. VoiceMailMain provides the mailbox-owner interface: it authenticates the subscriber and opens the voicemail menu.

Do not confuse VoiceMailMain with VoiceMail:

Once logged in through VoiceMailMain, a subscriber can usually:

• Listen to new, old, saved, and other available message folders.
• Navigate between folders and messages.
• Save, delete, or otherwise manage messages according to the configured menu.
• Change supported mailbox options.
• Record or replace personal greetings.
• Exit the voicemail system.

Menu prompts and exact keypresses can vary with the installed Asterisk version, language, and voicemail configuration.

VoiceMailMain Dialplan Syntax

The general application form is:

VoiceMailMain([mailbox[@context]][,options])

Both the mailbox argument and the options argument are optional. With no mailbox argument, VoiceMailMain asks the caller for a mailbox number. With a mailbox supplied, the caller is normally taken directly to authentication for that mailbox.

Supplying a mailbox does not normally remove the password requirement. The caller must still enter the mailbox password unless a supported authentication-bypass option is deliberately used in a trusted context.

Check the Installed Application Documentation

Asterisk versions may support different options or behaviors. Query the running installation rather than relying on a guide written for another version:

asterisk -rx "core show application VoiceMailMain"

Choosing a Mailbox Selection Design

A shared number is simple to publish and maintain, especially when many users need the same access method. Direct access can reduce prompts and make an individual extension convenient, but the dialplan must reference the correct mailbox and context. In either design, normal password authentication should remain enabled unless there is a specific, reviewed reason to change it.

Mailbox Configuration Dependency

VoiceMailMain cannot authenticate a user unless the mailbox, password, and voicemail context already exist. Mailbox definitions are commonly stored in voicemail.conf, although a deployment may use another supported configuration mechanism.

A conceptual mailbox definition looks like this:

[default]
444 => 2587,Example User

In this example, mailbox 444 is in the default voicemail context, and 2587 is its sample password. The exact fields and configuration format can vary by Asterisk version and deployment method. Never reuse this sample password in production; use a strong, unique mailbox password.

For a shared access code using VoiceMailMain(), the login sequence is:

1. The user dials the feature code.
2. Asterisk prompts for a mailbox number because the application call did not specify one.
3. The user enters 444.
4. Asterisk prompts for the mailbox password.
5. The user enters the configured password, such as the instructional value 2587.
6. The user reaches the mailbox menu.

You can inspect configured users where the installation supports the relevant CLI command:

asterisk -rx "voicemail show users"

Building an Internal Voicemail Feature Code

A dialplan is Asterisk's call-routing logic. It maps a context, extension, and priority to applications. A feature code is a short dialable number assigned to a PBX feature. The following example gives internal users a shared voicemail login number:

exten => *99,1,NoOp(Shared voicemail access)
 same => n,VoiceMailMain()

NoOp means “no operation.” It does not change the call flow, but it adds an informational line to Asterisk logging and can help identify the call path during troubleshooting. The first priority logs the call, and the next priority invokes VoiceMailMain. When the application finishes, the call follows the remaining dialplan behavior or terminates according to the surrounding context.

The context containing *99 must be reachable by the intended internal extensions. Adding the extension to an unreachable context does not make the feature available. Also check for conflicting patterns or feature codes that could match the dialed digits first.

Direct Access to a Known Mailbox

This example sends a caller to authentication for mailbox 444 in the default voicemail context:

exten => 444,1,NoOp(Direct mailbox access)
 same => n,VoiceMailMain(444@default)

The context after the @ must match the context in the mailbox configuration. Normal password authentication remains in effect unless an option supported by the installed version changes it.

Password Authentication and Security

Authentication is the process of verifying that a caller is authorized to access a mailbox. VoiceMailMain normally uses the selected mailbox number together with that mailbox's password. A caller who knows only a mailbox number should not be able to manage the mailbox.

• Use unique passwords that are not extensions, birthdays, sequential numbers, or other easily guessed values.
• Do not use instructional credentials such as 2587 in a live system.
• Do not place mailbox passwords in dialplan comments, tickets, screenshots, or shared documentation.
• Restrict voicemail-management access to internal users when external access is unnecessary.
• Review call forwarding, trunk access, and other routes that could expose the feature code to untrusted callers.
• Use password-skipping behavior only when the call path is strongly trusted and the security consequences have been evaluated.

A direct mailbox reference is not itself a security control. It selects an account; it does not prove the caller is the account owner. Protect the route and retain password authentication unless a carefully controlled design requires otherwise.

Typical User Workflow

Shared Access Workflow

1. An authorized extension dials *99.
2. The dialplan executes VoiceMailMain().
3. Asterisk asks for the mailbox number.
4. The user enters the mailbox number.
5. Asterisk asks for the mailbox password.
6. After successful authentication, the user enters the voicemail menu.
7. The user retrieves messages, changes folders, deletes or saves messages, records greetings, or changes available options.
8. The user logs out or hangs up.

Direct Access Workflow

1. The user dials an extension whose dialplan invokes VoiceMailMain(444@default).
2. Asterisk already knows the mailbox and context, so it normally skips the mailbox-number prompt.
3. The user enters the password for mailbox 444.
4. Successful authentication opens the same type of mailbox-management menu.

Prompt wording, menu order, available actions, and keypresses can differ according to Asterisk version, language files, and voicemail settings.

Greetings and Mailbox Options

Authenticated mailbox users can use the voicemail menu to record or replace personal greetings when greeting-related features are enabled. A personal greeting is played to callers who reach that mailbox through the VoiceMail message-deposit application.

The greeting a caller hears depends on the active greeting type and call condition, such as unavailable or busy handling. A user may record a new greeting without it becoming active in every situation if the deployment uses separate greeting categories or other voicemail settings. After recording a greeting, place a test call through the message-deposit path to confirm which greeting callers hear.

Available mailbox options also depend on configuration. If a menu item is missing, review the voicemail feature settings rather than assuming the dialplan application is malfunctioning.

Testing and Operational Verification

1. Confirm that the mailbox and its password are defined in the intended voicemail context.
2. Confirm that the feature-code context is reachable from an authorized extension.
3. Dial the shared feature code, such as *99, from that extension.
4. Verify that the application prompts for a mailbox when the dialplan uses VoiceMailMain().
5. Enter a configured mailbox number and its password.
6. Verify that the mailbox menu opens and that existing messages can be retrieved.
7. Record or replace a test greeting if the feature is enabled.
8. Place a test call that reaches the mailbox through VoiceMail and confirm that the expected greeting plays.
9. Test the direct-access route separately if one is configured.
10. Review the Asterisk CLI and relevant logs if dialing, authentication, message retrieval, or greeting recording fails.

After changing dialplan or voicemail configuration, reload it according to your local operational procedure and verify the running configuration. Avoid exposing passwords while collecting logs or demonstrating a test.

Troubleshooting

The feature code does not reach a VoiceMailMain prompt

• Confirm the caller's active channel context.
• Confirm that the feature extension exists in that context.
• Check whether another extension or pattern matches the digits first.
• Verify that the changed dialplan has been reloaded according to local practice.

The mailbox number is rejected or not found

• Verify that the mailbox has been defined.
• Compare the referenced context in VoiceMailMain(mailbox@context) with the voicemail configuration.
• Check whether the mailbox configuration was reloaded after editing.
• Use voicemail show users where supported to inspect configured users.

The password prompt appears, but authentication fails

• Confirm that the user selected the intended mailbox.
• Verify the configured password through a trusted administrative process without exposing it in logs.
• Check whether the mailbox definition contains an unexpected password value.
• Repeat the test from an authorized internal extension.

Direct access opens the wrong account or reports no mailbox

• Check the mailbox argument for typographical errors.
• Use an explicit mailbox@context reference.
• Look for the same mailbox number in multiple voicemail contexts.
• Confirm which voicemail context should serve the calling extension.

The user can log in but cannot hear or record the expected greeting

• Review enabled voicemail features and greeting settings.
• Check recording storage paths and filesystem permissions.
• Inspect Asterisk logs during a greeting recording attempt.
• Place a call through the VoiceMail message-deposit path to test the active greeting.

Key Points

• Use VoiceMailMain() for a shared login number when users should enter their own mailbox numbers.
• Use VoiceMailMain(mailbox@context) when a route targets a known mailbox.
• Ensure mailbox definitions, passwords, and voicemail contexts exist before testing authentication.
• Keep mailbox-management routes internal or otherwise tightly controlled.
• Use the installed Asterisk CLI documentation to verify supported VoiceMailMain options.
• Test both login behavior and the caller-facing greeting path.