Voicemail -I(Asterisk)
Voicemail
Before email and instant messaging became ubiquitous, voicemail was a popular method of electronic messaging. Even though most people prefer text-based messaging systems, voicemail remains an essential component of any PBX.
Comedian Mail
One of the most popular (or, arguably, unpopular) features of any modern telephone system is voicemail. Asterisk has a reasonably flexible voicemail system named Comedian Mail. Voicemail in Asterisk is provided in the dialplan by the app_voicemail.so module.
Some of the features of Asterisk’s voicemail system include:
• Unlimited password-protected voicemail boxes, each containing mailbox folders for organizing voicemail
• Different greetings for busy and unavailable states
• Default and custom greetings
• The ability to associate phones with more than one mailbox and mailboxes with more than one phone
• Email notification of voicemail, with the voicemail optionally attached as a sound file 2
• Voicemail forwarding and broadcasts
• Message-waiting indicator (flashing light or stuttered dialtone) on many types of phones
• Company directory of employees, based on voicemail boxes
The default version of the /etc/asterisk/voicemail.conf configuration file requires a few tweaks in order to provide a configuration that will be suitable to most situations.
We’ll begin by going through the various options you can define in voicemail.conf, and then we’ll provide a sample configuration file with the settings we recommend for most deployments.
The voicemail.conf file contains several sections where parameters can be defined. The following sections detail all the options that are available.
The [general] Section
The first section, [general] , allows you to define global settings for your voicemail system. The available options are listed in Table.
Table [general] section options for voicemail.conf
a The separator that is used for each format option must be the pipe ( | ) character.
b Sending email from Asterisk can require some careful configuration, because many spam filters will find Asterisk messages
suspicious and will simply ignore them. We talk more about how to set email for Asterisk
c Yes, you read that correctly: megabytes.
d The Analog Display Services Interface is a standard that allows for more complex feature interactions through the use of the phone
display and menus. With the advent of VoIP telephones, ADSI’s popularity has decreased in recent years.
Part of the [general] section is an area that is referred to as advanced options. These options(listes in table) are defined in the same way as the other options in the [general] section, but they can also be defined on a per-mailbox basis, which would override whatever is defined under [general] for that particular setting.
Table Advanced options for voicemail.conf
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-complete/asterisk/11/config/voicemail.conf.sample file for syntax details. Asterisk includes the examples shown in Table
Table [zonemessages] section options for voicemail.conf
The Contexts Section
All the remaining sections in the voicemail.conf file will be the voicemail contexts, which allow you to segregate groups of mailboxes.
In many cases, you will only need one voicemail context, commonly named [default] . This is worth noting, as it will make things simpler in the dialplan: all the voicemail-related applications assume the context default if no context is specified. In other words, if you don’t require separation of your voicemail users, use default as your one and only voicemail context.
The format for the mailboxes is as follows (you should enter all of this on a single line):
mailbox => password[,FirstName LastName[,email addr[,pager addr
[,options[|options]]]]]
The parts of the mailbox definition are:
-mailbox-
This is the mailbox number. It usually corresponds with the extension number of
the associated set.
-password-
This is the numeric password that the mailbox owner will use to access her voice‐mail. If the user changes her password, the system will update this field in the voicemail.conf file. If the password is preceded by the hyphen (-) character, the user cannot change
their mailbox password.
If you are storing passwords in the spool (by use of the passwordlocation parameter), this field is ignored. However, the parser still requires there to be a field here, so if you are going to specify any other options for this mailbox, a comma will be needed as a placeholder for the password field.
-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.
-email address-
This is the email address of the mailbox owner. Asterisk can send voicemail notifications (including the voicemail message itself, as an attachment) to the specified email box.
-pager address-
This is the email address of the mailbox owner’s pager or cell phone. Asterisk can send a short voicemail notification message to the specified email address.
-options-
This field is a list of options for setting the mailbox owner’s time zone and overriding the global voicemail settings. There are quite a few valid options:
tz , locale , attach , attachfmt , saycid , cidinternalcontexts , sayduration , say durationm , dialout , sendvoicemail , searchcontexts , callback , exitcontext , review , operator , envelope , delete , volgain , nextaftercmd , forcename , force greeting , hidefromdir , tempgreetwarn , passwordlocation , messagewrap , min password .
The tz option sets the user’s time zone to a time zone previously defined in the [zonemessages] section of voicemail.conf. The other options override the global voicemail settings with the same names.
Table Mailbox options
The mailboxes you define in your voicemail.conf file might look like the following
[default]
100 => 5542,Mike Loukides,mike@shifteight.org
101 => 67674,Tim OReilly,tim@shifteight.org
102 => 36217,Mary JonesSmith,mary.jones-smith@shifteight.org
; *** This needs to all be on the same line
103 => 5426,Some Guy,,,dialout=fromvm|callback=fromvm
|review=yes|operator=yes|envelope=yesexamples:
[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
The contexts in voicemail.conf are an excellent and powerful concept, but you will likely find that the default context will be all that you need in normal use. The primary reason for multiple mailbox contexts is when your system is hosting more than one PBX and you need mailbox separation.
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:
; Voicemail Configuration
[general]
format=wav49|wav
serveremail=voicemail@shifteight.org
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
[shifteight.org]
100 => 1234,Leif Madsen,leif@shifteight.org
101 => 1234,Jim Van Meggelen,jim@shifteight.org
102 => 1234,Russell Bryant,russell@shifteight.org
103 => 1234,Jared Smith,jared@shifteight.org
Dialplan Integration
There are two primary dialplan applications that are provided by the app_voice mail.so module in Asterisk. The first, simply named VoiceMail() , does exactly what you would expect it to, which is to record a message in a mailbox. The second one, VoiceMailMain() , allows a caller to log into a mailbox to retrieve messages.
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() to provide a higher level of control are detailed in Table.
Table VoiceMail() optional arguments
The VoiceMail() application sends the caller to the specified mailbox, so that he can leave a message. The mailbox should be specified as mailbox@context , where con text is the name of the voicemail 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 the letter u is used, the caller will hear the mailbox owner’s unavailable message (if one exists).
Consider this simple example extension 101, which allows people to call John:
exten => 101,1,NoOp()
same => n,Dial(${JOHN})
Let’s add an unavailable message that the caller will be played if John doesn’t answer the phone. 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. Let’s add a 10-second timeout, and a priority to send the caller to voicemail if John doesn’t answer in time:
exten => 101,1,NoOp()
same => n,Dial(${JOHN},10)
same => n,VoiceMail(101@default,u)
Now, let’s change it so that if John is busy (on another call), the caller will be sent to his voicemail, where he will hear John’s 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 => 101,1,NoOp()
same => n,Dial(${JOHN},10)
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 John’s voicemail (with the appropriate greeting) if John 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 => 101,1,NoOp()
same => n,Dial(${JOHN},10)
same => n,Voicemail(101@default,${IF($[“${DIALSTATUS}” = “BUSY”]?b:u)})
same => n,Hangup()
A slight problem remains, however, in that John has no way of retrieving his messages. 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 optionally the context) to be accessed, and some 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 her mailbox number. The options that can be supplied are listed in Table.
Table VoiceMailMain() optional arguments
To allow users to dial an extension to check their voicemail, you could add an extension to the dialplan like this:
[Services]
exten => *98,1,NoOp(Access voicemail retrieval.)
same => n,VoiceMailMain()
You would then simply need to add an include in the [LocalSets] context so that you could dial *98:
[LocalSets]
; existing dialplan above here
include => Services
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 incoming context of our sample dialplan, so that callers can search by either first or last name:
exten => 8,1,Directory(default,incoming,f)
exten => 9,1,Directory(default,incoming)
If callers press 8 , they’ll get a directory by first name. If they dial 9 , they’ll get the directory by last name.
Using a Jitterbuffer
When using Asterisk as a voicemail server, you may want to add a jitterbuffer in between voicemail and the caller. The purpose of a jitterbuffer is to help deal with the fact that when a call traverses an IP network, the traffic may not arrive with perfect timing and
in perfect order. If packets occasionally arrive with a bit of delay (jitter) or if they arrive out of order, a jitterbuffer can fix it so that the voicemail system receives the voice stream on time and in order. If the jitterbuffer detects that a packet was lost (or may arrive so
late that it will no longer matter), it can perform packet-loss concealment. That is, it will attempt to make up a frame of audio to put in place of the lost audio to make it harder to hear that audio was lost.
In Asterisk, jitterbuffer support can be enabled on a bridge between two channels in two ways. In the case of voicemail, there is generally only a single channel connected to one of the voicemail applications. The old method (which is required in versions prior
to Asterisk 10) is to enable the use of a jitterbuffer in front of voicemail by creating a bridge between two channels using a Local channel and specifying the j option.
Specifying the n option for the Local channel additionally ensures that the Local channel is not optimized out of the call path in Asterisk:
[Services]
; old method — only required in versions prior to Asterisk 10
exten => *98,1,Dial(Local/vmm@Services/nj)
exten => vmm,1,VoiceMailMain()
As of Asterisk 10, there exists a new JITTERBUFFER() dialplan function which, from the user’s perspective, performs the same functionality. Simply by setting values in the dialplan, we can enable a jitterbuffer prior to accessing a dialplan application such as
Voicemail() :
[Services]
; new method — available in Asterisk 10 and later
exten => *98,1,NoOp()
same => n,Set(JITTERBUFFER(fixed)=default)
same => n,VoiceMailMain()
There exists both a fixed and an adaptive jitterbuffer, along with several different set‐ tings. We’ve used the fixed jitterbuffer with the default settings, which are as follows. See core show function JITTERBUFFER for more configuration options:
• 200 ms buffer length
• If more than 1,000 ms of timestamp difference exists, the jitterbuffer will resync.
