libraryh3lp logo

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

Sunday, March 15, 2009

SMS Gateway Released

We've just completed our first SMS gateway (with some help from Ron DuPlain at Espresso Labs). We've been thinking about and working on this for awhile now. The main thing we wanted in our gateway was the ability for patrons to text their library at a real phone number, as opposed to using a shortcode technique such as the AIM hack.

We have been able to achieve this goal by working with Google's Android phone (T-Mobile G1). Since it has an open architecture and allows applications to run in the background, Eric has been able to write an application that is installed directly on the phone. The application intercepts SMS messages sent to the phone and redirects them to a LibraryH3lp queue, where they are then delivered just like other IMs on the system.

We like a few things about this:
  1. Patrons text a phone number and don't need to remember any shortcode tricks.
  2. Libraries are fully responsible for their phone and texting package, which means...
  3. LibraryH3lp fees do not need to increase one bit. This is just another gateway.
  4. The phone's mobile number can be redirected to another line, such as a reference desk line, for voice communications, in case someone tries to call it rather than text it.
  5. If you staff your service with our web client, you get a character countdown when replying to texts, which is helpful in reducing the number of messages sent. (A long message will be broken down and sent as multiple SMS messages.)
Of course, libraries will need to secure the phone and make sure it doesn't run out of power.

We believe the application works well, but this is our beta release. Currently, text messages sent when a gateway's queue is offline will not be delivered; these offline messages will get delivered soon, after a bit more work. The application is available for free in the Android Market now.

To setup an SMS gateway, start by installing the LibraryH3lp application on your G1. Go to the menu, click Settings, and give it a password (which can be anything). Then, go to the LibraryH3lp admin web site to define the gateway. This step is just like setting up any other gateway, just choose "sms", enter your ten-digit phone number as the username, and give it the same password you gave the phone. Finally, go back to your phone and click the "Start" button, and you're ready to start texting.

Source code freely available on Eric's Github. The code will work with any Jabber server; it is not LibraryH3lp-specific.


will said...

This is awesome. Working on getting a G-Phone to get it going.

eleedee said...

Cool! Question - what happens if nobody is currently monitoring chat? We're new to this, so I'm sorry if this is a stupid question, but can it go to an email address?

Pam Sessoms said...

Hi Ellie,

Not a stupid question at all!

If you set up an SMS gateway today, text messages sent when your library was offline would just get dumped.

However, offline messaging is a coming feature; its priority will get bumped up if we know there's real interest in using the SMS gateway.

Once offline messaging is implemented, you'll get those messages as IMs the next time your library signs in (rather than through email).

Hope this helps!

eleedee said...

Thanks Pam! Very helpful info.

S.M. Forbes said...

Just wondering if you know of any problems downloading/using the LibraryH3lp application to set up an SMS gateway in Canada?

Pam Sessoms said...


We don't know of any issues with Canada and can't think of any reason it shouldn't work. Will you please let us know if you encounter any problems?

Pam Sessoms said...

Update: Offline messages are available now for gateways (SMS and IM). This means that if your queue is offline when a patron texts you, you'll get that text the next time the queue comes online.

Erin Cassidy said...

Two questions, as we are concerned about our patron privacy. (1) Is the patron phone number kept private/made anonymous when the SMS arrives as an IM, or is the number stored in the chat transcript? (2) Does the original SMS message still appear on the physical phone (i.e., do patron phone numbers have to be purged from that device as well)?

Pam Sessoms said...

Hi Erin,

The patron's phone number is not hidden from the library. Privacy is extremely important in all things LibraryH3lp, and transcripts are stored securely.

Transcripts are under the control of the library. Transcript storage is turned OFF by default. If transcripts are enabled, there are management tools available for librarians.

At any time, the library can delete:

1) just the transcripts, leaving the record of the chat/IM/SMS session in place for statistical/reporting purposes.


2) The entire record of the chat/IM/SMS session, after which that record is no longer available for the reporting interface.

Also at any time, transcripts can be downloaded as zipped text files if desired (for example, to allow a content analysis).

All of these actions can be performed selectively or across a range of dates.

(2) Does the original SMS message still appear on the physical phone (i.e., do patron phone numbers have to be purged from that device as well)

Yes, all incoming SMS messages will stay on the phone until they are deleted. It's easy to do; the Android has a "delete all" option.

Hope this helps!

Unknown said...

Will this work with the new mytouch3g google phone?

Unknown said...

Will this sms gateway work with the new mytouch 3g google phone?

Pam Sessoms said...


We think it should work, but our phone is not that exact model. Give it a whirl and let us know.

Unknown said...

Hi everybody,

I write from Spain, we follow these instrunctions and I can't conect my phone with libraryh3lp.

I set up a gateway for my phone number with international prefix for spain.

Any idea what problem is?

Can you help me, please?

Pam Sessoms said...

Lorenzo, the problem is probably that the code inside the gateway software itself needs to be changed so that Spanish format phone numbers will work. Eric will work with you to try to resolve this.

Please either leave some contact info here or email Eric at nubgames at gmail dot com.

Unitec Library said...

Hi Pam

I suspect I've got the same problem as Lorenzo. Did you create a fix for it?

Thanks, Andrew

Pam Sessoms said...


We've discovered that some Android phones have issues with not knowing their own phone numbers and/or with sending blank text messages when trying to use the gateway.

We're trying to physically get our hands on one of these phones so that we can troubleshoot it more effectively. More news as it happens...

Unitec Library said...

I'm using an HTC Magic, which is the same as the MyTouch 3G. There was no problem downloading the application to the phone. I've tried specifying the queue with and without the country code, but it hasn't made any difference.


Pam Sessoms said...


Eric's currently working with another international user and we'll probably learn something helpful from that. We'll be back in touch when we know more. Sorry for the problems!

Unitec Library said...

Thanks Pam, it's a relief to know that you're working on the problem. Can you please post if there are any developments?


Pam Sessoms said...

Big update: Thanks to someone very kindly physically sending us their phone, we've been able to debug the problems with the new model Android phones, G2 (Mytouch 3G). This should fix recent mysterious issues, at least for 10 digit phone numbers as in the US.

The app has been updated on the Android Market. Your phone may even notice and ask you to upgrade.

There are a few other tweaks in the app, including new code to support international phone numbers. There may still be a little extra work to get that part fully functional.

Bottom line: Try again with the updated app. If it still doesn't work, let us know!

Unitec Library said...

It works! I'm using an HTC Magic and have a 10-digit phone number with the country code included.

Thank you so much for all your help with this.


Pam Sessoms said...

Andrew, horray!

Thank you so much for your patience and for testing it out so quickly.

All the best!

Karen Keiller said...

SMS gateway is working at the Univeristy of Manitoba! Thanks Pam. We're still in testing, but I will let everyone know how it goes!

Pam Sessoms said...

Quick update since this was such an active comments thread.

This gateway has been updated and local admins need to take some action. Details in a new blog post: