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.

12 thoughts on “Setting up shared voicemail on Asterisk – part 1”

  1. I have followed this document’s instructions exactly in a test bed on Freepbx 2.10 asterisk 1.8 and although it is very informative, I believe there is some typos in the bash script. In my case the subscription request has been accepted by Asterisk and the hint is correct when I type “core show hints”. when I call the script directly from the command prompt I get an error;
    “No such command ‘originate Local/s@groupmwi-on extension 4@default”

    I would appreciate it if you could let me know if there has been a update to this article because this is a common task that most customers ask for. Thank you for providing this solution.

    • Hi Dale,
      The article was written for earlier versions of Asterisk/FreePBX. I think this must be a change in version 1.8. I am working what seems like every waking hour at the moment, but will try to investigate this and update the article when I get some time.

      I am sure there are no typos in the article as many people have used these instructions successfully and I am sure others would have posted comments by now if the instructions contained errors. I tested it all on a system here when I wrote the article too, but not v1.8 of Asterisk.
      John

  2. Dear sir, thanks a lot for clearing much things. Now I am stuck with groupmwi script. Can you show the code for multiple extensions i.e. 4444, 4445 or 4446. I don’t know how to change groupscript from one to for multiple extensions.

    • Writing Linux bash scripts is not my favourite weekend pastime either, so I suggest you start here:
      http://linuxconfig.org/Bash_scripting_Tutorial

      Please do your own testing and bug fixing, but the basic structure might look a bit like this:

      #!/bin/sh

      VM_CONTEXT=$1
      EXTEN=$2
      VM_COUNT=$3

      ASTCMD=”/usr/sbin/asterisk -rx”

      if [ $EXTEN -eq 4444 ]; then
      if [[ $VM_COUNT = “0” ]]; then
      $ASTCMD “devstate change Custom:group1mwi NOT_INUSE”
      else
      $ASTCMD “devstate change Custom:group1mwi INUSE”
      fi
      fi

      if [ $EXTEN -eq 4445 ]; then
      if [[ $VM_COUNT = “0” ]]; then
      $ASTCMD “devstate change Custom:group2mwi NOT_INUSE”
      else
      $ASTCMD “devstate change Custom:group2mwi INUSE”
      fi
      fi

      etc.

  3. Again sorry for, my lack of scripting or coding, can you show the complete code with these three dummy extensions.

    • I’m not clear what question you are asking, so I will try to address all possibilities:
      a) 3 extensions can monitor 1 shared voicemail box – that is what the article is describing.
      b) 1 extension could monitor 3 shared voicemail boxes provided the extension has enough programmable keys.
      c) Several extensions could monitor several voicemail boxes
      d) BLF keys can be used to monitor the status of other extensions, but that is not what this article is focussed on. You can use asterisk hints to monitor extensions. For example:
      exten => 4001,hint,SIP/4001
      …that would create a mapping between hint 4001 and the status of SIP extension 4001. You could then set the data field on the BLF key of another phone to 4001 and its lamp would then show you the status of extn 4001.

      • Dear sir, please don’t mind, I am quite new in asterisk. I am concern with this possibility
        b) 1 extension could monitor 3 shared voicemail boxes provided the extension has enough programmable keys.
        what will be the dial plan in the extensions_custom and what will be the script (groupmwi) layout for addressing three extensions. I want to monitor three voicemail box on one ip phone using it’s three blf kyes. Each blf key should indicate the concern voicemail indication.

        • You just need to read the article here, but repeat the steps three times, using a different extension/voicemail/custom-device-state number for each. So create three dummy extensions and you could number them 4444, 4445, 4446. Add three hints and three message retrieval sections to extensions_custom:
          ; Retrieve messages from the group 1 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:group1mwi

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

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

          Then set your three BLF keys to point to 974444, 974445 and 974446

          If you study it, I’m sure you can see the way this works. You will also need to modify the code in the externnotify script so that it switches the correct one of the three custom device states depending which voicemail box number is passed. It will be passed 4444, 4445 or 4446 in the second argument $2.

Comments are closed.