1 page.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) brought an implementation of visual voicemail (VVM) 28 support integrated into the Dialer, allowing compatible Carrier VVM services to 29 hook into the Dialer with minimal configuration. Visual voicemail lets users 30 easily check voicemail without making any phone calls. Users can view a list of 31 messages in an inbox-like interface, listen to them in any order, and can 32 delete them as desired.</p> 33 34 <p>Android 7.0 added the following configuration parameters to visual voicemail: 35 <ul> 36 <li>Prefetching of voicemails controlled by <code>KEY_VVM_PREFETCH_BOOLEAN</code> 37 <li>Control of whether a cellular data connection is required by 38 <code>KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN</code> 39 <li>Fetching of voicemail transcriptions 40 <li>Fetching of voicemail quota 41 </ul> 42 43 <p>This article gives an overview of what is provided, how carriers can integrate 44 with it, and some details of the implementation.</p> 45 46 <h2 id=visual_voicemail_vvm_client>Visual voicemail (VVM) client</h2> 47 48 <p>Android 6.0 and above includes a OMTP VVM client, which (when provided with the correct 49 configuration) will connect to Carrier VVM servers and populate visual 50 voicemail messages within the Android Open Source Project (AOSP) Dialer. The VVM client:</p> 51 52 <ul> 53 <li>Handles the SMS messages used to activate/deactivate/query status of the 54 service and the SMS messages used to notify the device of events in the 55 subscriber's mailbox 56 <li>Syncs the mailbox with the IMAP server 57 <li>Downloads the voicemails when the user chooses to listen to them 58 <li>Fetches voicemail transcriptions 59 <li>Fetches details of voicemail quota (total mailbox size and occupied size) 60 <li>Integrates into the Dialer for user functionality such as calling back, viewing 61 unread messages, deleting messages, etc. 62 </ul> 63 64 <h2 id=integrate_with_the_vvm_client>Integrate with the VVM client</h2> 65 66 <h3 id=implementation>Implementation</h3> 67 68 <p>The Carrier must provide a visual voicemail server implementing the 69 <a href="http://www.gsma.com/newsroom/wp-content/uploads/2012/07/OMTP_VVM_Specification_1_3.pdf">OMTP 70 VVM specifications</a>. The current implementation of the AOSP VVM client supports the core 71 features (read/delete voicemails, download/sync/listen) but the additional TUI 72 features (password change, voicemail greeting, languages) are not implemented. 73 At this time, we only support OMTP version 1.1 and do not use encryption for 74 IMAP authentication.</p> 75 76 <p>To support transcriptions, carriers must support the transcription attachment 77 format (MIME type plain/text) specified in the OMTP 1.3 spec, item 2.1.3.</p> 78 79 <p class="note"><strong>Note</strong>: Server-originated SMS messages to the device 80 (e.g. STATUS or SYNC) must be data SMS messages.</p> 81 82 <h3 id=configuration>Configuration</h3> 83 84 <p>In order for a carrier to integrate with the VVM service, the carrier must 85 provide configuration details to the platform that the OMTP client can use. 86 These parameters are:</p> 87 88 <ul> 89 <li>Destination number and port number for SMS 90 <li>The package name of the carrier-provided visual voicemail app (if one is 91 provided), so that the platform implementation can be disabled if that package 92 is installed 93 </ul> 94 95 <p>These values are provided through the 96 <a href="https://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier Config API</a>. 97 This functionality, launched in Android 6.0, allows an application to 98 dynamically provide telephony-related configuration to the various platform 99 components that need it. In particular the following keys must have values 100 defined:</p> 101 102 <ul> 103 <li><code>KEY_VVM_DESTINATION_NUMBER_STRING</code> 104 <li><code>KEY_VVM_PORT_NUMBER_INT</code> 105 <li><code>KEY_VVM_TYPE_STRING</code> 106 <li><code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> 107 <li><code>KEY_VVM_PREFETCH_BOOLEAN</code> 108 <li><code>KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN</code> 109 </ul> 110 111 <p>Please see the <a href="{@docRoot}devices/tech/config/carrier.html">Carrier Configuration</a> 112 article for more detail.</p> 113 114 <h2 id=implementation>Implementation</h2> 115 116 <p>The OMTP VVM client is implemented within <code>packages/services/Telephony</code>, 117 in particular within <code>src/com/android/phone/vvm/</code></p> 118 119 <h3 id=setup>Setup</h3> 120 121 <ol> 122 <li>The VVM client listens for <code>TelephonyIntents#ACTION_SIM_STATE_CHANGED</code> 123 or <code>CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED</code>. 124 <li>When a SIM is added that has the right Carrier Config values 125 (<code>KEY_VVM_TYPE_STRING</code> set to <code>TelephonyManager.VVM_TYPE_OMTP</code> 126 or <code>TelephonyManager.VVM_TYPE_CVVM</code>), the VVM client sends an 127 ACTIVATE SMS to the value specified in <code>KEY_VVM_DESTINATION_NUMBER_STRING</code>. 128 <li>The server activates the visual voicemail service and sends the OMTP 129 credentials via STATUS sms. When the VVM client receives the STATUS sms, it 130 registers the voicemail source and displays the voicemail tab on the device. 131 <li>The OMTP credentials are saved locally and the device begins a full sync, as 132 described below. 133 </ol> 134 135 <h3 id=syncing>Syncing</h3> 136 137 <p>There are a variety of ways that the VVM client can sync with the carrier 138 server and vice versa.</p> 139 140 <ul> 141 <li><strong>Full syncs</strong> occur upon initial download. The VVM client 142 fetches voicemail metadata like date and time; origin number; duration; 143 voicemail transcriptions, if available; and audio data if 144 <code>KEY_VVM_PREFETCH_BOOLEAN</code> is True. Full syncs can be 145 triggered by: 146 <ul> 147 <li>Inserting a new SIM 148 <li>Rebooting the device 149 <li>Coming back in service 150 <li>Receiving the <code>VoicemailContract.ACTION_SYNC_VOICEMAIL</code> broadcast 151 </ul> 152 <li><strong>Upload sync</strong> happens when a user interacts with a voicemail 153 to read or delete it. Upload syncs result in the server changing its data to 154 match the data on the device. For example, if the user reads a voicemail, 155 it's marked as read on the server; if a user deletes a voicemail, it's 156 deleted on the server. 157 <li><strong>Download sync</strong> occurs when the VVM client receives a "MBU" 158 (mailbox update) SYNC sms from the carrier. A SYNC message contains the 159 metadata for a new message so that it can be stored in the voicemail 160 content provider. 161 </ul> 162 163 <p class="note"><strong>Note</strong>: The voicemail inbox quota values are 164 retrieved during every sync.</p> 165 166 <h3 id=voicemail_download>Voicemail download</h3> 167 168 <p>When a user presses play to listen to a voicemail, the corresponding audio file 169 is downloaded. If the user chooses to listen to the voicemail, the Dialer can 170 broadcast <code>VoicemailContract.ACTION_FETCH_VOICEMAIL</code>, which the 171 voicemail client will receive, initiate the download of the 172 content, and update the record in the platform voicemail content provider.</p> 173 174 <h3 id=disabling_vvm>Disabling VVM</h3> 175 176 <p>The VVM service can be disabled or deactivated by user interaction, removal of 177 a valid SIM, or replacement by a carrier VVM app. <em>Disabled</em> means that the 178 local device no longer displays visual voicemail. <em>Deactivated</em> means that 179 the service is turned off for the subscriber. User interaction can 180 deactivate the service, SIM removal temporarily disables the service because 181 it's no longer present, and carrier VVM replacement disables the AOSP VVM client.</p> 182 183 <h4 id=user_interaction>User interaction</h4> 184 185 <p>The user may manually enable or disable visual voicemail. If a user disables 186 visual voicemail, they are also deactivating their service. When they disable 187 visual voicemail, a DEACTIVATE sms is sent, the voicemail source is 188 unregistered locally, and voicemail tab disappears. If they re-enable visual 189 voicemail, their service is reactivated as well.</p> 190 191 <h4 id=sim_removal>SIM removal</h4> 192 193 <p>If there are changes to the device's SIM state (<code>ACTION_SIM_STATE_CHANGED</code>) 194 or Carrier Config values (<code>ACTION_CARRIER_CONFIG_CHANGED</code>), and 195 a valid configuration for the given SIM no longer exists, then the 196 voicemail source is unregistered locally and the voicemail tab disappears. If 197 the SIM is replaced, VVM will be re-enabled.</p> 198 199 <h4 id=replaced_by_carrier_vvm>Replaced by carrier VVM</h4> 200 201 <p>A carrier visual voicemail app, if installed on the device, can disable the 202 AOSP VVM client. This is achieved by checking if a package with a name 203 matching the <code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> parameter is installed.</p> 204 205 <p>The VVM client can still be enabled through user interaction.</p> 206 207 <h2 id=testing>Testing</h2> 208 209 <p>There is an existing (since Android 4.0) set of CTS tests for the 210 VoicemailProvider APIs that allow an app to insert/query/delete voicemails into 211 the platform. These are the same APIs that VVM uses to add/delete voicemails so 212 that any Dialer app can display them in the UI.</p> 213 214 <p>To test your configuration application is passing the OMTP configuration 215 correctly you can test your code with:</p> 216 217 <ul> 218 <li>A SIM containing a valid certificate signature 219 <li>A device running Android 6.0 with an unmodified version of the AOSP phone framework 220 </ul> 221
