Page tree
Skip to end of metadata
Go to start of metadata

About

mod_voicemail is a Dialplan Application that provides voicemail services via Diaplans. It lets you send calls to voicemail, which allows callers to leave messages for users and allows users to retrieve and manage any messages left by callers.

 Click here to expand Table of Contents

Synopsis

Dialplan variables

skip_greeting


Skips playback of greeting message when leaving messages. Variable is unset after voicemail application finishes.

If using a command to access voicemail, you can use the following to direct the playout of a custom greeting to the caller:


However, if using bridge to get to voicemail, you need to use "export" instead of "set" to get the channel variable to the correct leg of the call

 

skip_instructions


Skips playback of instructions when leaving messages. Variable is unset after voicemail application finishes.

However, if using bridge to get to voicemail, you need to use "export" instead of "set" to get the channel variable to the correct leg of the call

For instance, in dialplan/default.xml under <extension name="Local_Extension">, you would modify the xml by:

voicemail_callback_dialplan

Set's the dialplan for the voicemail callback. This channel variable will override the parameter 'callback_dialplan' in voicemail.conf.xml

voicemail_callback_context

Set's the dialplan context for the voicemail callback. This channel variable will override the parameter 'callback_context' in voicemail.conf.xml

Controlling User Parameters & Variables

When the following parameters are set in the extension conf files located in (conf/directory/'extension'.xml or conf/directory/default/'extension'.xml), they set options for your voicemail users

vm-enabled

When set to false this user will not have a voicemail box. This means busy and no answer calls will not forward to a voicemail box, nor will the user be able to log in to a voicemail box.

vm-alternate-greet-id

voicemail_alternate_greet_id

The parameter allows you to override the default extension or phone number spoken by the system in the voicemail greeting. This can also be set in the dialplan before calling the voicemail app.

This controls system greetings that read back a phone number, not user recorded greetings. To change to a different recorded greeting, use voicemail_greeting_number below.

 

Example setting the parameter in the user's directory entry. This example will say "8661234567" in the voicemail generic system greeting instead of the extension number 1004.

Parameter set in user directory entry

 

Example setting the variable before trasferring to voicemail. This example will say "2024561000" in the voicemail greeting instead of the extension number, for example 1019.

Variable set in dialplan

 

voicemail_greeting_number


Selects the user-recorded greeting to play.

If using a command to access voicemail, you can use the following to direct the playout of a custom greeting to the caller:


However, if using bridge to get to voicemail, you need to use "export" instead of "set" to get the channel variable to the correct leg of the call

By default, either of the above would play the file in $${base_dir}/storage/voicemail/default/$${domain}/<user>/greeting_1.wav. However, this file is not created until the user has recorded a custom greeting in slot 1.

If you have defined voicemail_greeting_number in the user's XML directory entry and would like to follow that value then execute the set_user app before transferring to voicemail.

http-allowed-api

This allows the user to use the web vm

vm-disk-quota


This will put a limit to the length of voicemail messages a user can store. If 0 or missing doesn't make any limitation. Default is no limitation.

The following example will limit the user's voicemail box to 30 seconds. When the limit exceed, The caller will hear "mailbox is full, please try your call again later, goodbye".

vm-mailto

This is the user's email address, default: undefined.
(originally called email-addr. Use vm-mailto instead)

This is defined in the directory for the particular user as a param. Multiple email addresses can be defined using a comma-separated list.

vm-mailfrom

This is the FROM address to send the email, default: undefined

This is defined in the directory for the particular user as a param.


in the voicemail template you can get this value using: ${voicemail_email_from}

vm-notify-mailto


The address you want notification messages sent to, default: same as vm-mailto.

This is defined in the directory for the particular user as a param.

vm-password


This is the user's configured voicemail PIN. This is additional to the voicemail password that the user can change in the voicemail system. If the value is set to "user-choose", then there is no configured password and only the user set password is used. Note that if you set the vm_password in the directory XML, any changes to the password from a phone are stored in the voicemail_prefs table. The module does not update the XML. The result is that there will be 2 passwords that can access the mail box, the one set in XML and the one that the user set from the phone.

