Home

niryariv edited this page Sep 27, 2011 · 40 revisions
Clone this wiki locally

For new features, check out EnvayaSMS – EnvayaSMS is based on the KalSMS codebase with many added features such as polling, MMS support, multipart SMS and more.

KalSMS is a simple SMS gateway running entirely on an Android phone. It works wherever the phone can receive SMS messages and access the Internet (via wifi or GPRS), so it can provide an SMS gateway anywhere the phone works.

It requires no hardware or software installation. Configuration consists of only two settings. Maintenance simply means keeping a cellphone working – so most people in the world already know how to maintain KalSMS.

To install KalSMS, just scan this barcode:

Once installed, launching KalSMS will display the following screen:

Press Menu to open the settings screen. There are two settings:

  • SMS Identifier: KalSMS will only handle SMS messages that begin with this string. If you wish to handle any incoming SMS, set this to an empty value.
  • Target URL: Once an SMS is received, KalSMS will do an HTTP GET request to this URL, passing the contents in msg parameter and sender phone number in sender.

How KalSMS Works

When KalSMS is launched, it listens for SMS starting with the SMS Identifier string (or if the string is empty, any SMS). When a message is received, its content & sender phone number are sent as an HTTP GET request to the Target URL, for example http://example.com/sms?sender=1234&msg=itp+hello

The target URL may reply with XML containing messages to be SMSed back to the sender phone or other phones.

Here’s an example workflow:

  1. KalSMS is installed on the phone with Target URL http://qkhack.appspot.com/weather and SMS Identifier weather
  2. User sends an SMS to the phone running KalSMS with the text “weather 10026” from phone number 123-555-1337
  3. KalSMS recognizes the “weather” keyword and opens the URL http://qkhack.appspot.com/weather?sender=1235551337&msg=weather+10026
  4. The server at qkhack.appspot.com replies with the following XML:
    <reply>
        <sms-to-sender>Mostly Cloudy 51F today, Partly Cloudy 54F tomorrow, Mostly Sunny 58F Thursday</sms-to-sender>
    </reply>
  5. KalSMS parses the reply XML and SMSes the message Mostly Cloudy 51F today, Partly Cloudy 54F tomorrow, Mostly Sunny 58F Thursday to the user’s phone number, 123-555-1337

In addition to replying to an SMS, KalSMS can also send SMS to other phones as well. Check out the Examples page for more use cases, and Reply XML for details on the reply’s XML format.

Limitations

  • If you respond with text to be sent back to the user, KalSMS expects it to be UTF-8. Other encodings may work, but they might cause unexpected behavior.
  • At the moment KalSMS does not remove received SMS, which means you probably want to use one of Android’s SMS auto delete applications to clean them up periodically (if you have good/bad experience with a particular application please let us know and we’ll be happy to post it here)
  • KalSMS is not meant for mission critical or high load applications in its current form. It works, but it’s a young codebase and yet to be tested in real use. Again, if you have feedback on real use we’d love to hear it.

Help / Contact

If you’d like to help KalSMS, there are a number of ways to do so:

  • If you know Java, there’s always code to fix/clean up/add
  • If you happen to have a spare Android phone to donate for development/testing, it would be much appreciated :)
  • If you want to use KalSMS on a project, I’d love to work with you and help as much as I can!

On any feedback, questions, comments, etc please feel free to email niryariv@gmail.com. Project updates will be posted at @niryariv