The /etc/asterisk/voicemail.conf file is sectioned into contexts, similar to how the extensions.conf file is setup. The first context of the voicemail.conf file is the [general] section. This section is used to configure the operation of the voicemail system. The second context is the [zonemessages] section. This context is used to defines time zones and time reporting formats. Additional contexts can be added to define groups of users .
The general sections has several options that can be set. Below is a table defining the options:
| attach | If attach=yes, Asterisk copies a voicemail message to an audio file and sends it to the user as an attachment in an e-mail voicemail notification message. The default value is no. |
| callback | Specify a context to be used from the “return phone call” feature in the advanced voicemail features menu. This setting takes a string value set to the outgoing context to be used. The default value for this setting is an empty string. This setting is only available in versions of Asterisk with advanced voicemail feature support. |
| cidinternalcontexts | This setting defines the internal contexts used to determine the type of voice announcement to play when reading back the caller ID in a message envelope, or when the saycid advanced feature is enabled. In case of an internal call the voice prompt reads “Call from extension …” instead of “Call from 12345678”. This setting is only available in versions of Asterisk with advanced voicemail feature support. The value is a string listing the internal contexts. Each additional internal context should be separated from the previous one with a comma. The default value is an empty string, and no internal contexts defined. |
| dbhost | Specify the Mysql database server hostname for the voicemail application to use. The value is a string. The default value is an empty string. Note that Asterisk has to be compiled for Mysql support for this option to be meaningful. |
| dbname | Specify the Mysql database name. The value is a string. The default value is “vmdb”. Note that Asterisk has to be compiled for Mysql support for this option to be meaningful. |
| dboption | Specify the Postgres database option. The value is a string. The default value is an empty string. Note that Asterisk has to be compiled for Postgres support for this option to be meaningfu1, and this option must be specified if Postgres support is enabled. |
| dbpass | Specify the Mysql database password for the voicemail application to use. The value is a string. The default value is “test”. Note that Asterisk has to be compiled for Mysql support for this option to be meaningful. |
| dbuser | Specify the Mysql database user name for the voicemail application to use. The value is a string. The default value is “test”. Note that Asterisk has to be compiled for Mysql support for this option to be meaningful. |
| delete | If set to “yes” the message will be deleted from the voicemailbox (after having been emailed). The delete flag, when used alone (instead of with voicemail broadcast), provides functionality that allows a user to receive their voicemail via email alone. Note This settting does not always work as a global setting. It is recommended to put this as an option for each voice mailbox that’s messages are to be deleted after being emailed. Note This setting needs to be prefixed with a | not a , in order to set it on a user’s extension if other settings are being configured. For example 823 => 1234,office,[email protected],,attach=yes|delete=1 |
| dialout | Specify a context to be used from the “place an outgoing call” feature in the advanced voicemail features menu. This setting takes a string value set to the outgoing context to be used. The default value for this setting is an empty string. This setting is only available in versions of Asterisk with advanced voicemail feature support. |
| emailbody | This setting overrides the normal message text seen in the body of a voicemail notification message. It also supports variable substitution which can be used to make the message more meaningful. The format would look like this: emailbody=\n\tHi ${VM_NAME},\n\n\tYou have a ${VM_DUR} long new voicemail message (number ${VM_MSGNUM}) in mailbox ${VM_MAILBOX}\nfrom ${VM_CIDNAME} (${VM_CIDNUM}), on ${VM_DATE}\nso you might want to check it when you get a chance.\n\n Notice thats a single line without quotes… Use \n \t to do formatting. A list of macro-like expansion tokens are listed below. If you need to specify a specific body per mailbox, have a look at this patch. Variables include: VM_NAME VM_DUR VM_MSGNUM VM_MAILBOX VM_CIDNUM VM_CIDNAME VM_CALLERID VM_DATE |
| emaildateformat | Only used in combination with ’emails’ and not ‘pager’. If you use ${VM_DATE} in an email then the format you had given will be displayed. The format can be made with the abbrevations taken from strftime (see http://www.opengroup.org/onlinepubs/009695399/functions/strftime.html (Links to an external site.)) |
| emailsubject | This setting completely overrides Subject: line in the voicemail notification message, and substitutes its own text in place of it. The value passed is a string containing the text to send in place of the Subject: line. A list of macro-like expansion tokens are listed below. NOTE: \t and \n do not expand as you might expect in this field. If you need to specify a specific subject per mailbox, have a look at this patch. Example: emailsubject=New voicemail in mailbox ${VM_MAILBOX} from ${VM_CALLERID}. Variables include: VM_NAME VM_DUR VM_MSGNUM VM_MAILBOX VM_CIDNUM VM_CIDNAME VM_CALLERID VM_DATE |
| envelope | Envelope controls whether or not Asterisk will play the message envelope (date/time) before playing the voicemail message. This settng does not affect the operation of the envelope option in the advanced voicemail menu. Envelope takes two values yes or no. The default value is yes. Note: this is only in the Asterisk CVS version dated 5/19/04 or later. |
| exitcontext | Optional context to drop the user into after he/she has pressed * or 0 to exit voicemail. If not set, pressing * or 0 will return the caller to the last context they were in before being sent to voicemail (assuming that context has a ‘a’ or ‘o’ extension). |
| externnotify | Want to run an external program whenever a caller leaves a voice mail message for a user? This is where the externnotify command comes in handy. Externnotify takes a string value which is the command line you want to execute when the caller finishes leaving a message. Note: see an example of an external notification script . Note: This command will also run after a person who has logged into a mailbox exits the VoiceMailMain() application. (Remark: This seems not to be the case for Asterisk 1.2.x) The way it works is basically any time that somebody leaves a voicemail on the system (regardless of mailbox number), the command specified for externnotify is run with the arguments (in this order): context, extension, new voicemails, old voicemails and urgent voicemails. These arguments are passed to the program that you set in the externnotify variable. |
| externpass | Want to run an external program whenever a user change it’s voicemail password? This is where the externpass command comes in handy. Externpass takes a string value which is the command line you want to execute when the users finishes change it’s password. Note: if you use this setting, internal change_password function will not be used to regenerate voicemail.conf Since Asterisk 1.0.10, when using the externpass option for voicemail, the password will be immediately updated in memory as well, instead of having to wait for the next time the configuration is reloaded. For previous version you must do a reload of app_voicemail. |
| externpasscheck | Added in 1.6.1, if you want to impose security restrictions on your voicemail password, specify a script here. Arguments for this script are: mailbox context oldpass newpass |
| format | The format setting selects audio file format(s) to use when storing voice mail messages. The value is a string defining the audio format(s) of the message file. The default format string is wav49|gsm|wav, meaning that Asterisk will save the voicemail message in all three supported formats. When emailing the attachment, however, it will send only the first of the formats defined here. When playing back (as with all file playback) Asterisk will attempt to use the optimum format based on the codec used for the current channel, in order to provide the best sound quality and to reduce transcoding processing time. wav49: In this format, the file size will be small, the quality good, and it’s a good choice for sending voicemail messages in email. The file will have a .WAV extension, which all Windows users should have no problems with, and users on other platforms should also be able to easily play these sound files. gsm: Voicemail saved in this format will have about the same file size and same audio quality as wav49. It may be less well supported by client operating systems if sent to users in email, however. wav: This is an uncompressed sound format with a .wav extension, so the file size is very large. Sound quality will be great, but you probably don’t want to email it, and you must have adequate disk space. g723sf: The sample voicemail.conf file has this option commented out. If you try to activate it, you will find that it doesn’t work. If you’re running Asterisk on Mac OS X, which has a case-preserving but case-insensitive file system, you can use .wav but you won’t be able to use .WAV(wav49). Asterisk tries to pick the best file in the Playback command based on the encoding of your channel, and then looks for the file by file type in a specific order. In either case, asterisk will look for filename.wav, and if there is a filename.WAV, the file lookup will succeed. Asterisk will then try to play the file as “wav”, and choke on the format. This is especially noticeable in voicemail. If you have both wav49 and wav in the format= option, one will replace the other. You must remove wav49 from the format= option in voicemail.conf. |
| fromstring | This setting allows the adminstrator to override a portion of the From: line in the voicemail notification message. By default, Asterisk sends the string “From: Asterisk PBX <who>. The “Asterisk PBX” portion of the From: line can be overridden by specifying your own string as the value for this setting. One might use this to customize the voicemail notification message and/or remove the reference to “Asterisk PBX”. |
| mailcmd | Mailcmd allows the administrator to override the default mailer command with a defined command. Mailcmd takes a string value set to the desired command line to execute when a user needs to be notified of a voice mail message. The default command line is: ‘/usr/sbin/sendmail -t’. A useful alternative to sendmail is Exim (Links to an external site.) which many people find easier to configure. Examples mailcmd=/usr/sbin/sendmail -v -t -f [email protected] ; use -f to prevent [email protected] or similar mailcmd=/usr/exim/bin/exim -t ; — use the next line for testing mailcmd=cat >> /tmp/astvm-mail |
| maxgreet | This setting allows the adminstrator to limit the length of the user-recordable voicemail greeting. Use this option on systems with a large number of users and limited disk space. The value is an integer defining the maximum length in seconds of a greeting message. The default value is 0 which means that the greeting message can be any length. This setting will control the lengths of the unavailable greeting, busy greeting, and user name messages. |
| maxlogins | This setting defines the number of retries a user has to enter voicemail passwords before Asterisk will disconnect the user. The value should be a positive integer. The default value for this setting is 3. |
| maxmessage | This defines the maximum amount of time in seconds of an incoming message. Use this when there are many users and disk space is limited. The default value for this setting is 0 which means there will be no maximum time limit enforced. |
| maxmsg | This limits the number of messages in a voicemail folder. The maximum value is 9999 (hard coded) and the default 100. When a mailbox has more than this number of messages in it, new messages can not be recorded and vm-mailboxfull is played to the caller. No more messages possible is also logged. This setting was introduced in 1.2. In previous versions it was hard coded to 100. |
| maxsilence | Maxsilence defines how long Asterisk will wait for a contiguous period of silence before terminating an incoming call to voice mail. The default value is 0, which means the silence detector is disabled and the wait time is infinite. Maxsilence takes a value of zero or a positive integer value which is the number of seconds of silence to wait before disconnecting. |
| minsecs (used to be called minmessage) | This setting can be used to eliminate messages which are shorter than a given amount of time in seconds. The default value for this setting is 0 which means there will be no minimum time limit enforced. |
| nextaftercmd | If set to “yes,” after deleting a voicemail message, the system will automatically play the next message. |
| operator | This setting enables the user to reach an operator during the time the voicemail message is being recorded, or once a voicemail message has been left, if the review option has been set to yes. This setting takes a yes or no value. The operator must be specified at extension ‘o’ in extensions.conf, in the context you specify with the voicemail.conf option exitcontext (see below). This setting is only available in versions of Asterisk with advanced voicemail feature support. |
| pagerbody | This setting overrides the normal message text seen in the body of a SMS voicemail notification message. It also supports variable substitution which can be used to make the message more meaningful. Example: pagerbody=${VM_DATE} – ${VM_MAILBOX} has a new voicemail from ${VM_CALLERID} (${VM_DUR} seconds). |
| pagerfromstring | This setting allows the adminstrator to override a portion of the From: line in the voicemail pager notification message. By default, Asterisk sends the string “From: Asterisk PBX <who>. The “Asterisk PBX” portion of the From: line can be overridden by specifying your own string as the value for this setting. One might use this to customize the voicemail pager notification message and/or remove the reference to “Asterisk PBX”. |
| pbxskip | This setting changes the Subject: line in a voicemail notification message. This setting takes a yes or no value. The default value is no. When set to yes the Subject: line will read “Subject: New message M in mailbox B”. When set to no the Subject: line will read “Subject: [PBX]: New message M in mailbox B”. |
| review | Sometimes it is nice to let a caller review their message before committing it to a mailbox. This setting takes a yes or no value. If set to yes, then the caller will be asked to review the message, or save it as is after they have pressed ‘#’. If set to no, the message will be saved and the voice maill system will disconnect the caller. The default value for review is no. This setting is only available in versions of Asterisk with advanced voicemail feature support. |
| saycid | Read back caller’s telephone number prior to playing the incoming message, and just after announcing the date and time the message was left. This setting takes a yes or no value. If the administrator wants the caller’s phone number to be heard prior to playing back a voicemail message, this option should be set to yes. The default value for saycid is no. This setting is only available in versions of Asterisk with advanced voicemail feature support. |
| sendvoicemail | This setting takes a yes or no value. It enables the “Leave a message” menu option from the Advanced Options menu which allows the voicemail user to send a message to another voicemail user. |
| serveremail | This setting can be used to identify the source of a voicemail notification message. The value is a string which can be encoded one of two ways. If the string is of the form [email protected], then the string will be used as the source address for all voicemail notification emails. If the string is of the form someone, then the host name of the machine running Asterisk will be postpended to the string after insertion of a ‘@’. |
| silencethreshold | When using the maxsilence setting, it is sometimes necessary to adjust the silence detection threshold to eliminate false triggering on background noise. Silencethreshold allows the adminstrator to do just that. The default silencethreshold value is 128. Higher numbers raise the threshold so that more background noise is needed to cause the silence detector to reset. When employing this setting, some experimentation will be necessary to find the best result. |
| skipms | This setting defines an interval in milliseconds to use when skipping forward or reverse while a voicemail message is being played. The value entered here should be a positive integer. The default value for this setting is 3000 (3 seconds). |
| usedirectory | If set to “yes” Asterisk allows to forward emails to another voicemailbox by choosing a local name. This can be done by pressing 8 in the voicemailboxmenu after the user has heard a voicemail. After this he has to choose between dialing the number of the recipient (Button: 1) or choosing a name which should be defined whether in the file voicemail.conf or in users.conf (Button: 2). |
| volgain | Set the gain to use when sending a recorded message via email attachment. Requires sox. |
The [zonemessages] section
The zonemessages section allows custom time zones, and the way time is recorded to be defined. With a large Asterisk system, users may have different time zones, and have different formats for announcing the date and time of voicemail messages. Time zones defined in this section can be set to individual malboxes by specifying a tz= option.
An example of a [zonemessage] option defined is:
eastern=America/New_York|’vm-received’ Q ‘digits/at’ IMp
The example defines “eastern” as the time zone name. It can be any name you want to define. “America” is the country. “New York” is the city. The country/city comes from the timezone information availabe in Ubuntu. A list of availabe combinations is located in the /usr/share/zoneinfo directory.
The settings following the city are the additional options. “vm-recieved” Q “digits/at” IMp
One or more sound files or announce options may be inserted after the ‘|’ delimiter. The sound files should be surrounded by single quotes such as ‘vm-received’ . The announce options are either single characters or a variable substitution ( ${xxx} ). Multi-character strings of announce options are permitted such as HM. The announce options which can be specified for the options field are:
| Option | Description |
|---|---|
| ‘filename’ | filename of a soundfile (single ticks around the filename required) |
| ${VAR} | variable substitution |
| A or a | Day of week (Saturday, Sunday, …) |
| B or b or h | Month name (January, February, …) |
| d or e | numeric day of month (first, second, …, thirty-first) |
| Y | Year |
| I or i | Hour, 12 hour clock |
| H | Hour, 24 hour clock (single digit hours preceded by “oh”) |
| k | Hour, 24 hour clock (single digit hours NOT preceded by “oh”) |
| M | Minute |
| P or p | AM or PM |
| 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 minute |