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