The voicemail.conf file controls the
Asterisk voicemail system (called Comedian Mail). It consists of three
main sections. The first, called [general], sets the general system-wide settings
for the voicemail system. The second, called [zonemessages], allows you to configure
different voicemail zones, which are a collection of time and time zone
settings. The third and final section is where you create one or more
groups of voicemail boxes, each containing the mailbox definitions. For
more information on adding voicemail capabilities to your dialplan, see
Chapter 6, More Dialplan Concepts.
The [general] section of
voicemail.conf contains a plethora of options that
affect the entire voicemail system:
format
Lists the codecs that should be used to save voicemail
messages. Codecs should be separated with the pipe character
(|). The first format specified
is the format used when attaching a voicemail message to an email.
Defaults to wav49|gsm|wav. The
reason that the voicemail might be saved in several different
formats is to minimize the amount of transcoding that Asterisk
does when the voicemail is played back.
serveremail
Provides the email address from which voicemail notifications should be sent.
attach
Specifies whether or not Asterisk should attach the voicemail sound file to the voicemail notification email.
maxmsg
Sets the maximum number of messages that may be kept in any voicemail folder.
maxmessage
Sets the maximum length of a voicemail message, in seconds.
minmessage
Sets the minimum length of a voicemail message, in seconds.
maxgreet
Sets the maximum length of voicemail greetings, in seconds.
skipms
Specifies how many milliseconds to skip forward/back when the user skips forward or backward during message playback.
maxsilence
Indicates how many seconds of silence to allow before ending the recording.
silencethreshold
Sets the silence threshold (what we consider “silence”—the lower the threshold is, the more sensitive it is).
maxlogins
Sets the maximum allowed number of failed login attempts.
userscontext
Specifies which voicemail context the mailboxes defined in
users.conf should be a part
of. This defaults to the default voicemail context.
externnotify
Supplies the full path and filename of an external program
to be executed when a voicemail is left or delivered, or when a
mailbox is checked. It can also be set to smdi to use SMDI for external
notification. If it is smdi,
the smdiport should be set to a
valid port as specified in smdi.conf.
smdiport
Specifies the communications port used by SMDI. This should
correspond to a valid port as specified in smdi.conf. This is used when the
externnotify setting is set to
smdi.
externpass
Supplies the full path and filename of an external program to be executed whenever a voicemail password is changed.
directoryintro
If set, overrides the default introduction to the dial-by-name directory.
charset
Defines the character set for voicemail messages.
adsifdn
Specifies the ADSI feature descriptor number to download to.
adsisec
Sets the ADSI security lock code.
adsiver
Indicates the ADSI voicemail application version number.
pbxskip
Causes Asterisk not to add the string [PBX]: to the beginning of the subject
line of a voicemail notification email.
fromstring:Changes the From: string
of voicemail notification email messages.
usedirectory
Permits a mailbox owner to select entries from the dial-by-name directory for forwarding and/or composing new voicemail messages.
odbcstorage
If support for ODBC voicemail storage has been compiled into
Asterisk, this option allows you to specify which ODBC connection
to use. ODBC connections are defined in res_odbc.conf.
odbctable
This option is used in conjunction with the odbcstorage option. This option
specifies which database table to use for voicemail
messages.
emailsubject
Specifies the email subject of voicemail notification email messages.
pagerfromstring
Changes the From: string
of voicemail notification pager messages.
emailbody
Supplies the email body of voicemail notification email messages.
emaildateformat
Specifies the format of the date and time for outbound email
notifications. For more information on the format, see the
strftime(3) manpage.
mailcmd
Supplies the full path and filename of the program Asterisk should use to send notification emails. This option is useful if you want to override the default email program.
nextaftercmd
Skips to the next message after the user hits 7 or 9 to delete or save the current message. This can be set only globally at this time, not on a per-mailbox basis.
As voicemail users may be located in different geographical
locations, Asterisk provides a way to configure the time zone and the
way the time is announced for different callers. Each unique combination
is known as a voicemail zone. You configure your
voicemail zones in the [zonemessages]
section of voicemail.conf. Later, you can assign
your voicemail boxes to use the settings for one of these zones.
Each voicemail zone definition consists of a line with the following syntax:
zonename=timezone|time_format
The zonename is an arbitrary name used
to identify the zone. The timezone argument
is the name of a system time zone, as found in
/usr/share/zoneinfo. The
time_format argument specifies how times
should be announced by the voicemail system. The
time_format argument is made up of the
following elements:
'
filename
'
The filename of a sound file to play (single quotes around the filename are required)
${
VAR
}
Variable substitution
A
or
a
The day of the week (Saturday, Sunday, etc.)
B
or
b
or
h
The name of the month (January, February, etc.)
d or eThe numeric day of the month (first, second... thirty-first)
Y
The year
I
or
l
The hour, in 12-hour format
H
The hour, in 24-hour format—single-digit hours are preceded by “oh”
k
The hour, in 24-hour format—single-digit hours are not preceded by “oh”
M
The minute
P
or
p
A.M. or .P.M.
Q
“today”, “yesterday,” or ABdY (note: not standard strftime value)
q
“” (for today), “yesterday”, weekday, or ABdY (note: not standard strftime value)
R
24-hour time, including minutes
For example, the following example sets up two different voicemail zones, one for the Central time zone in 12-hour format, and a second in the Mountain time zone, in 24-hour format:
[zonemessages] central=America/Chicago|'vm-received' Q 'digits/at' IMp mountain24=America/Denver|'vm-received' q 'digits/at' H 'digits/hundred' M 'hours'
Now that the system-wide settings and voicemail zones have been set, you can define your voicemail contexts and individual mailboxes.
Voicemail contexts are used to separate out different groups of voicemail users. For example, if you are using Asterisk to host voicemail for more than one company, you should place each company’s mailboxes in different voicemail contexts, to keep them separate. You might also use voicemail contexts to create per-department dial-by-name directories.
To define a new voicemail context, simply put the context name inside of square brackets, like this:
[default]
Inside a voicemail context, each mailbox definition takes the following syntax:
mailbox=password,name[,pager_email[,options]]]
The mailbox argument is the mailbox
number.
The password argument is the numeric
code the mailbox owner must enter to access his voicemail. If the
password is preceded by a minus sign (-), the password may not be changed by the
mailbox owner.
If the password is set to d,
then this line is assumed to provide an alternate name that can be
used for this mailbox in the dial-by-name directory. In the following
example, people can reach extension 123 by searching for either Robert or Bob, along with a popular misspelling of his
last name:
123 => 4444,Robert Schauerhamer 123 => d,Bob Schauerhamer 123 => d,Robert Showerhammer
The email and
pager_email arguments are email addresses
where voicemail notifications will be sent. These may be left blank if
you don’t want to send voicemail notifications via email. The message
sent to the pager_email address is usually
shorter and suitable for sending to a cell phone (via an email to SMS
gateway) or to an alpha-numeric pager.
The options argument is a
pipe-separated list of voicemail options that may be specified for the
mailbox. (These options may also be set globally by placing them in the
[general]
section.) Valid voicemail options include:
tz
Sets the voicemail zone from the [zonemessages] section earlier. This
option is irrelevant if envelope is set to no.
attach
Attaches the voicemail to the notification email (but
not to the pager email). May be set to either
yes or no.
attachfmt
Specifies the format of the voicemail message that should be
attached to the message sent to the notification email.
Ordinarily, Asterisk uses the first format specified in the
format parameter listed in
[general] (covered earlier), but this may also
be changed on a per-mailbox basis. This option may be set
only on a per-mailbox basis.
This option is often used if Windows users want wav49 attachments but Linux users want their attachments in gsm format.
saycid
Says the Caller ID information before the message.
cidinternalcontexts
Sets the internal context for name playback instead of extension digits when saying the Caller ID information.
sayduration
Turns on/off the duration information before the message.
Defaults to on.
saydurationm
Specifies the minimum duration to say when sayduration is on. Default is two minutes.
dialout
Specifies the context to dial out from (by choosing option 4 from the advanced menu). If not specified, dialing out from the voicemail system will not be permitted.
sendvoicemail
Specifies the context to send voicemail from (by choosing option 5 from the advanced menu). If not specified, sending messages from within the voicemail system will not be permitted.
searchcontexts
By default, Asterisk searches only the default context if no context is
specified. To have Asterisk search all contexts, set this option
to yes.
callback
Specifies the context to call back from. If not specified, calling the sender back from within the voicemail system will not be permitted.
review
Allows senders to review/re-record their messages before
saving them. Defaults to off.
operator
Allows senders to hit 0
before, after, or while leaving a voicemail message to reach an
operator. Defaults to off.
envelope
Turns on/off envelope playback before message playback.
Defaults to on. This does not
affect option 3,3 from the advanced options menu.
delete
Deletes voicemails from the server after notification is sent. This option may be set only on a per-mailbox basis; it is intended for use with users who wish to receive their voicemail messages only by email.
volgain
If your voicemail attachments to email are too quiet, you can set this option to increase the gain on the message before it is attached to the email notification.
This option only works if the sox application has been installed
on your Asterisk system.
forcename
Forces new users to record their names. A new user is
determined by the password being the same as the mailbox number.
Defaults to no.
forcegreetings
Forces new users to record greetings. A new user is
determined by the password being the same as the mailbox number.
Defaults to no.
hidefromdir
Hides the mailbox from the dial-by-name directory. Defaults
to no.
tempgreetwarn
Warns users that their temporary greeting is still enabled.
You can specify multiple options by separating them with the pipe character, as shown in the definitions for mailboxes 102 and 103 below.
Here are some sample mailbox definitions:
[default] ; regular mailbox with email notification 101 => 4242,Example Mailbox,somebody@asteriskdocs.org ; more advanced mailbox with email and pager notification and a couple of ; special options 102 => 9855,Another User,another@asteriskdocs.org,pager@asteriskdocs.org, attach=no|tz=central ; a mailbox with no email notification and lots of extra options 103 => 6522,John Q. Public,,,tz=central|attach=yes|saycid=yes|dialout=fromvm| callback=fromvm|review=yes