This is defined in the directory for the particular user as a param.

Example:

vm-a1-hash

This parameter allows you to avoid sending the voicemail password in plain text. This is the same as the user a1-hash (see [[XML_User_Directory_Guide]]). Set this parameter to the MD5 hash of "userid:domain_name:vm-password". Example:

vm-email-all-messages

Setting to true will send all messages to vm-mailto address (attachment based on vm-attach-file param), default: false

This is defined in the directory for the particular user as a param.

vm-notify-email-all-messages


Setting to true will send a notify email to vm-notify-mailto when a vm is left (never has attachment)
default: false

This is defined in the directory for the particular user as a param.

vm_cc

Setting this variable will inject the message into the specified voicemail mailbox.
This is defined in the directory for the particular user as a variable.
Please note that the variable 'vm_cc' needs to be set as a channel variable before mod_voicemail is called. When set as a directory variable, it only becomes a channel variable when the UA is authenticated.

Dialplan Example (recommended):

Directory Example:

vm-keep-local-after-email

Setting to false will delete the local copy of the voicemail file after transmission of the mail message. When set to true the voicemail file will be kept locally and set as New for the phone to retrieve.
default: true

Example:

vm-attach-file


Setting to true will attach the audio file to the main email
default: false

This is defined in the directory for the particular user as a param.

Example:

vm-message-ext

This Parameter determines the storage type (and email type) for voicemails received and can be set per user. In order to use MP3 you must have mod_shout installed and loaded. The default is 'wav'.

Example:

vm_message_ext

Determines the storage type (and email type) for voicemails received and can be set per originating user or the Dial Plan. In order to use MP3 you must have mod_shout installed and loaded. The default is 'wav'. This may be set from the Dial Plan to override the file type. If this variable is set it overrides the vm-message-ext parameter.
When this variable is set on the originating user the specified file type will apply to the receiver of the message.

Example:

vm-skip-instructions


This disables instructions for how to leave a message, and instead just plays a beep.

notify-template-file

The notify email will use the same template as the main email unless you define the new profile
default: undefined

vm-storage-dir


This parameter allows to force the storage directory for voicemail files received and can be set per user. By default, voicemail files are stored in 'BASE_DIR/storage/voicemail/DOMAIN_NAME/USER_ID'.

It can be set to a full path, or a path relative to the BASE_DIR (usually /usr/local/freeswitch or /opt/freeswitch for debian installs).

Example:

(warning) Note: Most users either save voicemails locally, on a network file share directory or using a distribusted network file system, like glusterFS. https://www.gluster.org You can also save the voicemails locally and transfer to different FreeSWITCH servers in any manner: scp, rsync, Borgbackup, sneakernet, etc.

Here's a users input on GlusterFS:

Essentially, gluster is a cluster distributed filesystem. It uses local storage on each 'server' node, and that can then
be mounted on clients. It's intended for high performance compute resources, but works quite nicely for freeswitch backend.

In my case, I have 4 servers accessing the cluster - 2 freeswitch nodes that are setup as an HA pair using keepalived
(article already in wiki for that), 2 web server front end nodes for a local custom UI.

On the backend, I have the three gluster nodes for file service (odd number to insure quorum) and 3 Percona XTraDB mysql
nodes also operating as a cluster.

Everything except the two freeswitch instances is running as a VM. The FS nodes are running on real hardware.

The key difference with NFS is that the filesystem itself is redundant - so you can take any one of those backend nodes
out of service and it isn't visible (except as a momentary hang) to the servers that have the filesystem mounted.

http://lists.freeswitch.org/pipermail/freeswitch-users/2016-August/121650.html

vm-storage-dir-shared

If this is set to true (default false) we assume the storage-dir is shared, organized by realm/domain, with uses other than voicemail, so we adopt a directory structure of:

Example:

vm-domain-storage-dir

