GVoice: An Open Source Objective-C Google Voice Library

05/12/2011 Note: I failed to mention that the library, as it currently stands, builds for iOS only. I’m sure it could be rejiggered to work with OSX, because I don’t think I used any iOS specific features. All the project files would need to be changed, and I’m not sure what’s involved with that.

I am please to announce my free and open source Objective-C library for working with Google Voice. It’s called GVoice and you can find it here. It’s BSD licensed, which means you can use it for anything you want, both commercial and free/opensource.

It’s quite easy to use, and this example should help:

// USERNAME, PASSWORD, SOURCE and ACCOUNT_TYPE should be replaced with proper
// values.
self.voice = [[GVoice alloc] initWithUser: USERNAME password: PASSWORD source: SOURCE
accountType: ACCOUNT_TYPE];

// This causes some logging to happen.
self.voice.logToConsole = YES;

BOOL res = [self.voice login];

if (!res) {
// error handling

// Assuming you have a phone whose id is 23, this would cause Google Voice
// to route calls to it.
res = [self.voice enablePhone: 23]

if (!res) {
// error handling

// Send an SMS. Replace TEXT_PHONE_NUMBER with a proper 10-digit phone number
// capable of receiving SMS messages
res = [self.voice sendSmsText: @"Testing 1, 2, 3" toNumber: TEXT_PHONE_NUMBER];

if (!res) {
// error handling

On line 3, we create an instance of GVoice, passing in the email address and password from the user. The third field, source, is a field required by Google to identify where the connection is coming from. It’s free-form, but they suggest a reverse_domain_name-app-version approach, , something like com.joeygibson-GVTest-1.0, for example. The fourth parameter is what sort of account you’re trying to connect to, and there are two choices: GOOGLE and HOSTED. (This is an enum that also has a value of HOSTED_OR_GOOGLE, but I would suggest letting your user decide which account they have. It will save you problems later.)

Line 9 is where the actual login happens. If you get back a YES, all is well. If not, you can look at the GVoice object’s errorDescription property.

Line 17 demonstrates using one of the features of the library: enabling a phone. You pass the phone’s Id, which is obtained through another part of the API, and GV will then ring that number when a call comes in. You can also disable phones in the same fashion.

Line 25 shows how to send an SMS message from the GV account to the specified mobile phone.

There are many features that are fully formed, though some are still not as polished as I’d like. Two things still remain to be done: handling redirects and CAPTCHAs. After a certain number of failed logins, a URL will be returned that leads to a CAPTCHA image. To login after than you need to send a response to the CAPTCHA, but none of that is implemented in the library yet. Similarly, sometimes requests can be redirected by Google, but the library doesn’t handle those either. I’ve never seen either of these cases occur, but they could.

There is a full test suite included, which provides many more examples of how to use it. Before trying to compile it, you need to copy a file in the GVTests directory called GVCredentials-Sample.h to GVCredentials.h, replacing the dummy values with proper values. After that, you should be able to compile it and run the tests.

Full API documentation is available in the doc/ directory.

I wrote this library to use with my own iPhone app, which is currently in final testing before submission to the app store. I thought it would be useful for other people, so that’s why it’s free. If you’d like to use it, please do. If you’d like to improve it, let me know, and I can give you access to the repo.

It’s hosted on Bitbucket: https://bitbucket.org/joeygibson/gvoice.