1page.title=Visual Voicemail 2@jd:body 3 4<!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18--> 19<div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25</div> 26 27<p>Android 6.0 (Marshmallow) brings an implementation of visual voicemail (VVM) 28support integrated into the Dialer, allowing compatible Carrier VVM services to 29hook into the Dialer with minimal configuration. Visual voicemail lets users 30easily check voicemail without making any phone calls. Users can view a list of 31messages in an inbox-like interface, listen to them in any order, and can 32delete them as desired.</p> 33 34<p>This article gives an overview of what is provided, how carriers can integrate 35with it, and some details of the implementation.</p> 36 37<h2 id=visual_voicemail_vvm_client>Visual voicemail (VVM) client</h2> 38 39<p>Android 6.0 includes a OMTP VVM client, which (when provided with the correct 40configuration) will connect to Carrier VVM servers and populate visual 41voicemail messages within the Android Open Source Project (AOSP) Dialer. The VVM client:</p> 42 43<ul> 44 <li>Handles the SMS messages used to activate/deactivate/query status of the 45service and the SMS messages used to notify the device of events in the 46subscriber's mailbox 47 <li>Syncs the mailbox with the IMAP server 48 <li>Downloads the voicemails when the user chooses to listen to them 49 <li>Integrates into the Dialer for user functionality such as calling back, viewing 50unread messages, deleting messages, etc. 51</ul> 52 53<h2 id=integrate_with_the_vvm_client>Integrate with the VVM client</h2> 54 55<h3 id=implementation>Implementation</h3> 56 57<p>The Carrier must provide a visual voicemail server implementing the <a href="http://www.gsma.com/newsroom/wp-content/uploads/2012/07/OMTP_VVM_Specification_1_3.pdf">OMTP VVM specifications</a>. The current implementation of the AOSP VVM client supports the core 58features (read/delete voicemails, download/sync/listen) but the additional TUI 59features (password change, voicemail greeting, languages) are not implemented. 60At this time, we only support OMTP version 1.1 and do not use encryption for 61IMAP authentication. </p> 62 63<p><strong>Note</strong> that server-originated SMS messages to the device (e.g. STATUS or SYNC) must 64not be class 0 messages.</p> 65 66<h3 id=configuration>Configuration</h3> 67 68<p>In order for a carrier to integrate with the VVM service, the carrier must 69provide configuration details to the platform that the OMTP client can use. 70These parameters are:</p> 71 72<ul> 73 <li>Destination number and port number for SMS 74 <li>Authentication security type for IMAP (SSL, TLS, none, etc.) 75 <li>The package name of the carrier-provided visual voicemail app (if one is 76provided), so that the platform implementation can be disabled if that package 77is installed 78</ul> 79 80<p>These values are provided through the <a href="https://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier Config API</a>. This functionality, launched in Android 6.0, allows an application to 81dynamically provide telephony-related configuration to the various platform 82components that need it. In particular the following keys must have values 83defined:</p> 84 85<ul> 86 <li><code>KEY_VVM_DESTINATION_NUMBER_STRING</code> 87 <li><code>KEY_VVM_PORT_NUMBER_INT</code> 88 <li><code>KEY_VVM_TYPE_STRING</code> 89 <li><code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> 90</ul> 91 92<p>Please see the <a href="{@docRoot}devices/tech/config/carrier.html">Carrier Configuration</a> article for more detail.</p> 93 94<h2 id=implementation>Implementation</h2> 95 96<p>The OMTP VVM client is implemented within <code>packages/services/Telephony</code>, in particular within <code>src/com/android/phone/vvm/</code></p> 97 98<h3 id=setup>Setup</h3> 99 100<ol> 101 <li>The VVM client listens for <code>TelephonyIntents#ACTION_SIM_STATE_CHANGED</code> or <code>CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED</code>. 102 <li>When a SIM is added that has the right Carrier Config values (<code>KEY_VVM_TYPE_STRING</code> set to <code>TelephonyManager.VVM_TYPE_OMTP</code> or <code>TelephonyManager.VVM_TYPE_CVVM</code>), the VVM client sends an ACTIVATE SMS to the value specified in <code>KEY_VVM_DESTINATION_NUMBER_STRING</code>. 103 <li>The server activates the visual voicemail service and sends the OMTP 104credentials via STATUS sms. When the VVM client receives the STATUS sms, it 105registers the voicemail source and displays the voicemail tab on the device. 106 <li>The OMTP credentials are saved locally and the device begins a full sync, as 107described below. 108</ol> 109 110<h3 id=syncing>Syncing</h3> 111 112<p>There are a variety of ways that the VVM client can sync with the carrier 113server and vice versa.</p> 114 115<ul> 116 <li><strong>Full syncs</strong> occur upon initial download. The VVM client only fetches voicemail metadata 117like date and time, origin number, duration, etc. Full syncs can be triggered 118by a: 119 <ul> 120 <li>new SIM 121 <li>device reboot 122 <li>device coming back in service 123 </ul> 124 <li><strong>Upload sync</strong> happens when a user interacts with a voicemail to read or delete it. Upload 125syncs result in the server changing its data to match the data on the device. 126For example, if the user reads a voicemail, it's marked as read on the server; 127if a user deletes a voicemail, it's deleted on the server. 128 <li><strong>Download sync</strong> occurs when the VVM client receives a "MBU" (mailbox update) SYNC sms from the 129carrier. A SYNC message contains the metadata for a new message so that it can 130be stored in the voicemail content provider. 131</ul> 132 133<h3 id=voicemail_download>Voicemail download</h3> 134 135<p>When a user presses play to listen to a voicemail, the corresponding audio file 136is downloaded. If the user chooses to listen to the voicemail, the Dialer can 137broadcast <code>VoicemailContract.ACTION_FETCH_VOICEMAIL</code>, which the voicemail client will receive, initiate the download of the 138content, and update the record in the platform voicemail content provider.</p> 139 140<h3 id=disabling_vvm>Disabling VVM</h3> 141 142<p>The VVM service can be disabled or deactivated by user interaction, removal of 143a valid SIM, or replacement by a carrier VVM app. <em>Disabled</em> means that the local device no longer displays visual voicemail. <em>Deactivated</em> means that the service is turned off for the subscriber. User interaction can 144deactivate the service, SIM removal temporarily disables the service because 145it's no longer present, and carrier VVM replacement disables the AOSP VVM client.</p> 146 147<h4 id=user_interaction>User interaction</h4> 148 149<p>The user may manually enable or disable visual voicemail. If a user disables 150visual voicemail, they are also deactivating their service. When they disable 151visual voicemail, a DEACTIVATE sms is sent, the voicemail source is 152unregistered locally, and voicemail tab disappears. If they re-enable visual 153voicemail, their service is reactivated as well.</p> 154 155<h4 id=sim_removal>SIM removal</h4> 156 157<p>If there are changes to the device's SIM state (<code>ACTION_SIM_STATE_CHANGED</code>) or Carrier Config values (<code>ACTION_CARRIER_CONFIG_CHANGED</code>), and a valid configuration for the given SIM no longer exists, then the 158voicemail source is unregistered locally and the voicemail tab disappears. If 159the SIM is replaced, VVM will be re-enabled.</p> 160 161<h4 id=replaced_by_carrier_vvm>Replaced by carrier VVM</h4> 162 163<p>A carrier visual voicemail app, if installed on the device, can disable the 164AOSP VVM client. This is achieved by checking if a package with a name 165matching the <code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> parameter is installed.</p> 166 167<p>The VVM client can still be enabled through user interaction.</p> 168 169<h2 id=testing>Testing</h2> 170 171<p>There is an existing (since Android 4.0) set of CTS tests for the 172VoicemailProvider APIs that allow an app to insert/query/delete voicemails into 173the platform. These are the same APIs that VVM uses to add/delete voicemails so 174that any Dialer app can display them in the UI.</p> 175 176<p>To test your configuration application is passing the OMTP configuration 177correctly you can test your code with:</p> 178 179<ul> 180 <li>A SIM containing a valid certificate signature 181 <li>A device running Android 6.0 with an unmodified version of the AOSP phone framework 182</ul> 183