Visual voicemail

Android 6.0 (Marshmallow) brought 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.

Android 7.0 added the following configuration parameters to visual voicemail:

  • Prefetching of voicemails controlled by KEY_VVM_PREFETCH_BOOLEAN
  • Control of whether a cellular data connection is required by KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN
  • Fetching of voicemail transcriptions
  • Fetching of voicemail quota

This page 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 and above includes a OMTP VVM client, which (when provided with the correct configuration) connects to carrier VVM servers and populates VVM messages within the Android Open Source Project (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
  • Fetches voicemail transcriptions
  • Fetches details of voicemail quota (total mailbox size and occupied size)
  • 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 AOSP 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.

To support transcriptions, carriers must support the transcription attachment format (MIME type plain/text) specified in the OMTP 1.3 spec, item 2.1.3.

Note: Server-originated SMS messages to the device (e.g. STATUS or SYNC) must be data SMS 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
  • 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, lets an app 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
  • KEY_VVM_PREFETCH_BOOLEAN
  • KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN

See Carrier configuration for details.

Implementation

The OMTP VVM client is implemented within packages/services/Telephony, in particular within src/com/android/phone/vvm/

Setup

  1. The VVM client listens for TelephonyIntents#ACTION_SIM_STATE_CHANGED or CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED.
  2. 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.
  3. The server activates the visual voicemail service and sends the OMTP credentials through STATUS SMA. When the VVM client receives the STATUS SMS, it registers the voicemail source and displays the voicemail tab on the device.
  4. 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 fetches voicemail metadata like date and time; origin number; duration; voicemail transcriptions, if available; and audio data if KEY_VVM_PREFETCH_BOOLEAN is True. Full syncs can be triggered by:
    • Inserting a new SIM
    • Rebooting the device
    • Coming back in service
    • Receiving the VoicemailContract.ACTION_SYNC_VOICEMAIL broadcast
  • 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.

Note: The voicemail inbox quota values are retrieved during every sync.

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 receives, initiate the download of the content, and update the record in the platform voicemail content provider.

Disable 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 AOSP VVM client.

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 is re-enabled.

Replaced by carrier VVM

A carrier visual voicemail app, if installed on the device, can disable the AOSP VVM client. 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 app 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