An Initial voicemail.conf File

We recommend the following sample as a starting point. You can refer to ~/asterisk-complete/asterisk/11/configs/voicemail.conf.sample for details on the various settings.

Place the following in a file named /etc/asterisk/voicemail.conf:

; Voicemail Configuration

[general]
format=wav49|wav
[email protected]
attach=yes
skipms=3000
maxsilence=10
silencethreshold=128
maxlogins=3
emaildateformat=%A, %B %d, %Y at %r
pagerdateformat=%A, %B %d, %Y at %r
sendvoicemail=yes ; Allow the user to compose and send a voicemail while inside

[zonemessages]
eastern=America/New_York|'vm-received' Q 'digits/at' IMp
central=America/Chicago|'vm-received' Q 'digits/at' IMp
central24=America/Chicago|'vm-received' q 'digits/at' H N 'hours'
military=Zulu|'vm-received' q 'digits/at' H N 'hours' 'phonetic/z_p'
european=Europe/Copenhagen|'vm-received' a d b 'digits/at' HM

You can create a massive and complex voicemail.conf file (and can even store user mailboxes in it), but we’re going to focus on a few curated examples to keep things simple. You’ll likely find that what we present will serve your needs quite well (and that the documentation samples will provide more detail, should you require it).

The [general] Section

The first section of the voicemail.conf file, [general], allows you to define global settings. Many of these settings can be assigned on a per-mailbox setting. We’ve listed in Table 8-1 a few settings that we feel are the most important to consider.

Part of the [general] section is an area of supplementary options (referred to in the config file as advanced options, though there’s not really anything advanced about them). These options (listed in Table 8-2) are defined in the same way as the other options in the [general] section, but what is significant about them is that they can also be defined on a per-mailbox basis, which would override whatever is defined under [general] for that particular setting. In other words, the following options can be set in the database when you create a new mailbox.

The [zonemessages] Section

The next section of the voicemail.conf file is the [zonemessages] section. The purpose of this section is to allow time zone–specific handling of messages, so you can play back to the user messages with the correct timestamps. You can set the name of the zone to whatever you need. Following the zone name, you can define which time zone you want the name to refer to, as well as some options that define how timestamps are played back. You can look at the ~//src/asterisk-16.<TAB>/configs/samples/voicemail.conf.sample file for syntax details. Asterisk includes the examples shown in Table 8-3. Any valid time zone known to the Linux system should be configurable. Just use the Linux name for the zone, and then provide the details of how you want it handled.

Mailboxes

You can configure mailboxes in the voicemail.conf file, but it’s not the recommended way. We’re going to use the database to define your mailboxes.

The first thing we need to do is tell Asterisk that voicemail users are available in the database. We do that by editing the /etc/asterisk/extconfig.conf file:

$ sudo vim /etc/asterisk/extconfig.conf

[settings] ; older mechanism for connecting all other modules to the database
ps_endpoints => odbc,asterisk
ps_auths => odbc,asterisk
ps_aors => odbc,asterisk
ps_domain_aliases => odbc,asterisk
ps_endpoint_id_ips => odbc,asterisk
ps_contacts => odbc,asterisk
voicemail => odbc,asterisk,voicemail

You should restart Asterisk to ensure this change has been applied ($ sudo service asterisk restart).

In the voicemail system, a mailbox must be defined with a context. This does not relate to any dialplan context; it’s a label specific to voicemail that will determine what mailboxes will be grouped together, and is also used to name the folder in the spool that contains the various files associated with this mailbox (greeting, messages, envelopes, and so forth). Normally, you don’t need to worry about this, as all mailboxes will end up in the default context. You really only need to define various contexts if you have a complex, multi-tenanted system, where there’s a potential for extension overlap, or where you don’t want certain groups of users exposed to other groups of users.

The `asterisk`.`voicemail` table offers many options; however, to create a mailbox there are only three fields that are required, plus two more that are recommended. The context, mailbox, and password fields are required, and fullname and email are strongly recommended. Here’s a simple MySQL INSERT that’ll create some mailboxes for you.

INSERT INTO `asterisk`.`voicemail` (context,mailbox,password,fullname,email) 
VALUES 
('default','100','486541','Russell Bryant', '[email protected]'),
('default','101','957642','Leif Madsen', '[email protected]'),
('default','102','656844','Jared Smith', '[email protected]'),
('default','103','375416','Jim VanMeggelen', '[email protected]')
;

The parts of the mailbox definition are:

mailbox

This is the mailbox number. It is normal to ensure it corresponds with the extension number of the associated set.

password

This is the numeric password that the mailbox owner will use to access her voicemail. If the user changes her password, the system will update this field in the database.

If the password is preceded by the hyphen (-) character, the user cannot change their mailbox password.

fullname (FirstName LastName)

This is the name of the mailbox owner. The company directory uses the text in this field to allow callers to spell usernames. You only get one space, which is meant to delimit the first name from the last name, so if your last name is something like Van Meggelen, you’ll put that in as VanMeggelen. Other punctuation characters might also cause problems. (We’re looking at you, O’Reilly.)

email address

This is the email address of the mailbox owner. Asterisk can send the voicemail to the specified email box.

There are quite a few other options you can define for each user. It’s unlikely you’ll use many of them, but Table 8-4 contains a curated list of some that may be of use to you.

The VoiceMail() Dialplan Application

When you want to pass a call to voicemail, you need to provide two arguments: the mailbox (or mailboxes) in which the message should be left, and any options relating to this, such as which greeting to play or whether to mark the message as urgent. The structure of the VoiceMail() command is this:

VoiceMail(mailbox[@context][&mailbox[@context][&...]][,options])

The options you can pass to VoiceMail() that provide a higher level of control are detailed in Table 8-5.

