Monday, August 3, 2009

Google Voice SMS Gateway

We just installed our Google Voice gateway, and it's ready for testing. You may know that LibraryH3lp already has an SMS gateway, one that runs on a library-purchased Android phone. The Android gateway continues to be a solid choice. However, for libraries needing a completely free option, without the cost of acquiring an Android phone and service provider, there is the Google Voice gateway now.

We prefer SMS solutions that let patrons text their library using a regular phone number, so that they can easily store it in their contacts list. Since Google Voice provides a phone number and can receive text messages, it was a good fit. By default, Google Voice wants to send text messages to a mobile phone you connect with your Google Voice account. You can also reply to them on the Google Voice website, but alerting is a problem. How do you know you have a text message in the first place? Google does not provide email or Google Talk chat alerts in Google Voice currently.

But this is where LibraryH3lp comes in. To configure your Google Voice gateway, sign into the admin site and select a queue for this gateway, or create a new queue for it. Create a "voice" gateway, and provide your Google login (username and password). Note that you never supply your Google Voice phone number. You'll probably also want to setup your Google Voice account to ring one or more of your public service desks in case someone calls it expecting to have a phone conversation. While you may advertise the number for your text message service only, once the number is in a contacts list, someone will very likely try to call it at some point.

Now, text messages sent to your GV number will arrive as regular LibraryH3lp chats. If you were offline when the message came in, you'll get it the next time that queue comes online. You reply from within your chat client, and these messages can be transferred just like any other chat in LibraryH3lp. If you're using our webchat client, LibraryH3lp will detect that your patron is coming in on a phone number, and you'll get a character countdown to assist your staff with making shorter replies, like this:

You won't get this countdown by default in other clients, but there are still things you can do. You can train staff to watch for a special queue name for text messages. There is a character count plugin for Pidgin that looks very promising (I have not tested it, but I have no reason to believe it would not work).

All of that said, we need to add a few caveats. Google does not currently provide an official API for Google Voice. Thus, this gateway works through screen scraping and polling, just like the other Google Voice applications coming out now. This means that if Google changes the code in the Google Voice SMS display area, it may break the gateway until we can account for the change. It also means that Google may throttle traffic if it detects some magical and unknown level of activity; the gateway application already tries to account for this, but further adjustments may be needed. Lastly, so far, Google has not shown signs of shutting down Voice applications, so we are optimistic, but we can't guarantee this will always be the case.

The Android gateway is still a safer bet. It uses published APIs to work with an open operating system. But as we all know, budgets are very tight these days, and free or very inexpensive solutions are extremely useful.

Quick update in case anyone has had bad luck testing. Right after we announced the gateway, we hit an unexpected glitch, and if you were testing it then, it probably didn't work.

However, we *think* we've got it beaten into submission now.

One note -- the patron's initial text message can take up to 5 minutes to appear for the librarian. This has to do with how the polling is setup right now. Once you have established a conversation, messages go through more quickly.

Have the problems described above reappeared? I tried setting this up, but while the SMS messages are showing up on our Google Voice account, they don't seem to be coming through to Pidgin. (I saw the note about five minutes to the first message appearing; at this point it's been about fifteen.)

(Regardless, thanks for putting this together. Once the bugs are worked out, this will be great to have.)

Updates for the collective. :) A couple of people are testing now, and some of the same glitches have happened to more than one person.

Here you go:

When first adding your gateway, be sure the queue is offline. If the queue is online when you add it, be sure to toggle its online/offline status before sending the first test message. You can toggle it by briefly un-assigning and re-assigning online operators on the queue.

The queue has to come online after you've added any new gateway, so that the login credentials for the gateway will get sent "home" (to Google in this case).

Once that's done, send your first test message.

If you've sent previous text messages to that Voice account, make sure your new test message is not exactly the same message that you sent previously.

The gateway will not send exact duplicates right on top of each other.

This is great. Thanks for setting up this gateway, Pam. Having a real phone number is really nice.

In the admin site, any texting patrons appear as their phone number. But for the actual operator (using Pidgin in our case) just sees a guest239483 ID like usual. I had thought their ID would be their number so librarians could easily ID a texter. Is there a reason that doesn't work with this gateway?

The appearance of the phone number depends a bit on the librarians' client. The webchat client displays it immediately and begins a character countdown since it has detected a phone number.

Pidgin displays the phone number immediately in the top bar on the conversation window. It's also part of the URL if you look closely enough. The guest ID becomes a phone number after the conversation "turns" a third time, which of course, isn't ideal.

For Pidgin, it's probably best to train staff to look for a queue named for the SMS service. They can also look for the phone number in the two places where it displays immediately.

A feature in progress is queue avatars, which let you supply a small image to represent your queue. These display now in the webchat client, but desktop clients have different ways they look for them, and they won't all find them yet. Eventually, though, they should show up.

Another seemingly-arcane rule (this one came up on the libh3lp google group as opposed to here in the blog):

Phones contacting your Voice gateway cannot have been assigned contact information. Having contact info significantly changes the underlying XML, and the screen scraping for the gateway doesn't currently account for this.

Delete any contact info from the phone number you're using to send your test text messages.

(This shouldn't be a problem in practice since your patrons won't have been assigned contact info in Voice.)

Seville University Library (Spain):We working with Android and LibraryH3lp but we can't connect both system. We download LibraryH3lp SMS Gateway software in our mobile and setup gateway in libraryH3lp admim for phone number. When we try start program in mobile don't happend anything. Please could help me?

Oct 6, 2009 Update: Google has changed how the authentication step works, so we have to update the gateway code to reflect this. For now, please check your Google Voice SMS messages by hand at the GV website.