Visual Voicemail

page.title=Visual Voicemail
@jd:body

In this document

Android 6.0 (Marshmallow) brings an implementation of Visual Voicemail (VVM)
support integrated into the Dialer, allowing compatible Carrier VVM services to
hook into the Dialer with minimal configuration. Visual voicemail lets users
easily check voicemail without making any phone calls. Users can view a list of
messages in an inbox-like interface, listen to them in any order, and can
delete them as desired.

This article gives an overview of what is provided, how carriers can integrate
with it, and some details of the implementation.

Visual Voicemail (VVM) client

Android 6.0 includes a OMTP VVM client, which (when provided with the correct
configuration) will connect to Carrier VVM servers and populate Visual
Voicemail messages within the AOSP Dialer. The VVM client:

Handles the SMS messages used to activate/deactivate/query status of the
service and the SMS messages used to notify the device of events in the
subscriber’s mailbox

Syncs the mailbox with the IMAP server

Downloads the voicemails when the user chooses to listen to them

Integrates into the Dialer for user functionality such as calling back, viewing
unread messages, deleting messages, etc.

Integrate with the VVM client

Implementation

The Carrier must provide a Visual Voicemail server implementing the OMTP VVM specifications. The current implementation of the Google VVM client supports the core
features (read/delete voicemails, download/sync/listen) but the additional TUI
features (password change, voicemail greeting, languages) are not implemented.
At this time, we only support OMTP version 1.1 and do not use encryption for
IMAP authentication.

Note that server-originated SMS messages to the device (e.g. STATUS or SYNC) must
not be class 0 messages.

Configuration

In order for a carrier to integrate with the VVM service, the carrier must
provide configuration details to the platform that the OMTP client can use.
These parameters are:

Destination number and port number for SMS

Authentication security type for IMAP (SSL, TLS, none, etc.)

The package name of the carrier-provided Visual Voicemail app (if one is
provided), so that the platform implementation can be disabled if that package
is installed

These values are provided through the Carrier Config API. This functionality, launched in Android 6.0, allows an application to
dynamically provide telephony-related configuration to the various platform
components that need it. In particular the following keys must have values
defined:

KEY_VVM_DESTINATION_NUMBER_STRING

KEY_VVM_PORT_NUMBER_INT

KEY_VVM_TYPE_STRING

KEY_CARRIER_VVM_PACKAGE_NAME_STRING

Please see the Carrier Configuration article for more detail.

Implementation

The OMTP VVM client is implemented within

packages/services/Telephony

, in particular within

src/com/android/phone/vvm/

Setup

The VVM client listens for

TelephonyIntents#ACTION_SIM_STATE_CHANGED

or

CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED

.

When a SIM is added that has the right Carrier Config values (

KEY_VVM_TYPE_STRING

set to

TelephonyManager.VVM_TYPE_OMTP

or

TelephonyManager.VVM_TYPE_CVVM

), the VVM client sends an ACTIVATE SMS to the value specified in

KEY_VVM_DESTINATION_NUMBER_STRING

.

The server activates the visual voicemail service and sends the OMTP
credentials via STATUS sms. When the VVM client receives the STATUS sms, it
registers the voicemail source and displays the voicemail tab on the device.

The OMTP credentials are saved locally and the device begins a full sync, as
described below.

Syncing

There are a variety of ways that the VVM client can sync with the carrier
server and vice versa.

Full syncs occur upon initial download. The VVM client only fetches voicemail metadata
like date and time, origin number, duration, etc. Full syncs can be triggered
by a:

new SIM

device reboot

device coming back in service

Upload sync happens when a user interacts with a voicemail to read or delete it. Upload
syncs result in the server changing its data to match the data on the device.
For example, if the user reads a voicemail, it’s marked as read on the server;
if a user deletes a voicemail, it’s deleted on the server.

Download sync occurs when the VVM client receives a “MBU” (mailbox update) SYNC sms from the
carrier. A SYNC message contains the metadata for a new message so that it can
be stored in the voicemail content provider.

Voicemail Download

When a user presses play to listen to a voicemail, the corresponding audio file
is downloaded. If the user chooses to listen to the Voicemail, the Dialer can
broadcast

VoicemailContract.ACTION_FETCH_VOICEMAIL

, which the voicemail client will receive, initiate the download of the
content, and update the record in the platform Voicemail content provider.

Disabling VVM

The VVM service can be disabled or deactivated by user interaction, removal of
a valid SIM, or replacement by a carrier VVM app. Disabled means that the local device no longer displays visual voicemail. Deactivated means that the service is turned off for the subscriber. User interaction can
deactivate the service, SIM removal temporarily disables the service because
it’s no longer present, and carrier VVM replacement disables the Google
component of visual voicemail.

User interaction

The user may manually enable or disable visual voicemail. If a user disables
visual voicemail, they are also deactivating their service. When they disable
visual voicemail, a DEACTIVATE sms is sent, the voicemail source is
unregistered locally, and voicemail tab disappears. If they re-enable visual
voicemail, their service is reactivated as well.

SIM removal

If there are changes to the device’s SIM state (

ACTION_SIM_STATE_CHANGED

) or Carrier Config values (

ACTION_CARRIER_CONFIG_CHANGED

), and a valid configuration for the given SIM no longer exists, then the
voicemail source is unregistered locally and the voicemail tab disappears. If
the SIM is replaced, VVM will be re-enabled.

Replaced by carrier VVM

If the device or the user installs a corresponding carrier visual voicemail app
and the carrier has opted to disable Google visual voicemail if the carrier
equivalent is installed, then the Google visual voicemail client will be
automatically disabled. This is achieved by checking if a package with a name
matching the

KEY_CARRIER_VVM_PACKAGE_NAME_STRING

parameter is installed.

The VVM client can still be enabled through user interaction.

Testing

There is an existing (since Android 4.0) set of CTS tests for the
VoicemailProvider APIs that allow an app to insert/query/delete voicemails into
the platform. These are the same APIs that VVM uses to add/delete voicemails so
that any Dialer app can display them in the UI.

To test your configuration application is passing the OMTP configuration
correctly you can test your code with:

A SIM containing a valid certificate signature

A device running Android 6.0 with an unmodified version of the AOSP phone framework