BlackBerry Mobile Voice System APIs – Handling Multiple Phone Numbers in OS 5.0

How-to

So you’ve landed yourself a sweet deal with a carrier and your BlackBerry® smartphone application is going to be sold and billed through them.  Congratulations!  Now it’s time for you to keep the carrier happy.  How do you do that?  Increase their revenues and minimize their expenses.  If you’ve got a good app, the revenue part is easy.  The expenses part is a little trickier – it could mean that your app is bandwidth friendly; it could mean that you as an app developer are extremely self-proficient; or it could also mean that your app is rock solid and generates very few support calls.

In most cases when a carrier partnership agreement is achieved, the billing and/or authentication is done using the cell phone number of the BlackBerry smartphone.  Traditionally, this requirement meant that you’d call Phone.getDevicePhoneNumber(boolean format) to retrieve the user’s BlackBerry smartphone cell number.  However, if the user is using BlackBerry® Mobile Voice System (BlackBerry MVS), getDevicePhoneNumber() will not return their cell phone number, but instead will return the phone number used for BlackBerry MVS.  Uh-oh, did your app just create a support incident?  If you’ve been keeping up with platform features, the answer is no.

When a user is connected to BlackBerry MVS, the whole point is to use it as much as possible, thus getting its maximum benefit.  Thus, the user’s work number / the number associated with BlackBerry MVS now becomes the user’s default phone number – which is exactly what will be returned by getDevicePhoneNumber().  This new default phone number might cause a problem for the billing and/or authentication of your application through the carrier, since your application might be expecting the user’s cell number to be returned – not the BlackBerry MVS number.

So how do you handle this situation?

Option A: Make the user do it.

Since the user does have the ability to manually set which phone number to use, you could take a hard-nosed stance and make the user do all the work.  In order for the user to change this setting, they need to go into the Phone application, select “Options” from the menu, select “Work line,” then select “Line and Network Preferences,” and finally choose the right number using the drop down box labelled “Default line for outgoing calls.”  Save this change and you’re done.  With no change required to your app, getDevicePhoneNumber() now returns the cell number to you.  However, you’ve now just put a ton of onus on the user, reduced the effectiveness of BlackBerry MVS, and likely still generated a support call.

Option B: Take advantage of new platform features and use the new APIs.

Use the following API functionality added in BlackBerry Device Software 5.0:

int[] lineIds = Phone.getLineIds();
String phoneNumber = null;
for( int i=0; i < lineIds.length; i++ ) {
if(Phone.getLineType(lineIds[i]) == Phone.MOBILE_TYPE) {
//found the user’s cell number
phoneNumber = Phone.getLineNumber(lineIds[i]);
} else if Phone.getLineType(lineIds[i] == Phone.PBX_TYPE) {
//found the number used for BlackBerry MVS
}
}

With less than 10 lines of code, your app is more robust, BlackBerry MVS friendly, and can reliably provide the cell phone number to the carrier.  Personally, I like my carrier relationships, so I’ll go with option B.  But the choice is yours!

Have you tried out this tip? Let us know how it went in the comments!

About Brian Z.

Brian joined Research In Motion (RIM) in 2005 working with Independent Software Vendors (ISVs) who specialize in Bluetooth, GPS, multimedia, and gaming. As a senior member of the Developer Relations Team, it's Brian's mandate to not only support the application development efforts for a number of ISVs, but also to act as a voice at RIM for third party application developers. Like RIM, Brian's roots are in the enterprise world, but over the past couple of years he's quickly adapted to the consumer space, and that's where he spends most of his time today.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus