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) brought 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>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
44with 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
49configuration) will connect to Carrier VVM servers and populate visual
50voicemail 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
54service and the SMS messages used to notify the device of events in the
55subscriber'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
61unread 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
70VVM specifications</a>. The current implementation of the AOSP VVM client supports the core
71features (read/delete voicemails, download/sync/listen) but the additional TUI
72features (password change, voicemail greeting, languages) are not implemented.
73At this time, we only support OMTP version 1.1 and do not use encryption for
74IMAP authentication.</p>
75
76<p>To support transcriptions, carriers must support the transcription attachment
77format (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
85provide configuration details to the platform that the OMTP client can use.
86These 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
91provided), so that the platform implementation can be disabled if that package
92is 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>.
97This functionality, launched in Android 6.0, allows an application to
98dynamically provide telephony-related configuration to the various platform
99components that need it. In particular the following keys must have values
100defined:</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>
112article 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>,
117in 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
138server 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
164retrieved 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
169is downloaded. If the user chooses to listen to the voicemail, the Dialer can
170broadcast <code>VoicemailContract.ACTION_FETCH_VOICEMAIL</code>, which the
171voicemail client will receive, initiate the download of the
172content, 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
177a valid SIM, or replacement by a carrier VVM app. <em>Disabled</em> means that the
178local device no longer displays visual voicemail. <em>Deactivated</em> means that
179the service is turned off for the subscriber. User interaction can
180deactivate the service, SIM removal temporarily disables the service because
181it'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
186visual voicemail, they are also deactivating their service. When they disable
187visual voicemail, a DEACTIVATE sms is sent, the voicemail source is
188unregistered locally, and voicemail tab disappears. If they re-enable visual
189voicemail, 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>)
194or Carrier Config values (<code>ACTION_CARRIER_CONFIG_CHANGED</code>), and
195a valid configuration for the given SIM no longer exists, then the
196voicemail source is unregistered locally and the voicemail tab disappears. If
197the 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
202AOSP VVM client. This is achieved by checking if a package with a name
203matching 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
210VoicemailProvider APIs that allow an app to insert/query/delete voicemails into
211the platform. These are the same APIs that VVM uses to add/delete voicemails so
212that any Dialer app can display them in the UI.</p>
213
214<p>To test your configuration application is passing the OMTP configuration
215correctly 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