Voicemail IMAP Integration
Voicemail IMAP Integration
“Unified messaging” has been a buzzword in the telecommunications industry for ages. It’s all about integrating services so users can access the same types of data in multiple locations, using different methods. One of the most touted applications is the integration of email and voicemail. Asterisk has been doing this for years, but many larger companies are still trying to get this right. Asterisk has the ability to send users voice‐mails via email, using the Mail Transport Agent (MTA) in your Linux distro (this always
used to be sendmail, but Postfix has become increasingly popular as an MTA). Voicemail to email is one of the oldest features in Asterisk, and it normally works without any configuration at all.
Internet Message Access Protocol (IMAP) integration has existed in Asterisk (and been steadily evolving) since version 1.4. IMAP voicemail integration means your users can access their voicemails via a folder within their email accounts, which gives them the ability to listen to, forward, and mark voicemail messages with the same flexibility that the Asterisk VoiceMail() dialplan application gives. Asterisk will be aware of the statuses of those messages when the users next log in via the phone system.
As the number of administrators integrating Asterisk with their IMAP servers has increased, the number of bugs filed and fixed has first increased and then decreased, to the point where IMAP integration can be considered stable enough for production use. In this section we’ll discuss how to compile in IMAP voicemail support and connect your voicemail system to your IMAP server.
Compiling IMAP Voicemail Support into Asterisk
To get IMAP voicemail support into Asterisk, we need to compile the University of Washington’s IMAP library. The UW IMAP toolkit will give us the functionality in Asterisk to connect to our IMAP server. Before compiling the software, though, we need to install some dependencies.
The dependencies for building the IMAP library include the tools required to build Asterisk, but the way we’re building it also requires the development libraries for OpenSSL and Pluggable Authentication Modules (PAM). We’ve included instructions for both RHEL and Ubuntu.
RHEL dependencies
Installing both the OpenSSL and PAM development libraries on RHEL can be done with the following command:
$ sudo yum install openssl-devel pam-devel
Ubuntu dependencies
Installing both the OpenSSL and PAM development libraries on Ubuntu can be done with the following command:
$ sudo apt-get install libssl-dev libpam0g-dev
Compiling the IMAP library
Now that we have our dependencies satisfied, we can compile the IMAP library that Asterisk will use to connect to our IMAP server.
The first thing to do is change to the thirdparty directory located under the asterisk-complete directory. If you have not already created this directory, do so now:
$ cd ~/src/asterisk-complete
$ mkdir thirdparty
$ cd thirdparty
Next up is downloading the IMAP toolkit and compiling it. The next steps will get the latest version of the IMAP toolkit from the University of Washington’s server (more information about the toolkit is available at http://www.washington.edu/imap/):
$ wget ftp://ftp.cac.washington.edu/mail/imap.tar.Z
$ tar zxvf imap.tar.Z
$ cd imap-2007e
There are a few options we need to pass to the make command when building the IMAP library, and the values you should pass will depend on what platform you’re building on (32-bit versus 64-bit), if you need OpenSSL support, and whether you need IPv6support or just IPv4.
Table -1. IMAP library compile time options
If you look in the Makefile shipped with the IMAP library, you will find a list of platforms for which the library can be compiled. In our case, we’ll be compiling for either RHEL or Ubuntu with PAM support. If you’re compiling on other systems, take a look in the Makefile for the three-letter code that tells the library how to compile for your platform.
To compile for a 64-bit platform with OpenSSL support and a preference for connecting via IPv4:
$ make lnp EXTRACFLAGS=”-fPIC -I/usr/include/openssl” IP6=4
To compile for a 32-bit platform with OpenSSL support and a preference for connecting via IPv4:
$ make lnp EXTRACFLAGS=”-I/usr/include/openssl” IP6=4
If you don’t wish to compile with OpenSSL support, simply remove the -I/usr/include/openssl from the EXTRACFLAGS option. If you would prefer connecting by IPv6 by default, simply don’t specify the IP6=4 option.
Compiling Asterisk
After compiling the IMAP library, we need to recompile the app_voicemail.so module with IMAP support. The first step is to run the configure script and pass it the –with-imap option to tell it where the IMAP library exists:
$ cd ~/src/asterisk-complete/asterisk/11
$ ./configure –with-imap=~/src/asterisk-complete/thirdparty/imap-2007e/
Once the configure script has finished executing, we need to enable IMAP voicemail support in menuselect:
$ make menuselect
From the menuselect interface, go to Voicemail Build Options. Within that menu, you should have the option to select IMAP_STORAGE .
After selecting IMAP_STORAGE , save and exit from menuselect and run make install, which will recompile the app_voicemail.so module and install it to the appropriate location. The next step is to configure the voicemail.conf file located in /etc/asterisk.
Configuring Asterisk
Now that we’ve compiled IMAP support into Asterisk, we need to enable it by connecting to an IMAP-enabled server. There are many IMAP servers we could use, including those supplied with Microsoft servers, Dovecot, and Cyrus on Unix, or a web-based IMAP server such as the one supplied by Google’s Gmail. 5 Our instructions will show how to connect Asterisk to a Gmail account with IMAP enabled, as it requires the least amount of effort to get up and running with IMAP voicemail, but these instructions can easily be adapted for use with any existing IMAP server.
Enabling IMAP on Gmail. Enabling IMAP support on your Gmail account is straightfor‐ward. Once logged into your account, select Settings from the upper-right corner. Then select Forwarding and POP/IMAP from the menu bar under the Settings header. In the IMAP Access section, select Enable IMAP. After enabling IMAP, click the Save Changes button at the bottom of the screen.
Figure -2. Enabling Gmail IMAP
Configuring voicemail.conf for IMAP. To enable our voicemail system to connect to an IMAP system, we need to make sure IMAP support has been built into the app_voice mail.so module per the instructions in “Compiling Asterisk”. With IMAP
support compiled into Asterisk, we just need to instruct the voicemail module how to
connect to our IMAP server.
We’re going to demonstrate how to connect to an IMAP-enabled Gmail account and use that to store and retrieve our voicemail messages. If you haven’t already, read the section “Enabling IMAP on Gmail” before proceeding. The final step is configuring voicemail.conf to connect to the server.
In voicemail.conf, add the following lines to the [general] section. Be sure you only specify a single format (we recommend wav49 ) for voicemail recordings, and remove any references to ODBC voicemail storage if you’ve enabled that previously:
[general]
format=wav49 : format to store files
imapserver=imap.gmail.com : IMAP server location
imapport=993 : port IMAP server listens to
imapflags=ssl : flags required for connecting
expungeonhangup=yes : delete messages on hangup
pollmailboxes=yes : used for message waiting indication
pollfreq=30 : how often to check for message changes
Before we configure our user for connecting to the Gmail IMAP server, let’s discuss the options we’ve just set in the [general] section. These are the basic options that will get us started; we’ll do some more customization shortly, but let’s see what we’ve done
so far.
First, the format=wav49 option has declared that we’re going to save our files as GSM with a WAV header, which can be played on most desktops (including Microsoft Windows) while retaining a small file size.
Next, we’ve configured Asterisk to connect to an imapserver located at imap.gmail.com on imapport 993 . We’ve also set imapflags to ssl , as Gmail requires a secure connection. Without the ssl IMAP flag being set, the server will reject our connection attempts (which is why it was important that we compiled our IMAP library with OpenSSL support). Another option that may be required on private IMAP servers such as Dovecot is to specify novalidate-cert for imapflags when an SSL connection is necessary, but the certificate is not generated by a certificate authority. Next, we’ve set expungeonhangup=yes , which causes messages marked for deletion to be removed from the server upon hangup from the VoiceMail() application. Without this option, messages are simply marked as read and left on the server until they have been removed via an email application or web interface.
In order to get message waiting indication (MWI) updates correctly, we need to enable pollmailboxes=yes , which causes Asterisk to check with the server for any changes to the status of a message. For example, when someone leaves us a voicemail and we listen to it by opening the message via our email application, the message will be marked as read, but without polling the mailbox Asterisk will have no way of knowing this and will enable the MWI light on the associated device indefinitely. Finally, we’ve set the related option pollfreq to 30 seconds. This option controls how often Asterisk will ask the server for the status of messages: set it appropriately to control the amount of traffic going to the voicemail server.
Table -3. Additional IMAP voicemail options
With our [general] section configured, let’s define a mailbox for connecting to the IMAP server.
we defined some users in the [shifteight] voicemail context. Here is the original configuration as defined:
[shifteight]
100 => 0107,Leif Madsen,leif@shifteight.org
101 => 0523,Jim VanMeggelen,jim@shifteight.org,,attach=no|maxmsg=100
102 => 11042,Tilghman Lesher,,,attach=no|tz=central
We’re going to modify mailbox 100 in such a way that it connects to the Gmail IMAP server to store and retrieve voicemail messages:
[shifteight]
100 => 0107,Leif Madsen,,,|imapuser=leif@shifteight.org|imappassword=secret
We’ve removed the email address from the third field because we’re not going to use sendmail to email us voicemails anymore: they are just going to be stored on the email server directly now. We’ve configured the mailbox to connect with the IMAP username leif@shifteight.org (because we’ve enabled Google Apps for the domain that hosts our email) and are connecting using the IMAP password secret .
After configuring Asterisk, we need to reload the app_voicemail.so module. If you enable console debugging, you should see output similar to the following upon connection to the voicemail server:
*CLI> core set debug 10
*CLI> module reload app_voicemail.so
DEBUG[3293]: app_voicemail.c:2734 mm_log: IMAP Info:
Trying IP address [74.125.53.109]
DEBUG[3293]: app_voicemail.c:2734 mm_log: IMAP Info: Gimap ready for requests
from 99.228.XXX.XXX 13if2973206wfc.0
DEBUG[3293]: app_voicemail.c:2757 mm_login: Entering callback mm_login
DEBUG[3293]: app_voicemail.c:2650 mm_exists:
Entering EXISTS callback for message 7
DEBUG[3293]: app_voicemail.c:3074 set_update:
User leif@shifteight.org mailbox set for update.
DEBUG[3293]: app_voicemail.c:2510 init_mailstream: Before mail_open, server:
{imap.gmail.com:993/imap/ssl/user=leif@shifteight.org}INBOX, box:0
DEBUG[3293]: app_voicemail.c:2734 mm_log: IMAP Info: Reusing connection to
gmail-imap.l.google.com/user=”leif@shifteight.org”
If you get any ERROR s, check your configuration and verify that the IMAP library is compiled with SSL support. Once app_voicemail.so is connected, try leaving yourself a voicemail; then check your voicemail via the Gmail web interface and verify that your message is stored correctly. You should also have an MWI light on your device if it supports it, and if you’ve configured mailbox=100@shifteight for the device in sip.conf. If you load the voicemail message envelope and mark it as read, the MWI light should turn off within 30 seconds (or whatever value you set pollfreq to in voice mail.conf).
