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.[83] Some of the features of Asterisk’s voicemail system include:
Unlimited password-protected voicemail boxes, each containing mailbox folders for organizing voicemail
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[84]
Message-waiting indicator (flashing light or stuttered dialtone) on many types of phones
And that’s just the tip of the iceberg!
The default version of the /etc/asterisk/voicemail.conf 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 first section, [general], allows you to define global
settings for your voicemail system. The available options are listed in
Table 8.1, “[general] section options for voicemail.conf”.
Table 8.1. [general] section options for voicemail.conf
| Option | Value/Example | Notes |
|---|---|---|
format | For each format listed, Asterisk will create a separate recording in that format whenever a message is left. The benefit of this is that some transcoding steps may be saved if the stored format is the same as the codec used on the channel. We like wav because it is the highest quality, and wav49 because it is nicely compressed and easy to email. We don’t like gsm due to it’s scratchy sound, but it enjoys some popularity.[a] | |
serveremail | user@domain | When an email is sent from Asterisk, this is the email address that it will appear to come from.[b] |
attach | yes,no | If an email address is specified for a mailbox, this determines whether the messages is attached to the email (if not, a simple message notification is sent). |
maxmsg | 9999 | By default Asterisk will only allow a maximum of 100 messages to be stored per user. For users who delete messages, this is no problem. For people who like to save their messages, this space can get eaten up quickly. With the size of hard drives these days, you could easily store thousands of messages for each user, so our current thinking is to set this to the maximum and let the users manage things from there. |
maxsecs | 0 | This type of setting was useful back in the days when a
large voicemail system might have only 40 MB[c] of storage: it was necessary to limit the system
because it was easy to fill up the hard drive. This setting can
be annoying to callers (although it does force them to get to
the point, so some people like it). Nowadays, with terabyte
drives becoming common, there is no reason not to set this to a
high value. Two considerations are: 1) if a channel gets hung in
a mailbox, it’s good to set some sort of value so it doesn’t
stay there for days, but 2) if a user wants to use her mailbox
to record notes to herself, she won’t appreciate it if you cut
her off after three minutes. A setting somewhere between
600 seconds (10 minutes) and
3600 seconds (1 hour) will
probably be about right. |
minsecs | 4 | Many folks will hang up instead of leaving a message when they call somebody and get voicemail. Sometimes this hangup happens after recording has started, so the mailbox owner gets an annoying two-second message of somebody hanging up. This setting ensures that Asterisk will ignore messages that are shorter than the configured minimum length. You should take care not to set this to a value that is too high, though, because then a message like “Hey it’s me give me a call” (which can be said in less than one second) will get lost, and you’ll get complaints of messages disappearing. Three seconds seems to be about right. To discourage people from leaving ultra-short messages that might be discarded, you can request callers to identify themselves and leave some information about why they called. |
maxgreet | 1800 | You can define the maximum greeting length if you want. Again, since storage is not a problem and setting this too low will annoy your more verbose users, we suggest setting this to a high value and letting your users figure it out an appropriate length for themselves. |
skipms | 3000 | When listening to messages, users can skip ahead or
backwards by pressing (by default) * and #. This setting indicates the length
of the jump (in milliseconds). |
maxsilence | 5 | This setting defines the maximum time for which the
caller can remain silent before the recording is stopped. We
like to set this setting to one second longer than minsecs (if you set it equal to or
greater than minsecs, you
will get a warning). |
silencethreshold | 128 | You can fine-tune the silence sensitivity of Asterisk to better define what qualifies as silence. In practice, this is seldom a good idea, since you cannot control the volumes of all the calls you’ll be getting from different places. It’s best to leave this at the default. |
maxlogins | 3 | This little security feature is intended to make
brute-force attacks on your mailbox passwords more
time-consuming. If a bad password is received this many times,
voicemail will hang up and you’ll have to call back in to try
again. Note that this will not lock up the mailbox. Patient
snoopers can continue to try to log into your mailbox as many
times as they like, they’ll just have to call back every third
attempt. If you have a lot of ham-fingered users, you can set
this to something like 5. |
moveheard | yes | This setting will move listened-to messages to the
Old folder. We recommend
leaving this at the default. |
forward _ urgent _ auto | no | Setting this to yes
will preserve the original urgency setting of any messages the
user receives and then forwards on. If you leave it at no, users can set the urgency level
themselves on messages that they forward. |
userscontext | default | If you use the users.conf file (we don’t), you can
define here the context where entries are registered. |
externnotify | /path/to/script | If you wish to run an external app whenever a message is left, you can define it here. |
smdienable | no | If you are using Asterisk as a voicemail server on a PBX that supports SMDI, you can enable it here. |
smdiport | /dev/ttyS0 | Here is where you would define the SMDI port that messages between Asterisk and the external PBX would pass across. |
externpass | /path/to/script | Any time the password on a mailbox is changed, the script
you define here will be notified of the context, mailbox, and new password. The script will then be
responsible for updating voicemail.conf (the Asterisk
voicemail app will not update the password if this parameter is
defined). |
externpassnotify | /path/to/script | Any time the password on a mailbox is changed, the script
you define here will be notified of the context, mailbox, and new password. Asterisk will handle
updating the password in voicemail.conf. If you have defined
externpass, this option will
be ignored. |
externpasscheck | /usr/local/bin/voicemailpwcheck.py | See the sidebar following this table for a description of this option. |
directoryintro | dir-intro | The Directory()
dialplan application uses the voicemail.conf file to search by name
from an auto attendant. There is a default prompt that plays,
called dir-intro. If you
want, you can specify a different file to play instead. |
charset | ISO-8859-1 | If you need a character set other than ISO-8859-1 (a.k.a Latin 1) to be supported, you can specify it here. |
adsifdn | 0000000F | Use this option to configure the Feature Descriptor Number.[d] |
adsisec | 9BDBF7AC | Use this option to configure the security lock code. |
adsiver | 1 | This specifies the ADSI voicemail application version number. |
pbxskip | yes | If you do not want emails from your voicemail to have the
string [PBX] added to the subject, you can set this to yes. |
fromstring | The Asterisk PBX | You can use this setting to configure the From: name that will appear in emails
from your PBX. |
usedirectory | yes | This option allows users composing messages from their mailboxes to take advantage of the Directory. |
odbcstorage | <item from res_odbc.conf>
| If you want to store voice messages in a database, you
can do that using the Asterisk res_odbc connector. Here, you would
set the name of the item in the res_odbc file. For details, see Chapter 22, Clustering. |
odbctable | <table name> | This setting specifies the table name in the database
that the odbcstorage setting
refers to. For details, see Chapter 22, Clustering. |
emailsubject | [PBX]: New
message
${VM_MSGNUM} in mailbox
${VM_MAILBOX} | When Asterisk sends an email, you can use this setting to
define what the Subject: line
of the email will look like. See the voicemail.conf.sample file for more
details. |
emailbody | Dear ${VM_NAME}:\n\n\tjust wanted to let you know
you were just left a ${VM_DUR} long message (number
${VM_MSGNUM})\nin mailbox ${VM_MAILBOX u might\nwant to check it
when you get a chance. Thanks!\n\n\t\t\t\t--Asterisk\n
| When Asterisk sends an email, you can use this setting to
define what the body of the email will look like. See the
voicemail.conf.sample file
for more details. |
pagerfromstring | The Asterisk PBX | We don’t actually know anybody who uses pagers anymore (nor can we recall having seen one in many years), but if you have one of these historical oddities and you want to customize what Asterisk sends with its pager notification, presumably you can do that with this. A very practical usage of this feature for short message voicemail notifications is to send a message to an email to SMS gateway. |
pagersubject | New VM | As above. |
pagerbody | New ${VM_DUR} long msg in box ${VM_MAILBOX}\nfrom
${VM_CALLERID}, on ${VM_DATE} | The formatting for this uses the same rules as emailbody. |
emaildateformat | %A, %d %B %Y at %H:%M:%S | This option allows you to specify the date format in
emails. Uses the same rules as the C function STRFTIME. |
pagerdateformat | %A, %d %B %Y at %H:%M:%S | This option allows you to specify the date format in
pager. Uses the same rules as the C function STRFTIME. |
mailcmd | /usr/sbin/sendmail -t | If you want to override the default operating system application for sending mail, you can specify it here. |
pollmailboxes | no, yes | If the contents of mailboxes are changed by anything
other than app_voicemail
(such as external applications or another Asterisk system),
setting this to yes will
cause app_voicemail to poll
all the mailboxes for changes, which will trigger proper message
waiting indication (MWI) updates. |
pollfreq | 30 | Used in concert with pollmailboxes, this option specifies
the number of seconds to wait between mailbox polls. |
imapgreetings | no, yes | This enables/disables remote storage of greetings in the IMAP folder. For more details, see Chapter 18, External Services. |
greetingsfolder | INBOX | If you’ve enabled imapgreetings, this parameter allows
you to define the folder your greetings will be stored in
(defaults to INBOX). |
imapparentfolder | INBOX | IMAP servers can handle parent folders in different ways. This field allows you to specify the parent folder for your mailboxes. For more details, see Chapter 7, Outside Connectivity. |
[a] The separator that is used for
each format option must be the pipe ( [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 in Chapter 18, External Services. [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 (listed in
Table 8.2, “Advanced options for voicemail.conf”) 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, overriding
whatever is defined under [general]
for that particular setting.
Table 8.2. Advanced options for voicemail.conf
| Option | Value/Example | Notes |
|---|---|---|
tz | eastern, european, etc. | Specifies the zonemessages name, as defined in the
[zonemessages] section, discussed in
the next section. |
locale | de_DE.utf8, es_US.utf8, etc. | Used to define how Asterisk generates date/time strings in different locales. To determine the locales that are valid on your Linux system, type locale -a at the shell. |
attach | yes, no | If an email address is specified for a mailbox, this determines whether the messages are attached to the email notifications (otherwise, a simple message notification is sent). |
attachfmt | wav49, wav, etc. | If attach is enabled
and messages are stored in different formats, this defines which
format is sent with the email notifications. Often wav49 is a good choice, as it uses a
better compression algorithm and thus will use less
bandwidth. |
saycid | yes, no | This command will state the caller ID of the person who left the message. |
cidinternalcontexts | <context>,
<another context> | Any dialplan contexts listed here will be searched in an attempt to locate the mailbox context, so that the name associated with the mailbox number can be spoken. The voicemail box number needs to match the extension number that the call came from, and the voicemail context needs to match the dialplan context.[a] |
sayduration | yes, no | This command will state the length of the message. |
saydurationm | 2 | Use this to specify the minimum duration of a message to
qualify for its length being played back. For example, if you
set this to 2, any message
less than 2 minutes in length will not have its length
stated. |
dialout | <context> | If allowed, users can dial out from their mailboxes. This
is considered a very dangerous feature in a phone system (mainly
because many voicemail users like to use 1234 as their password), and is
therefore not recommended. If you insist on allowing this, make
sure you have a second level of password in the dialplan where
another password is specified. Even so, this is not a safe
practice. |
sendvoicemail | yes, no | This allows users to compose messages to other users from within their mailboxes. |
searchcontexts | yes, no | This allows voicemail applications in the dialplan to not have to specify the voicemail context, since all contexts will be searched. This is not recommended. |
callback | <context> | This specifies which dialplan context to use to call back to the sender of a message. The specified context will need to be able to handle dialing of numbers in the format in which they are received (for example, the country code may not be received with the caller ID, but might be required for the outgoing call). |
exitcontext | <context> | There are options that allow the callers to exit the
voicemail system when they are in the process of leaving a
message (for example, pressing 0 to get an operator). By default, the
context the caller came from will be used as the exit context.
If desired, this setting will define a different context for
callers exiting the voicemail system. |
review | yes, no | This should almost always be set to yes (even though it defaults to
no). People get upset if your
voicemail system does not allow them to review their messages
prior to delivering them. |
operator | yes, no | Best practice dictates that you should allow your callers
to “zero out” from a mailbox, should they not wish to leave a
message. Note that an o
extension (not “zero,” “oh”) is required in the exitcontext in order to handle these
calls. |
envelope | no, yes | You can have voicemail play back the details of the
message before it plays the actual message. Since this
information can also be accessed by pressing 5, we generally set this to no. |
delete | no, yes | After an email message notification is sent (which could
include the message itself), the message will be deleted. This
option is risky, because even though a message was emailed, it
is no guarantee that it was received (spam filters seem to love
to delete Asterisk voicemail messages). Point being: on a new
system, leave this at no
until you are certain that no messages are being lost due to
spam filters. |
volgain | 0.0 | This setting allows you to increase the volume of
received messages. Volume used to be a problem in older releases
of Asterisk, but has not been an issue for many years. We
recommend leaving this at the default. The sox utility is required
for this to work. |
nextaftercmd | yes, no | This handy little setting will save you some time, as it takes you directly to the next message once you’ve finished dealing with the current message. |
forcename | yes, no | This strange little setting will check if the mailbox password is the same as the mailbox number. If it is, it will force the user to change his voicemail password and record his name. |
forcegreetings | yes, no | As above, but for greetings. |
hidefromdir | no, yes | If you wish, you can hide specific mailboxes from the
Directory() application using
this setting. |
tempgreetwarn | yes, no | Setting this to yes
will warn the mailbox owner that she has a temporary greeting
set. This can be a useful reminder when people return from trips
or vacations. |
passwordlocation | spooldir | If you want, you can have mailbox passwords stored in the spool folder for each mailbox.[b] |
messagewrap | no, yes | If this is set to yes,
when the user has listened to the last message, pressing next
(6) will take him to the
first message. Also, pressing previous (4) when at the first message will take
the user to the last message. |
minpassword | 6 | This option enforces a minimum password length. Note that
this does not prevent the users from setting their passwords to
something that’s easy to guess (such as 123456). |
vm-password | custom_sound | If you want, you can specify a custom sound here to use for the password prompt in voicemail. |
vm-newpassword | custom_sound | If you want, you can specify a custom sound here to use for the “Please enter your new password followed by the pound key” prompt in voicemail. |
vm-passchanged | custom_sound | If you want, you can specify a custom sound here to use for the “Your password has been changed” prompt in voicemail. |
vm-reenterpassword | custom_sound | If you want, you can specify a custom sound here to use for the “Please reenter your password followed by the pound key” prompt in voicemail. |
vm-mismatch | custom_sound | If you want, you can specify a custom sound here to use for the “The passwords you entered and reentered did not match” prompt in voicemail. |
vm-invalid-password | custom_sound | If you want, you can specify a custom sound here to use for the “That is not a valid password. Please try again” prompt in voicemail. |
vm-pls-try-again | custom_sound | If you want, you can specify a custom sound here to use for the “Please try again” prompt in voicemail. |
listen-control-forward-key | # | You can use this setting to customize the fast forward key. |
listen-control-reverse-key | * | You can use this setting to customize the rewind key. |
listen-control-pause-key | 0 | You can use this setting to customize the pause/unpause key. |
listen-control-restart-key | 2 | You can use this setting to customize the replay key. |
listen-control-stop-key | 13456789 | You can use this setting to customize the interrupt playback key. |
backupdeleted | 0 | This setting will allow you to specify how many deleted
messages are automatically stored by the system. This is similar
to a recycle bin. Setting this to 0 disables this feature. Up to 9999
messages can be stored, after which the oldest message will be
erased each time another message is deleted. |
[a] Yes, we found this a bit confusing too. [b] Typically the spool folder is | ||
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/1.8/configs/voicemail.conf.sample
file for syntax details. Asterisk includes the examples shown in Table 8.3, “[zonemessages] section options for voicemail.conf”.
Table 8.3. [zonemessages] section options for voicemail.conf
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:
mailbox =>password[,FirstNameLastName[,addr[,pageraddr[,options[|options]]]]]
The pipe character (|) used to be more popular in Asterisk. For the first few
years, it was used as the standard delimiter. More recently, it has
almost completely been replaced by the comma; however, there are
still a few places where the pipe is used. One of them is in
voicemail.conf: for example, as
a separator for any mailbox-specific options, and also as the
separator character in the format= declarative. You’ll see this in
our upcoming example, as well as in the voicemail.conf.sample file.
The parts of the mailbox definition are:
mailboxThis is the mailbox number. It usually corresponds with the extension number of the associated set.
passwordThis 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.
FirstName LastNameThis is the name of the mailbox owner. The company directory uses the text in this field to allow callers to spell usernames.
email addressThis 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 addressThis 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.
optionsThis field is a list of options
for setting the mailbox owner’s time zone and overriding 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.
The mailboxes you define in your voicemail.conf file might look like the
following examples:
[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=yes [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 Asterisk directory cannot handle
the concept of a family name that is anything other than a simple
word. This means that family names such as
O’Reilly, Jones-Smith, and
yes, even Van Meggelen must have any
punctuation characters and spaces removed before being added to
voicemail.conf.
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.
We recommend the following sample as a starting point. You
can refer to ~/asterisk-complete/asterisk/1.8/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
Setting up a Linux server to handle the sending of email is a Linux administration task that is beyond the scope of this book. You will need to test your voicemail to email service to ensure that the email is being handled appropriately by the Mail Transfer Agent (MTA),[85] and that downstream spam filters are not rejecting the messages (one reason this might happen is if your Asterisk server is using a hostname in the email body that does not in fact resolve to it).