The ability to store voice messages in the same location as regular email is something that the telecom industry has been promising for a long time. They called it Unified Messaging, and while most PBXes now offer some sort of unified messaging, it is typically very expensive to license and implement.

Naturally, Asterisk cuts through all the silliness and just allows you to have your voicemailbox integrated into an IMAP environment. There are several advantages to storing your voicemail on an IMAP server. When you listen to a voicemail on your phone, the message is set to the read state on the IMAP server. This means that your email client will also note that it has been read. By the same token, if you listen to the message from your email client, the voicemail will turn off the message notification light on any phones that are assigned to that mailbox. Deleting a message from one place will cause it to be deleted from every place. So once deleted, the message is truly gone. This is Unified Messaging, the holy grail of voicemail to email integration, but Asterisk humbly decides not to make a big deal of it.

IMAP integration is still new functionality, so there are a few things that need to be added in order to get it to function. First off, Asterisk needs to have an IMAP client installed so that it can communicate with the IMAP server. Pretty much any IMAP server works (even Exchange Server), and the authors have personally tested IMAP voicemail support with both the Courier-IMAP and Dovecot IMAP servers. The IMAP server may be on the same physical machine as the Asterisk installation, or it may be on the other side of the globe. To be able to access the IMAP server, Asterisk requires an IMAP client library. This library is the University of Washington’s free IMAP client, named c-client. To install the c-client you simply need to navigate to your /usr/src directory and run the following commands:

# wget ftp://ftp.cac.washington.edu/mail/imap.tar.Z

This downloads the source code. Extract it with:

# tar zxvf imap.tar.Z

Navigate into the resulting folder and run:

# make lrh IP6=4

This will compile everything Asterisk needs to make use of the IMAP client libraries.^[150]

Now we have to recompile Asterisk with the IMAP capabilities. We’ll need to navigate to the location of our Asterisk source files (such as /usr/src/asterisk), and run the following command:

# /configure --with-imap=/usr/src/imap-2006h

The we need to rerun make menuconfig to incorporate IMAP storage into the compile. Under Voicemail Build Options select the IMAP_STORAGE parameter, and then press x to save and exit. This ensures that when we compile Asterisk, it will build the IMAP module as well. Obviously, the next step then is to recompile and reinstall Asterisk. A simple way to do this is, in your terminal, to run:

# make && make install

OK, so we’ve got the module compiled and installed. Now it’s time to configure it.

In the /etc/asterisk folder, we’ll need to add a few lines to the voicemail.conf file, in the [general] section:

imapserver=localhost
imapport=143
expungeonhangup=yes
authuser=vmail
authpassword=vmailsecret
imapfolder=Voicemail

Since Dovecot is available in the CentOS package repository, installing a small IMAP server to handle your virtual (voicemail) users on your Asterisk box is simple:

# yum install dovecot

Now make sure that IMAP support is enabled in /etc/dovecot.conf by uncommenting the protocols line so that it appears as follows:

protocols = imap imaps

After you’ve enabled IMAP support, create the user account that will be storing the mail:

# groupadd vmail
# useradd vmail -g vmail -s /bin/true -c "asterisk voicemail user" -p vmailsecret 
  -d /var/spool/asterisk/imap-voicemail vmail
# chown -R vmail.vmail /var/spool/asterisk/imap-voicemail

Now restart Dovecot and Asterisk, and you should be good to go.

# service dovecot restart
# service asterisk restart

Congratulations! You’ve successfully installed basic IMAP voicemail support with Asterisk! This is just the tip of the iceberg, though. With IMAP voicemail storage, it is easy to implement shared (e.g., departmental) voicemail using shared IMAP folders. Many companies already have departmental email, so having a shared voicemail box is a very natural and logical progression of the technology. With IMAP voicemail storage, each employee can manage several voicemail boxes without becoming confused as to whether a particular voicemail message is for them personally or for a department to which they belong. There is nothing unusual to configure from Asterisk’s point of view; you simply call the VoiceMail() application with the desired mailbox and context, and make sure that the department employees have the shared IMAP folder included in their email client’s folder list.

Finally, you may want to use per-mailbox authorization (i.e., each voicemail box authenticates as a specific user) instead of a global Asterisk IMAP user. Asterisk supports this through the imapuser and imappassword options in the individual voicemail box definition entries:

[imapvoicemail]
100 => 1234,Sue's Mailbox,,,imapuser=sue@example.tld|imapsecret=suesimapsecret
101 => 5555,Bob's Mailbox,,,imapuser=bob@example.tld|imapsecret=bobsimapsecret

In this particular example, if a message is left in IMAP mailbox 100 in the imapvoicemail context, Asterisk will authenticate to the IMAP server as sue@example.tld, using suesimapsecret as the password. Similarly, bob@example.tld/bobsimapsecret will be used to authenticate if a message is left in mailbox 101 of the same voicemail context.

In case you missed it, you can also store voicemail in a database via the ODBC connector. See Chapter 12, Relational Database Integration for details!