Setting up shared voicemail on Asterisk – part 1

It’s a requirement that people often seem to ask for – a single voicemail box, taking messages for a department, that can be easily monitored and accessed by several different users. A typical application would be to record out-of-hours messages which are then checked in the morning by any of a number of users, perhaps just depending who arrives first at the office.

While it is fairly easy to configure Asterisk or Trixbox to record the messages, it is less clear how to configure an indicator lamp to show messages are waiting on several IP extension phones. Oh yes, and of course we will want the programmable key to also work as a single-press access for retrieving messages from the voicemail box.

In part 1 of this 2-part article I describe how to create a shared mailbox, send your out-of-hours calls to it, configure a custom device state to control a programmable key’s lamp on an arbitrary number of IP phones and insert code into the dialplan to allow the BLF key to talk to Asterisk. In part 2, I explain how to switch the status of that custom device state to reflect whether there are any messages in a specific voicemail box.

Creating the shared voicemail box

In Trixbox or FreePBX

Just add a new dummy extension and make sure the Voicemail status is enabled. If you select “Generic SIP Device” when creating the extension, then be sure to assign an unused extension number to it and – very important – an obscure, unguessable string for the SIP password (shown as “secret” in the “Device Options” section). For example, use 8 randomly chosen characters and digits for “secret”. No one will ever need to use the SIP password, but if you use a weak one like 123 then it may render your Asterisk system vulnerable to hacking.

The voicemail password is different – it is located in the “Voicemail & Directory” section and should be set to something that all your users can remember while not being so obvious that anyone could guess it. For the examples shown here, I created a SIP extension 4444, set the Display Name to “Dept Voicemail” and in the Device Options section I kept the default setting for mailbox as “4444@default”. The voicemail password was set to 1471. Email notification is optional and is activated simply by inserting an address in “Email Address”.

In raw Asterisk

Edit the file /etc/asterisk/voicemail.conf and scroll down until you see the [default] section. In this section, add a definition for your departmental mailbox. The format for adding new voicemail boxes (as explained in the comments in the sample file) is as follows:

<mailbox>=<password>,<name>,<email>,<pager_email>,<options>

My examples use the following voicemail box definition (the email address and attach option are optional and control delivery of message alerts by email):

4444 => 1471,Dept Voicemail,group@mymaildomain.com,,attach=yes

Sending out-of-hours callers to the shared voicemail box

In Trixbox or FreePBX, it is simply a case of setting the destination for your inbound calls to Voicemail: <4444> Dept Voicemail. If you want to use a timer to send your inbound calls to this shared voicemail box, then take a look at the modules called Time Groups and Time Conditions. Time Groups defines the hours, days, etc and Time Conditions controls the routing of calls to different destinations at times defined in the selected Time Group.

If you are using raw Asterisk, you will need to edit the file /etc/asterisk/extensions.conf and find the appropriate context where inbound calls are handled. To send a call to the shared voicemail box, add a line like this:

exten => _X.,n,Voicemail(4444,u)

The option u, shown above, tells Asterisk to play the “unavailable announcement” to the caller, followed by instructions. For the complete list of announcement options go to
http://www.voip-info.org/wiki/view/Asterisk+cmd+VoiceMail

If you want to use timers to only route the call to this voicemail at certain times of day then check for details at http://www.voip-info.org/wiki/view/Asterisk+cmd+GotoIfTime

About custom device states

If you have not already done so, I now recommend that you read my earlier article about Asterisk’s custom device states. In it, I explain how you can check if your version of Asterisk supports custom device states and I also explain how a device state can be set from the dial plan and how it can be linked to a programmable BLF key using Asterisk hints. Click here to go to that article.

Setting up a custom device state and linking it to a hint

We are going to use a custom device state called groupmwi to show when there are messages waiting in the shared mailbox 4444. The phone’s BLF key tells Asterisk that it is interested in the state of a device by sending a subscribe request – Asterisk knows which device it is interested in because the BLF key also sends an ID string, usually numeric, to specify what it wants to subscribe to. Asterisk hints map these ID strings to objects that it knows about.

To proceed, we must first choose the ID string that will be mapped to our custom device state, groupmwi. The shared mailbox in my examples is 4444. The default feature code to access a voicemail box is *97. The ID string actually does two jobs – it links the BLF lamp to the custom device state, but it is also used to retrieve messages from the box when the BLF key is pressed. I therefore chose to set the ID string to 974444. So my hint looks like this:

exten => 974444,hint,Custom:groupmwi

As well as defining the hint, I will also include dialplan entries that allow access to the stored messages when the BLF key is pressed, because they go in the same section as the hint. So the code we need to add looks like this:

; Retrieve messages from the group message box by dialling 974444
exten => 974444,1,Answer
exten => 974444,2,VoicemailMain(4444@default)
; Add hint to link to the Custom Device State
exten => 974444,hint,Custom:groupmwi

Ok so far? – I hope. But where does this code need to be added? The answer depends if you are using Trixbox/FreePBX or raw asterisk:

For FreePBX based systems, you must edit the file /etc/asterisk/extensions_custom.conf and add the lines to the end of the file in a new context section called [ext-local-custom]:

For raw Asterisk, edit the file /etc/asterisk/extensions.conf and add the lines to the end of the default context (or whichever context you use for calls from extensions):

Setting up the BLF programmable key on the IP phone

On your IP phone, configure one of the programmable keys to be of type BLF and set the number (or value) field to 974444. This is all explained in more detail in the companion article mentioned earlier.

Changing the Custom Device State when voicemail arrives

All that remains now is to make the custom device state change to INUSE when there are messages waiting and NOT_INUSE when there are no messages. This is achieved by:

1. Configuring the Asterisk voicemail option externnotify to call a bash script whenever the number of messages changes in a voicemail box
2. Writing that bash script – its job is to check the input parameters sent from Asterisk and run an appropriate portion of dialplan code
3. Writing two special context sections in the dialplan which change the custom device state to INUSE or NOT_INUSE. These are used by the bash script.

Details are available in part 2.