Asterisk course

Using the Asterisk VoiceMailMain Application

Learn how to configure Asterisk VoiceMailMain for mailbox login, voicemail retrieval, greetings, mailbox options, and secure dialplan access.

VoiceMailMain is the Asterisk dialplan application that gives a voicemail subscriber access to stored messages and mailbox-management features. A typical user dials a feature code, enters a mailbox number, authenticates with a mailbox password, and then uses the voicemail menu.

This lesson assumes basic familiarity with Asterisk dialplans, extensions, priorities, contexts, and DTMF input. A dialplan is the call-routing logic that maps dialed numbers and priorities to applications. An extension can be a phone number or a feature code such as *99.

VoiceMailMain versus VoiceMail

The names are similar, but the applications serve different parts of the voicemail process.

After successful login, VoiceMailMain can provide menu options for listening to messages, managing saved or new messages, changing mailbox options, and recording personal greetings. The exact prompts and available choices can vary with the Asterisk version and voicemail configuration.

VoiceMailMain parameters

The application accepts an optional mailbox selection and optional behavior-modifying options. Its commonly used structure is:

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

A mailbox is a voicemail subscriber identity containing messages, greetings, and settings. The mailbox number is the numeric identifier used to select it. A context is a logical grouping used for dialplan routing or voicemail mailbox lookup.

Omitting the mailbox

With an empty argument list, the application uses interactive mailbox selection. This is the normal choice when one feature code should serve many subscribers:

same => n,VoiceMailMain()

The caller is prompted for a mailbox number and then for the password associated with that mailbox.

Supplying a mailbox directly

A dialplan can supply a mailbox when the target is known:

same => n,VoiceMailMain(444@default)

Supplying the mailbox does not automatically make the path safe for public use. Decide explicitly whether the mailbox owner must still enter a password. A direct mailbox path that removes authentication should be limited to a trusted, already-authenticated internal path.

Options and authentication

VoiceMailMain options alter application behavior. In Asterisk versions that support it, the s option skips the normal mailbox passcode check. The exact option set should be confirmed with the documentation for the installed Asterisk version or the CLI application help.

An authentication bypass is appropriate only when another control has already established the caller's identity, such as a tightly restricted internal feature path. It should not be exposed through a public DID, an unrestricted endpoint context, or a shared feature code. For ordinary subscriber access, omit bypass behavior and require the mailbox password.

Interactive mailbox selection and login flow

When the dialplan invokes VoiceMailMain() without a mailbox argument, the default flow is:

1. The caller dials the voicemail access feature code.
2. Asterisk starts VoiceMailMain and asks for a mailbox number.
3. The caller enters the numeric mailbox identifier.
4. Asterisk looks up that mailbox in the configured voicemail context.
5. The caller enters the mailbox password.
6. After successful authentication, Asterisk presents the voicemail-management menu.

The digits entered by the caller must match the mailbox credentials defined in voicemail.conf. For example, entering 444 selects mailbox 444, and entering 2587 is checked against the password configured for that mailbox.

Configuring a shared voicemail access code

The following example creates *99 as a shared feature code. Each user selects a mailbox interactively.

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

NoOp() means “no operation.” It does not provide a user-facing function, but it marks the call flow and can make console logs easier to understand while troubleshooting. It is optional.

The empty parentheses in VoiceMailMain() are important: they tell Asterisk not to select a mailbox in advance, so the caller is prompted for one.

Place this extension in a dialplan context reachable by the intended users. If an endpoint enters a different context, it may not be able to dial *99. Review Asterisk contexts and dialplan extensions when deciding where the feature code belongs.

Defining the required mailbox

A mailbox must already exist before VoiceMailMain can authenticate its owner. Mailboxes and their associated settings are defined in voicemail.conf. See The Voicemail Conf File for mailbox configuration details.

For the demonstration flow, define mailbox 444 with password 2587 in the appropriate voicemail context. Conceptually, the configuration contains:

[default]
444 => 2587,Example User

The exact fields available after the mailbox password depend on the voicemail configuration format and Asterisk version. The important values for this example are:

• Mailbox number: 444
• Mailbox password: 2587
• Voicemail context: the context containing mailbox 444

Use a stronger private password in a real deployment. Do not publish or reuse 2587 outside a demonstration.

When voicemail contexts are used, the context must align with the lookup performed by the dialplan. For a direct invocation such as VoiceMailMain(444@default), the mailbox must be present in the default voicemail context. For prompted access, verify that the application's default lookup context is the one containing the intended mailbox.

Direct mailbox access design

A dedicated dialplan path can pass a known mailbox to VoiceMailMain:

[trusted-phones]
exten => *9444,1,NoOp(Access mailbox 444)
same => n,VoiceMailMain(444@default)

This design can be useful when a phone or internal workflow is associated with one mailbox. The user should normally still enter the mailbox password. Do not add an authentication-bypass option simply because the mailbox number is known. Caller-ID values and dialed feature codes are not, by themselves, reliable proof of identity.

Testing the configuration

1. Confirm that mailbox 444 exists in voicemail.conf and has the expected password.
2. Confirm that the dialplan containing *99 is loaded in the context used by the test endpoint.
3. From an authorized phone, dial *99.
4. When prompted, enter mailbox number 444.
5. Enter password 2587 for this demonstration only.
6. Verify that the voicemail-management menu is reached.
7. Check that stored messages can be heard if messages exist.
8. Navigate to mailbox options and greeting controls.
9. Test the greeting workflow without permanently changing a production greeting unless that is intended.

Also test the two selection modes separately. With VoiceMailMain(), verify that the caller is prompted for a mailbox. With VoiceMailMain(444@default), verify that mailbox 444 is selected directly and that the expected password prompt remains in place.

Troubleshooting

The feature code does not reach VoiceMailMain

• Confirm that *99 exists in the active dialplan context.
• Confirm that the calling endpoint or inbound route enters that context.
• Check that the dialplan configuration was validated and reloaded after editing.
• Use the NoOp() marker and Asterisk console output to determine whether the call reaches the expected priority.

For background on how applications execute through priorities, review Asterisk priorities.

Mailbox 444 is rejected

• Verify that mailbox 444 is defined in voicemail.conf.
• Check that it is in the voicemail context used by VoiceMailMain.
• Confirm that voicemail configuration changes were loaded before retesting.
• Check for typing errors in the mailbox number.

The mailbox is accepted but the password fails

• Verify the password assigned to mailbox 444.
• Repeat the mailbox-number sequence to ensure the correct mailbox was selected.
• Check whether the configuration was changed but not applied.
• Reset the credential through a secure administrative process rather than sharing the password in an unsecured channel.

The user is not prompted for a password

• Inspect the active VoiceMailMain arguments for a behavior-modifying option.
• Check whether a direct mailbox path uses an authentication-bypass option such as s.
• Confirm that the call is not reaching a different dialplan extension.
• Restore normal password verification for shared, public, or otherwise untrusted access paths.

Exam-relevant points

• VoiceMail deposits a caller's message; VoiceMailMain provides subscriber retrieval and administration.
• VoiceMailMain() prompts for the mailbox number.
• A supplied mailbox such as 444@default selects the mailbox in advance.
• The mailbox must exist in voicemail.conf, and the password must match the selected mailbox.
• The feature-code context must be reachable by the intended endpoints or call routes.
• Authentication-bypass behavior must never be exposed to untrusted callers.