libraryh3lp logo

LibraryH3lp is software used by libraries, educators, and non-profits for better customer service.

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.


Eric Sessoms said...

Code is here, as always:

Ellen said...

We have tested the character count plugin for Pidgin while we were getting ready to launch the AIM hack, and it works very well.

Pam Sessoms said...

Ellen, awesome. Thanks for letting folks know!

Michael Peper said...

Is Google giving out GV numbers? I went to learn more about GV and it asked me to submit a request for an invite and that I would be informed when the program was ready.

Pam Sessoms said...

Yup, they've been rolling them out. I put an account on the list one or two days ago and received the invitation today. So, it seems to be happening pretty fast!

Pam Sessoms said...

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.

Unknown said...

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.)

Pam Sessoms said...

Rinn Law,

Hmmm, very strange. Yes, it's been working fine for me today.

I just did several tests with two different Voice accounts and then all worked... so we need to figure out why it's not working for you.

Please email me directly psessoms at gmail dot com and we'll go from there. I'm also checking with Eric to see if he can see anything strange happening on the back end.

Pam Sessoms said...

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.

I think that's it for now... Happy testing!

Pam Sessoms said...

One more thing...

Offline messages are supported for the Voice gateway, but only after it has been "activated" by its queue coming online once.

(I know! So many rules!)

After the queue comes online once, offline messages should work with Voice, with the messages appearing for librarians the next time the queue comes online.

Michael Peper said...

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?

Pam Sessoms said...

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.

Here is how it looks in pidgin (screenshot).

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.

Kenley Neufeld said...

I'm happy this option is available. However, I have been unsuccessful.

Check. Created gateway while queue was offline.

Check. Waited more than 5-minutes for text to arrive.

Check. Tried several different texts while testing (before and after doing above.

Any other hints to try? Our Google Voice is 805-699-5874.

Pam Sessoms said...

Hi Kenley,

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.)

I've been building a help doc about all the Voice stuff:

Hope this helps!

Kenley Neufeld said...

I'll give it a try tomorrow or Monday. Thanks Pam.

Unknown said...

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?

Pam Sessoms said...

To Lorenzo in Spain,

We think it most likely has to do with different formatting for Spanish phone numbers (as compared with US numbers). Eric will be in touch with you to see what adjustments are needed.

Pam Sessoms said...

To Lorenzo in Spain,

I just realized 2e don't have any contact information for you.

Please write directly to nubgames at gmail dot com, and Eric will look into getting the Android gateway to work with your country's phone number formatting.

Kenley Neufeld said...

Learned of another feature to be aware of when using Google Voice Gateway.

If a series of messages are sent to the gateway (for example, if the length is longer than one SMS) then they may not be displayed in the correct order in webchat client.

I tested this a couple times with the same results. Typically this shouldn't be a problem because most send a single SMS and wait for a response.

The other "funny" thing is when I removed the contact information as suggested and then tested the service, ALL the previously sent texts appeared in the webchat client. Hahaha.

For the good.

Pam Sessoms said...


Glad you got 'er working!

Also, great catch on the ordering thing. Makes sense given the screen scraping thing and how GV displays messages. I'll add this to the doc about this gateway, hopefully this weekend.


Pam Sessoms said...

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.

Should be back somewhere between tonight and this weekend.

Colin said...

I stumbled upon this and we're looking to do this. I'm brand new to libraryh3lp. Dumb Question: How do you assign users to queues? Is there a good "get started" tutorial somewhere?


Pam Sessoms said...


Here's a quick movie I just made to show how to assign users to queues (and how the basic notion of presence works):

Within the admin site, there's some help on this in the top-right of the users/queues/gateways area. Specifically:

Good luck!

ocdude said...

Does the Google Voice gateway still work? There was a comment from back in October 2009, but I do not see any followup about it.

Pam Sessoms said...

Oh yes, it definitely works. Sorry, I must have left a loose end.

If you have trouble getting it going, drop me a line.