This is like vm-storage-dir but we append the user ID to the directory so if vm-domain-storage-dir is /var/lib/freeswitch/storage/example.com, it will store VM in /var/lib/freeswitch/storage/test.com/user_id.

Example:

Using Outside Programs to Send Voicemail to Email


There are times when you don't want or need an email server on your PBX. For these times it would be nice to be able to
use an outside program to send the email.

Below is a python script that does just that. Note that it will give deprecation warnings on later versions of Python so needs to be rewritten to used MIME in place of MimeWriter.

TODO: Fix indentation

Make the following changes to /usr/local/freeswitch/autoload_configs/switch.conf.xml:

Send_mail setting

To enable email setting for voicemail, make sure the following two lines are configured correctly in switch.conf.xml

'''Note''' - On CentOS and possibly other OSs, `sendmail` isn't in the non-root PATH so you'll want to specify the entire path in the mailer-app value or modify your PATH prior to running FreeSWITCH&trade;.

Exim4 settings

There have been several reports of segfaults with Exim4 in combination with Debian and FreeSWITCH - so far no definite resolution has been posted - mostly citing the advice below - which does not help(See [http://lists.freeswitch.org/pipermail/freeswitch-users/2009-June/043660.html here],[http://lists.freeswitch.org/pipermail/freeswitch-users/2010-January/052529.html here] and [http://jira.freeswitch.org/browse/FS-1923 here]).
A default installation of '''postfix''' instead of exim4 is a workaround, if you just quickly want to setup a mailer for FreeSWITCH on Debian --[[User:Peletiah|Peletiah]] 15:19, 1 June 2011 (UTC).

Using '''msmtp''' together with exim4 on the same host works and can be used as a workaround, see the notes below in a dedicated sub-section -- [[User:Miconda|miconda]] Sep 24, 2012.

As of April 22, 2013, a patch was applied to resolve the stack size setting for child processes, which is the primary cause of this issue. See [http://jira.freeswitch.org/browse/FS-5332 here] for details.

VM to email notification can also use other MTAs such as Debian's default Exim4. For email notification basically mod_voicemail constructs an email message that is then passed to standard input of the application defined in the "mailer-app" param found in switch.conf.xml.

The MTA application then needs to be configured in a way so that the recipients of the message are obtained from the To:, Cc:, and Bcc: header lines of the message passed to it. This is achieved in Exim4 with the -t option.

However, FS also adds another argument with the To: address to the command defined in the parameters above, so that the final command would look like:

If you have set:

This is because as documented in O'Reilly Sendmail's book, some versions of Sendmail add argument addresses to those obtained from the headers and also as a good measure to send the To: address to applications that cannot parse the headers in the email msg.

Exim's default behavior however is that these extra addresses specify addresses to which the message is NOT to be delivered. So in the command line described above "someone@someaddress.net" is the actual recipient of the email message, but exim's default behavior takes the argument from the command line and subtracts the "someone@someaddress.net" email address from the To: headers of the actual message, leaving it with no recipients at all.

Exim can be made to add the argument instead of subtracting it by setting the option extract_addresses_remove_arguments false in it's config and then you can use:

But if you do not want to go through the hassle of changing exim's configuration, then you could also overcome the "extra" argument using a script such as:

eximcompat.sh:


And then pointing the mailer app to this script:

If you're using the sysV init script from this wiki, the stack size is set to some low value (240) which can cause exim to segfault; add a line in your exim4compat.sh to increase this value (8192 works for me).

Using MSMTP for Local Relay to Exim4 on Debian

This is a possible workaround to make voicemail email notification work on Debian with Exim4 as main MTA.

MSMTP can be installed together with Exim4 on the same host and can be configured to do relay to local exim4 instance. In this way, Voicemail module can use MSMTP, but the public email relaying is taken care by Exim.

Installation of MSMTP on Debian is very simple:

Its configuration has to be stored in '''/etc/msmtprc'''. To relay to localhost SMTP server, just set its content to the next three lines:

 

By default, exim4 accepts messages from localhost without user authentication (to allow running processes to send email alerts), so you don't need to change anything in exim4 configuration (unless you disabled that default option).

On FreeSwitch configuration side, edit switch.conf.xml to set sending emails with MSMTP:

Windows settings

Example setting in switch.conf.xml for sending email on windows.


Mail via PHP

Example setting in switch.conf.xml for sending email with PHP mailer. Make sure the path to php is correct for mailer-app.

nullmailer settings

http://untroubled.org/nullmailer/ is installed sometimes as a sendmail service. Make sure the following two lines are configured correctly in switch.conf.xml

If you don't take out the ''-t'' default argument, nullmailer will create duplicate emails.

sSMTP settings

http://wiki.debian.org/sSMTP can be used as a null mailer and has the advantage over http://untroubled.org/nullmailer/ that it permits sending to mail hosts that require SSL/TLS and/or authentication. It also logs to /var/log/mail.log which is useful for debugging.

sSMTP uses the same sendmail command, ignoring some options and failing if others are specified. Within conf/autoload_configs//switch.conf.xml, you need to include:

Within /etc/ssmtp/ssmtp.conf, your mileage may vary, but to relay to a Postfix server using submission (tcp/587), the config looks like this:

Google will help you get a config that matches your configuration.

Debugging an external mailer

FreeSWITCH does very little error reporting on emails. Basically, once the email is
accepted for queueing, FreeSWITCH has (rightly) lost interest. So, it is best to first test that mails can be sent from your FreeSWITCH box before trying to get FreeSWITCH to do it.

First, create a minimal email in a text file:

Then send it from the command line with:

Nearly all mailers have a 'sendmail' alias even if they are not sendmail itself. Depending on the local mail server you are using, you may have to include the -t switch which extracts the To address(es) from the  message itself.

If this command fails, then you may not have sendmail, or a clone, installed. If you don't need the weight and features of sendmail, exim or postfix, leave them alone and use a simple null mailer like nullmailer or sSMTP as described above.

If the command works but the mail still does not reach the destination, then you know you have a mail transport issue and can solicit the assistance of your friendly postmaster or a forum appropriate to your operating system and mailer.

Once you are reliably sending email from the shell, transfer your settings into conf/autoload_configs/switch.conf.xml

For example, for sSMTP:

Note that if you need to run your mailer-app with no args, explicitly state them as <param name="mailer-app-args" value="" /> as the default if not specified is to use "-t".

With your external mailer known to be working, you can now narrow down your debugging to FreeSWITCH. Make sure that you include all the parameters required in the user directory entry. For example, in conf/directory/default/1001.xml:

Then, use fs_cli in /log 7 and leave a voicemail on a configured extension. After completing the voicemail, you should see something like this (both mailto and notify-mailto have been set in this case):

 

Example

Send Voice Mail to Email


The following is an example of sending a voicemail to email

Send Call To Voice Mail

The following is an example of sending a call to voicemail after you've decided that a user isn't available.

where '''default''' is the profile name (must be configured in voicemail.conf.xml), '''$${domain}''' is (obviously) the domain (in this case the system-wide domain setting for your switch from vars.xml) and '''$1''' is the dialed extension.

Check Voice Mail

The following is an example of checking vm (will prompt for PIN if ${voicemail_authorized} is not "true")

Please make sure the password is set in order for the mailbox to prompt for a password.

The following example will allow the user to check vm whether they're "voicemail_authorized" or not. If voicemail_authorized=true , then user can access voicemail without prompting for password. If it's set to false, then the system will ask to enter the password. I found that even if you don't put <auth> in the following example, it will still check if it is authed. Someone please verify.

To automatically pass all registered users on your domain without prompting to enter the password:

(Preliminary 2012.02.06) To speak the called party number before speaking the date of the voicemail message, enable channel variable vm_announce_cid. This only speaks the number, it does not preface it with introductory words such as "The caller's number is..." nor separate the number from the date that follows it.

Retrieve Voice Mail Via Web Interface

Configuration

To enable the web interface for voice mail, you must first install/enable mod_xml_rpc

You also need to enable the user or domain to use the web interface using #http-allowed-api

There are two different URLs for retrieving voice mail via a browser.
The following are functionally equivalent:

Enter the username and password in the challenge box. When authorized, the list of current voice mails will be displayed.<br/>
Note: use the actual IP address (or domain name) and not something like 127.0.0.1 or "localhost" because it won't work.<br/>
Domains are used in various circumstances. Here are some scenarios:

In this case you could do this:

http://your.domain.com:8080/api/voicemail/web

Log in with user and password and you are in

Alternatively, you could use the IP address:

http://1.2.3.4:8080/api/voicemail/web

Then login with user@your.domain.com and password

Finally, you could even do this:

http://1.2.3.4:8080/domains/your.domain.com/api/voicemail/web

And log in with just user and password (no @your.domain.com)

Retrieve Voice Mail Via IMAP Interface

This is not implemented yet.

See [[Bounty#IMAP integration of voicemail]]

Using voicemail to authenticate a caller's PIN

This example allows you to authenticate a user by requiring him/her to enter a PIN. If the user enters the correct PIN then dialplan processing continues. If not, then the system will play an error message and then disconnect the caller.

you can also set the "vm_auth_only" channel variable to true before calling the voicemail application, instead of using the auth_only arg

Configuration Parameters

file-extension

This is the extension which you want to use for the voicemail messages to be recorded. The default is wav but can be gsm, raw, ul, al, etc.

Key FS Mapping

[[mod_voicemail key map]]

callback-dialplan

callback-context

terminator-key

max-login-attempts

digit-timeout

max-record-len

tone-spec

play-new-messages-key

play-saved-messages-key

main-menu-key

config-menu-key

record-greeting-key

choose-greeting-key

record-name-key

record-file-key

listen-file-key

save-file-key

delete-file-key

undelete-file-key

email-key

pause-key

restart-key

ff-key

rew-key

odbc-dsn

This option allows you to override the default sqlite with an ODBC handle. You can use any valid DSN from your odbc.ini to store your voicemail configuration

record-silence-threshold

This parameter defines an 'energy level', it is a numeric value of how "quiet" the channel is.

See [[Misc. Dialplan Tools wait_for_silence#Description|DP Tool 'wait_for_silence']] for more info.

record-silence-hits

This parameter defines how many consecutive hits below record-silence-threshold it takes to end the recording.

See [[Misc. Dialplan Tools wait_for_silence#Description|DP Tool 'wait_for_silence']] for more info.

email-from

Setting this value will set the from address on the email sent

db-password-override

If db-password-override=true, the db password will only be used if present, if not present fallback to the xml config file vm-password. By default, both values in voicemail db and xml config file work.

dbname

If you want to have a non-standard location for the sqlite3 db, you can specify a different location for the profile.

allow-empty-password-auth

If allow-empty-password-auth=false, it will disable login via a authentication method if there is no password set in the user account (This wont affect voicemail_authorize=true login)

auto-playback-recordings

Database Schema

This will be automatically created by FreeSWITCH if it does not already exist.

Voicemail Message Settings
Voicemail User Preferences

API

vm_boxcount

vm_boxcount can be called from console, xml_rpc or any other interface that exposes FreeSWITCH API.

The function takes the following arguments:

[profile/]<user>@<domain>[|[new|saved|new-urgent|saved-urgent|all]]

and defaults to "new" voicemails and to the "default" voicemail profile.

Examples:

 

voicemail_inject

<user>@<domain>[@<profile>] <sound_file> [<cid_num>] [<cid_name>]

voicemail_inject is used to add an arbitrary sound file to a users voicemail mailbox.

vm_prefs

Syntax:
vm_prefs [profile/]<user>@<domain>[|[name_path|greeting_path|password]]
vm_prefs is used to check the preference changed by user
<br>
Example:
vm_prefs 1000@192.168.15.186|name_path|greeting_path|password
Output:

/etc/freeswitch.trunk/storage/voicemail/default/192.168.15.186/1000/greeting_1.wav:/etc/freeswitch.trunk/storage/voicemail/default/192.168.15.186/1000/recorded_name.wav:9999

Example:
vm_prefs 1000@192.168.15.186|greeting_path
Output:

/etc/freeswitch.trunk/storage/voicemail/default/192.168.15.186/1000/greeting_1.wav

vm_list

Syntax:
vm_list <id>@<domain>[/profile] [xml]
vm_list is used to get list of all the voicemails for the user

Example
vm_list 1000@192.168.15.186

1303500797:1303501043:1000:192.168.15.186:inbox:/etc/freeswitch.trunk/storage/voicemail/default/192.168.15.186/1000/msg_051dfd52-3318-4edc-b2ac-ba4d66dd55da.wav:051dfd52-3318-4edc-b2ac-ba4d66dd55da:Extension 1001:1001

Example
vm_list 1001@192.168.0.207 xml
<voicemail>
<message>
<created_epoch>1308582141</created_epoch>
<read_epoch>0</read_epoch>
<username>1001</username>
<domain>192.168.0.207</domain>
<folder>inbox</folder>
<path>/usr/share/freeswitch/storage/192.168.0.207/1001/msg_ae850faa-1661-4245-a551-3a8c5154fe1b.wav</path>
<uuid>ae850faa-1661-4245-a551-3a8c5154fe1b</uuid>
<cid-name>TheCaller</cid-name>
<cid-number>1001</cid-number>
<message-len>28</message-len>
</message>
</voicemail>

vm_delete

Syntax:
vm_delete <id>@<domain>[/profile] [<uuid>]

vm_read

Syntax:
vm_read <id>@<domain>[/profile] <read|unread> [<uuid>]

=Advanced API=
This advanced API was introduced in Apr 2011. It provides for configuring voicemail as well as the retrieval of voicemail related information. Using this api avoids needing to access voicemail_defaults.db directly. It was created for use with [[Mod_voicemail_ivr]], and was as well used in some GUI implementations.

This is also the base reference API for future [[Mod_voicemail_ivr]] improvement.

vm_fsdb_pref_password_set

Syntax
vm_fsdb_pref_password_set <profile> <domain> <userid> <new-password>
Sets the mailbox password

vm_fsdb_pref_greeting_set

Syntax
vm_fsdb_pref_greeting_set <profile> <domain> <userid> <slot> [file-path]
Sets the file in file_path as the current greeting in voicemail_prefs table (voicemail_defaults.db)

<need to determine the slot parameter action>

The voicemail_prefs table is updated to reflect the currently active greeting

Returns -ERR if the file is not present

vm_fsdb_pref_recname_set

Syntax
vm_fsdb_pref_recname_set <profile> <domain> <user> <file-path>
Sets or updates (if there is already a name file path) the file in file-path as the current name recording in voicemail_prefs

returns -ERR if the file is not present

vm_fsdb_msg_list

Syntax
vm_fsdb_msg_list <format> <profile> <domain> <user> <folder> <filter>
<format> is ignored but must be present
<folder> For future implementation
<filter> If none specified, then all messages are returned. Support the following filter :
* not-read
* new
* save
Example:
freeswitch@default> vm_fsdb_msg_list 0 default mydomain.com 1000 new ASC


Returns the list of unread messages for the user@domain for Inbox in JSON format

This function returns only New messages so it is not a full replacement for vm_list

vm_fsdb_msg_email

Syntax
vm_fsdb_msg_list <profile> <domain> <user> <uuid> <email address>
Example:
freeswitch@default> vm_fsdb_msg_email default mydomain.com 1000 1dfdc31c-7615-4e54-bfbc-dadacc3e5807 me@myemail.com

vm_fsdb_msg_purge

Syntax
vm_fsdb_msg_purge <profile> <domain> <user>
This function purges voicemails marked as Delete for the user@domain

Returns -OK or -ERR (if missing a parameter or profile not found)

vm_fsdb_msg_delete

Syntax
vm_fsdb_msg_delete <profile> <domain> <user> <uuid>
Deletes the message specified by uuid for user@domain

returns -OK or -ERR (if missing parameter or profile not found)

vm_fsdb_msg_save

Syntax
vm_fsdb_msg_save <profile> <domain> <user> <uuid>
Marks the file specified by uuid for user@domain to 'save'

Returns -OK or -ERR if missing a parameter or profile not found

vm_fsdb_msg_undelete

Syntax
vm_fsdb_msg_undelete <profile> <domain> <user> <uuid>
Clears the flags field (regardless of whether it was 'delete' or not)

Returns -OK or -ERR if missing a paramter or profile is not found

vm_fsdb_auth_login

Syntax
vm_fsdb_auth_login <profile> <domain> <user> <password>
password is assumed to be 64 chars or less

Seems to verify that the password in voicemail_prefs is same as in xml?????

Returns -OK or -ERR if:
#missing parameters or profile not found
#password in voicemail_prefs doesn't match password passed in call
#password in xml does not match password passed in call
#"Login Denied" if vm is disabled
If a password exists in voicemail_prefs, it is used in preference to xml

vm_fsdb_msg_get

Syntax
vm_fsdb_msg_get <format> <profile> <domain> <user> <uuid>
<format> is ignored but must be present

Returns a JSON formatted list detailing the VM
or -ERR if missing parameters or profile is not found

Assumes that the uuid can exist in more than 1 row of voicemail_msgs

vm_fsdb_msg_count

Syntax
vm_fsdb_msg_count <format> <profile> <domain> <user> <folder>
Returns a count of the number of read and unread VM's in the Inbox folder for this user@domain

Counts are returned in JSON format for
VM-Total-New-Messages
VM-Total-New-Urgent-Messages
VM-Total-Saved-Messages
VM-Total-Saved-Urgent-Messages
(VM's in other folders are not counted but includes VM's marked as delete or save)

Returns -ERR if missing a parameter or if profile is not found

FAQ

How do I reload new configuration without restarting FreeSWITCH?

If you happened to change settings in autoload_configs/voicemail.conf.xml and would like to make it effective without restarting FreeSWITCH, enter the following command in console mode in sequence:

reloadxml
reload mod_voicemail

Do I need a text-to-speech engine installed?

No, it will work with sound files or a text-to-speech engine.

How do I install sound files?

make sounds-install

Voicemail Voice Prompt / Troubleshooting Problems


Unfortunately mod_voicemail does not have a great ability to be debugged, even with logging turned up tracking down errors can be tricky and an incorrect config upgrade can leave you without working voicemail. Make sure that dialed_extension is SET and exported (you can use the info app to verify) as if this variable is not set voicemail will most likely not be working for you.

If you encounter a problem where the voice mail prompts are either missing, or fail to play with this error on the console:


switch_ivr_phrase_macro() Macro [voicemail_config_menu] did not match any patterns

or

Can't find macro

This is caused by a missing voicemail prompt sound file or invalid conf/lang files.
You will need to perform the corrective command below in the FreeSWITCH source directory:


make vm-sync

After you run the make vm-sync, you'll need to do a reloadxml at the FreeSWITCH console, or restart FreeSWITCH. If the error is in certain xml files then this may not fix it, try to temporarily replace your conf/lang folder with that from trunk (or the base install).

If you've installed french sound files, you have to do the following:
* rename `conf/lang/fr/ca/vm/sounds.xml` to `conf/lang/fr/ca/vm/tts.xml` 
* copy `conf/lang/en/us/vm/sounds.xml` to `conf/lang/fr/ca/vm/sounds.xml` 

How to update keys for accessing voicemail from outside?


You need to edit the /<path to freeswitch>/conf/autoload_configs/voicemail.conf.xml file.

<param name="login-keys" value="0"/>
-Key to prompt the voicemail's password
<param name="vmain-key" value="*"/>
-Key to prompt the voicemail's UserID
<br><br>
The login-keys param is the key to prompt the password, while the vmain-key is the key to prompt the UserID.

How can I disable remote login/access to voicemail?

Set the following two params in autoload_configs/voicemail.conf.xml:

<param name="vmain-key" value="a"/>
<param name="login-keys" value="a"/>

Can I share voicemail boxes between multiple phones/users?

To Monitor Voicemail


There are 2 ways to do this, the correct way would be to use the subscribe feature of your phone to monitor a particular mailbox

1. SUBSCRIBE feature method


: The phones in question all need to support using SUBSCRIBE to monitor their mailbox.<br/>
: Phones that use other methods (ie. gratuitous/parasitic "NOTIFY" style) will not work.<br/>
: Other concerns you may face include: whether you can configure the extension dialed when you press the 'retrieve' button.<br/>
: This configuration tested successfully on two SNOM 320 handsets, but fails on the Cisco 7960 because it does not use SUBSCRIBE.<br/>

SNOM 320 configuration

This configuration tested with firmware 7.1.30 and newer.<br/>
* Under 'Identity-->Login', set Mailbox to the shared box number.

2. Force MWI Info in Sofia


: To populate the param MWI-Account of the directory user (or domain) with user@domain of the voicemail you want to monitor.
: This will force sofia to send the MWI info for that mailbox even if you registred for another phone. This method only allow you to monitor mailbox

<param name="MWI-Account" value="1000@$${domain}"/>

To Receive Voicemail

''receiving voicemail into the shared mailbox (e.g. when no answer)''

In each user's directory entry, add a variable named 'mailbox' that looks like this:

<variable name="mailbox" value="1500"/>

This sets the stage for which mailbox they're actually going to use, shared or not.. it is used ONLY in the dialplan.
Change your dialplan to reflect this:

The old entry:

<action application="voicemail" data="default ${domain_name} ${dialed_extension}"/>

The new entry:

<action application="voicemail" data="default ${domain_name} ${user_data(${dialed_extension}@${domain_name} var mailbox)}"/>

Voicemail Callback

''calling back a caller while checking voicemail''

When a user is listening to voicemail messages - they are able to dial '5' and be connected to the caller of that voicemail.

You are able to control the dial plan execution of this callback method by modifying the vm_callback.xml file located under BASE_FREESWITCH_DIR/conf/dialplan

An example vm_callback.xml is as follows:

 

Transcribing Voicemail

There's no real simple way to do this as of now with mod_voicemail.

If you use Fusionpbx's mailer for FS, then you can intercept the wav file mid-mailing and send it to some sort of API.

NOTE: "Transcription" is the full text, where as IVR speech recognition is to recognize audio vs a specific list of options, "grammar". These are very different things.

The available APIs for some sort of transcription are:

  • twilio - 5cents/minute
  • voicecloud - 10cents/minute. They seem to have a $250/month minumum.
  • tropo - 3 cents/minute I think (60 second billing) BUT they need to record the file, on their system. They have all-SIP plans with alternate billing.
  • quicktate - $0.0175/word, volume at 1.10cents/word. Avg of 160 words per minute = $2.80/minute.
  • mycaption - 9c/minute for purely machine-based.
  • mycaption - 43c/minute upto 55c/minute - 15 second increments -premium that combines machine-based speech recognition with error correction by human editors.
  • Google speech API - free, but it's not that great as of right now. Some info on how to access it here.

Here is a script you can use for tinkering with Google Speech API:

Google Speech API

 

 

Example:

./googlevoice.sh /usr/local/freeswitch/sounds/en/us/callie/ivr/8000/ivr-one_more_mistake.wav 
1 SoX Sound Exchange - Convert WAV to FLAC with 16000
2 Submit to Google Voice Recognition
3 SED Extract recognized text
4 Remove Temporary Files
5 Show Text 
that's odd 1 more mistake and I will hang up on your ass

It should be "that's it" instead of "that's odd" but otherwise Google actually got it right. Try other sound prompts.