One of the most popular (or, arguably, unpopular) features of any modern telephone system is voicemail. Naturally, Asterisk has a reasonably flexible voicemail system. 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[83]
Voicemail forwarding and broadcasts
Message-waiting indicator (flashing light or stuttered dial tone) on many types of phones
Company directory of employees, based on voicemail boxes
And that’s just the tip of the iceberg! In this section, we’ll introduce you to the fundamentals of a typical voicemail setup.
The voicemail configuration is defined in the configuration file called voicemail.conf. This file contains an assortment of settings that you can use to customize the voicemail system to your needs. Covering all of the available options in voicemail.conf would be beyond the scope of this chapter, but the sample configuration file is well documented and quite easy to follow. For now, look near the bottom of the file, where voicemail contexts and voicemail boxes are defined.
Just as dialplan contexts keep different parts of your dialplan
separate, voicemail contexts allow you to define different sets of
mailboxes that are separate from one another. This allows you to host
voicemail for several different companies or offices on the same server.
Voicemail contexts are defined in the same way as dialplan contexts, with
square brackets surrounding the name of the context. For our examples,
we’ll be using the [default] voicemail
context.
Inside each voicemail context, we define different mailboxes. The syntax for defining a mailbox is:
mailbox=>password,name[,pager_email[,options]]]
Let’s explain what each part of the mailbox definition does:
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 voicemail. If the user changes her password, the system will update this field in the voicemail.conf file.
name
This is the name of the mailbox owner. The company directory uses the text in this field to allow callers to spell usernames.
email
This is the email address of the mailbox owner. Asterisk can send voicemail notifications (including the voicemail message itself) to the specified email box.
pager_email
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 that sets the mailbox
owner’s time zone and overrides the global voicemail settings.
There are nine valid options: attach,
serveremail, tz, saycid, review, operator, callback, dialout, and exitcontext. These options should be in
option = value
pairs, separated by the pipe character (|). The tz option sets the user’s time zone to a time zone previously
defined in the [zonemessages] section of
voicemail.conf, and the other eight options
override the global voicemail settings with the same names.
A typical mailbox definition might look something like this:
101 => 1234,Joe Public,jpublic@somedomain.com,jpublic@pagergateway.net, tz=central|attach=yes
Continuing with our dialplan from the last chapter, let’s set up
voicemail boxes for John and Jane. We’ll give John a password of
1234 and Jane a password of 4444 (remember, these go in
voicemail.conf, not in
extensions.conf):
[default] 101 => 1234,John Doe,john@asteriskdocs.org,jdoe@pagergateway.tld 102 => 4444,Jane Doe,jane@asteriskdocs.org,jane@pagergateway.tld
Now that we’ve created mailboxes for Jane and John, let’s allow callers
to leave messages for them if they don’t answer the phone. To do this,
we’ll use the VoiceMail()
application.
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
context 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).
Let’s use this in our sample dialplan. Previously, we had a line
like this in our [internal]
context, which allowed us to call John:
exten => 101,1,Dial(${JOHN})Next, let’s add an unavailable message that the caller will be
played if John doesn’t answer the phone within 10 seconds. 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,Dial(${JOHN},10)
exten => 101,n,VoiceMail(101@default,u)
Now, let’s change it so that if John is busy (on another call),
it’ll send us to his voicemail, where we’ll hear his busy message. To do
this, we will make use of the ${DIALSTATUS} variable
which contains one of several status values (see core show application dial at the Asterisk
console for a listing of all the possible values):
exten => 101,1,Dial(${JOHN},10)
exten => 101,n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy:unavail)
exten => 101,n(unavail),Voicemail(101@default,u)
exten => 101,n,Hangup()
exten => 101,n(busy),VoiceMail(101@default,b)
exten => 101,n,Hangup()Now callers will get John’s voicemail (with the appropriate greeting) if John is either busy or unavailable. A slight problem remains, however, in that John has no way of retrieving his messages. Let’s remedy that.
Users can retrieve their voicemail messages, change their voicemail options, and record
their voicemail greetings by using the VoiceMailMain() application. In its typical
form, VoiceMailMain() is called
without any arguments. Let’s add extension 700 to the [internal] context of our dialplan so that
internal users can dial it to access their voicemail messages:
exten => 700,1,VoiceMailMain()
One last feature of the Asterisk voicemail system 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 the 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.