The VoiceMail() application sends the caller to the specified mailbox, so that they can leave a message. The mailbox should be specified as mailbox@context, where context is the name of the voicemail context (not the dialplan context). The option letters b or u can be added to request the type of greeting. If the letter b is used, the caller will hear the mailbox owner’s busy message (if one exists). If the letter u is used, the caller will hear the mailbox owner’s unavailable message (also assuming one exists). If no greeting exists, the system will generate a generic message: The person at extension <mailbox> is unavailable. Please leave a message at the tone.

In the dialplan we built in Chapter 6, we created several extensions. Consider this simple example extension 102, which allows people to call UserB_DeskPhone:

exten => 102,1,Dial(${UserB_DeskPhone},10)
  same => n,Playback(vm-nobodyavail)
  same => n,Hangup()

We faked a voicemail by playing a prompt that didn’t actually do anything. Let’s change that so the call goes to an actual mailbox instead. For now we’ll just let voicemail play a generic greeting that the caller will hear. Remember, the second argument to the Dial() application is a timeout. If the call is not answered before the timeout expires, the call is sent to the next priority. We’ve got a 10-second timeout, and a new priority to send the caller to voicemail after the dial timeout:

exten => 102,1,Dial(${UserB_DeskPhone},10)
  same => n,Voicemail(${EXTEN}@default,u))
  same => n,Hangup()

We can do more if we wish, and change it so that if the user is busy (on another call), the caller will hear a busy message. To do this, we will make use of the ${DIALSTATUS} variable, which contains one of several status values (type core show application Dial at the Asterisk console for a listing of all the possible values):

exten => 102,1,Dial(${UserA_SoftPhone})
  same => n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)

  same => n(unavail),VoiceMail(101@default,u)
  same => n,Hangup()

  same => n(busy),VoiceMail(101@default,b)
  same => n,Hangup()

Now callers will get voicemail (with the appropriate greeting) if the user is either busy or unavailable. An alternative syntax is to use the IF() function to define which of the unavailable or busy messages to use:³

exten => 103,1,Dial(${UserB_SoftPhone})
   same => n,Voicemail(${EXTEN}@default,${IF($["${DIALSTATUS}" = "BUSY"]?b:u)})
   same => n,Hangup()

A slight problem remains, however, in that our users have no way of retrieving their messages, nor setting their greetings or any other voicemail options. We will remedy that in the next section.

The VoiceMailMain() Dialplan Application

Users can retrieve their voicemail messages, change their voicemail options, and record their voicemail greetings using the VoiceMailMain() application. VoiceMailMain() accepts two arguments: the mailbox number (and context if necessary), plus a few options. Both arguments are optional.

The structure of the VoiceMailMain() application looks like this:

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

If you do not pass any arguments to VoiceMailMain(), it will play a prompt asking the caller to provide their mailbox number. The options that can be supplied are listed in Table 8-6.

To allow users to dial an extension to check their voicemail, you could add an extension to the dialplan like this:

exten => *98,1,NoOp(Access voicemail retrieval.)
   same => n,VoiceMailMain()

Any user whose device is assigned to the [sets] context can now dial *98, and they’ll be able to log into their mailbox to listen to messages, record their name, set their greeting, and so forth.

Standard Voicemail Keymap

Figure 8-1 shows the standard keymap configuration for Asterisk Mail. Some options may be enabled or disabled based on the configuration of voicemail.conf (e.g., envelope=no). This can be given to users as a reference.

Figure 8-1. Keymap configuration for Comedian Mail

Creating a Dial-by-Name Directory

One last feature of the Asterisk voicemail system that we should cover is the dial-by-name directory. This is created with the Directory() application. This application uses the names defined in the mailboxes in voicemail.conf to present the caller with a dial-by-name directory of users.

Directory() takes up to three arguments: the voicemail context from which to read the names, the optional dialplan context in which to dial the user, and an option string (which is also optional). By default, Directory() searches for the user by last name, but passing the f option forces it to search by first name instead. Let’s add two dial-by-name directories to the TestMenu context of our sample dialplan, so that callers can search by either first or last name:

exten => 4,1,Dial(${UserB_SoftPhone},10)
   same => n,Playback(vm-nobodyavail)
   same => n,Hangup()

exten => 8,1,Directory(default,sets,f)
exten => 9,1,Directory(default,sets)

exten => i,1,Playback(pbx-invalid)
   same => n,Goto(TestMenu,start,1)

If you call 201, and then press 8, you’ll get a directory by first name. If you dial 9, you’ll get the directory by last name.

Linux Filesystem

By default, Asterisk stores voice messages in the spool, at /var/spool/asterisk/voicemail/<voicemailcontext>/<mailbox>. The messages can be stored in multiple formats (such as wav and wav49), depending on what you specified as the format in the [general] section of your voicemail.conf file. Your greetings are also stored in this folder.

Figure 8-2 shows an example of what might be in a mailbox folder. This mailbox has no new messages in the INBOX, has two saved messages in the Old folder, and has busy, unavailable and name (greet) greetings recorded.

Figure 8-2. Sample mailbox folder

IMAP

Some organizations prefer to manage voicemail as part of their email system. This has been called unified messaging by the telecom industry, and its implementation has traditionally been expensive and complex. Asterisk allows for a fairly simple integration between voicemail and email, either through its built-in voicemail-to-email handler, or through a relationship with an IMAP server. We don’t recommend IMAP integration simply because it’s a lot of work for very little gain, and it is out of scope for this book.

Message Storage in a Database

It is possible to configure Asterisk voicemail to store messages as blobs within a database. This was originally seen as a simple way to allow synchronization of messages between systems. We’ve never been fans of the idea, since databases are not designed for bulk storage of binary data, and there are many other ways to synchronize files across systems.