Integrating SMS Messaging

with your Rails Application

Blythe Dunham
[email protected]
spongecell.com / snowgiraffe.com

Why SMS?
Oldest most reliable means to communicate with mobile users
Cell phone agnostic
Everybody is doing it
Great way to receive emergency messages at the bar

SERVER IS DOWN
SPARKS ARE UP

Popular Applications to Send SMS

Standard Email
yournumber@gatewayaddr Example:[email protected]
Find your provider gateway
Instant Message
AOL (US only)
Skype (small fee)
Other
Teleflip RIP
remindblast.com - Send SMS reminders to be awesome or do laundry
Facebook SMS app
Cell providers web page (ex. http://www.t-mobile.com)

Overview: One Way Messaging

Mobile Terminated (MT) or Outbound

Party at A1A Beach

front Ave

Black Box of
Your application &
gateway &
other

Mobile
Terminated
(MT)

Overview: Two Way Messaging

Mobile Originated (MO) or Inbound
Respond with "ROCK" for
Free party tix

Black Box of
Your application &
gateway &
other

MT
MO
ROCK

Simplest approach: SMS as email

Pros and Cons of sending SMS through email

The Good

Free to application (end-user with phone might pay)

Easy to integrate. Only email setup required.

Excellent for use with known numbers

Emergency Messages with plugins like Exception Notification

Pros and Cons of sending SMS through email

The Tricky

User carrier must be known

additional user input

storage considerations

No delivery confirmation

Supported by most US but not all cell phone carriers

No two way messaging

Giant Black Box Explained:

SMSCs, SMS Gateways,
Service Providers
Before exploring the other available
SMS options, lets look at how
SMS works

SMS Centers (SMSC)

SMSC

SMSC

SMSC

GSM Modem

SMSC

GSM
Modem
(Cell Phone)
AT Commands

Super
App

GSM Modem APIs and Applications

Kannel in C (open source) supports an API

RubyGSM - Written by Unicef for RapidSMS to inexpensively send

text messages

GSM Modem LoDown

Advantages
Cheap
Can use almost anywhere
Two way messaging support
Disadvantages
Difficult to setup
Slow
Doesnt scale (only 6 to 10 messages per second)
Must connect modem to a server

Talk directly to all SMS Centers

SMSC

SMSC

Awesome
App

SMSC

Mission Impossible: Coding for each SMSC

Large number of SMS Centers
Each use different and proprietary communication protocols
Dont do this unless
you are me!

SMS Gateway translates SMSC protocols

SMSC

SMSC

SMS Gateway

Rockstar
App

SMSC

SMS Gateways
Free Open Source Gateways
Kannel - written in C supports many SMSCs and also acts as a WAP
gateway
Must setup/configure on a server yourself

Pay the middleman!

Charge for sending messages

~ 5 cents per message

Bulk discounts

Provide convenient APIs

Most provide two way

messaging

Can help obtain short code

SMS Gateway: Sending Outbound (MT)

Typical approach for Outbound messages is simple:

Create an account

Buy credits (or messages)

Start sending messages through the API

Ruby Outbound (MT) message with HTTPS

http = Net::HTTP.new(CLICKATELL_BASE_URL, 443)
http.use_ssl = true
http.enable_post_connection_check = true
http.start {response =

http.request_get(url_string)}

Choosing an API (if you have a choice)

HTTP/S (GET & POST)

- By far the easiest to implement
- Great for sending < 10k messages a month
SMPP
- Best for bulk messages (over 10k per month)
- Leaves Connection open
STMP - send through mail
Other options (not so hot)
FTP - Bulk option for legacy systems
XML (use HTTP if available)
SOAP (use HTTP if available)
Com Object (Seriously? What wah?)

SMS Gateway: Two way messaging and MOs

1. Typically enable Outbound messaging
2. Obtain or rent a short code
3. Respond to Inbound MOs
1. Use a provider campaign management tool ($$$)
2. Parse yourself and write some regexp!

/^OPT(\s*[-_]?\s*)OUT|STOP|END|QUIT|
UNSUBSCRIBE|EXIT|HALT|
FUCK(\s*[-_]?\s*)OFF|REMOVE|CANCEL)/i

Two way messaging: Pull

Setup a cron task to pull new messages every few seconds.

Two way messaging: Push

Provide a callback URL that service provider invokes for each new
message

Do I need a short code?

If your awesome app is:

A giant spam machine

Implementing two way messaging
(Recommended) Sending > 5000
messages per month

Shared (Rented) Versus Dedicated Short Codes

Shared short code
shared with others
requires keyword like "RUBY"
Dedicated short code
all to yourself
Takes around 2 months to obtain
$1000 for a selected code or $500 for a random code per month

Chewing on a Cactus
Sms gateway service providers(connection aggregators) will help with
this process or you can go directly through the CSCA in the US

1.
2.
3.
4.
5.
6.
7.

Choose a short code (selected or random)

Apply by sending registration data for 3, 6 or 12 months
Receive approval email from CSCA
Pay all up front $500 per month for Random, $1000/mo for Selected
Apply for approval from each wireless service provider
Sign a contract with each provider
Implement and Test each connection with each provider

Opt out concerns

Handled by most providers

Implement yourself
-

Tracking

Opting out different

senders

Choosing a Service Provider

Cost: how many sms messages will you send per month?
Credit vs. sms
Hidden costs
Monthly fee
Coverage: does the provider cover all needed areas?
Implementation Time: is the API you want to use easy to integrate?
Opt-out: is it handled?
Two way messaging: is it supported? Do you need it?
Help with short code cactus eating experience?

Developer Integration Concerns

Save message information

Do you need to save a history or audit trail for reporting?
Lots of messages to send?
Can't send in real time (before controller action times out?)

Inside the SMS ORM: Check out SMS ON RAILS

Draft
Message
Delivery By Date

Outbound
Status
Time Sent
Service Provider UID

Sender/User
Username
Password
Favorite beer

PhoneNumber
Number
WhiteList?
DoNotSend?

PhoneCarrier
Name
Email gateway

Outbound Status: Produce and Consume

Web action creates an Outbound record with status

NOT_PROCESSED

Cron task processes messages with status NOT_PROCESSED and

marks them SUCCESS or FAIL
Controller
Action
Producer

NOT_PROCESSED

SUCCESS

Cron/Background
Task
Consumer

Locking and Delivering: Outbound Status

No transactions; no take backs
When delivering a message, try locking Outbound ORM object
SUCCESS

NOT_PROCESSED

PROCESSING

FAILED

Bulk Message Delivery

Use batch API call to send multiple phone numbers the same msg

For huge deliveries, use SMPP to maintain an open connection

Set delivery date and send to provider in advance

Lock multiple records with your database (MySQL FOR UPDATE)

Use Multiple servers

Bulk Message Delivery Tips

Reduce contention for competing servers storing data

Assign a group of records (ID mod X srvrs) to each server

(non dedicated servers) put tasks on staggered timers (ex. every

2 min) that execute for a shorter duration(ex. 45 seconds)

Identify fatal errors and stop the task

Fatal, stop task: Ex. No response from service provider

Single message error: Mark failed and continue processing

Cron to Recover messages in 'PROCESSING' state with updated_at

field > duration of consumer task (ex. 10 min)

Delivery status background task to request delivery information

Set priority on messages

Sanitize Phone Numbers

PhoneNumber.create!(:number => '(206)-555-1212 ')
PhoneNumber.find_by_number('12065551212') == nil

Your database without data integrity

Sanitize Phone Numbers

Sanitize all phone numbers before
search or insert or update
Store with country code (for USA
auto add a 1 for 10 digit
numbers not inputted with a +
or 0)

My database runs on flowers

Outbound Attributes: White List and Opt Out

Save safe numbers on a white list and enable checking to

prevent accidents (test mode)

restrict access

Store Opt-Out Information

Prevent paying for a message to a recipient provider opted out

Can make a distinction between opt out, opt in, and bounce, abuse

SMS Gateway Service Providers

Short List of Providers
http://www.redoxygen.com
http://www.redrabbitsms.com/
http://clickatell.com
http://quios.com
http://messagepub.com/
http://www.openmarMeket.com/products-and-services/message-and-contentdelivery.html
http://www.mobilemarketing.net
http://www.textmarks.com/
http://www.mozes.com/
Long list and comparison table of providers:
http://www.developershome.com/sms/smsGatewayProvComp.asp

Useful References
General SMS: http://www.developershome.com/sms/
Provider Gateway addresses: http://en.wikipedia.org/wiki/SMS_gateway
Sms On Rails Engine: http://github.com/blythedunham/smsonrails
Clickatell Gem: http://clickatell.rubyforge.org/
Exception Notification Plugin:
http://github.com/rails/exception_notification/tree/master
Kannel: http://www.kannel.org/
RapidSms http://mobileactive.org/tagging/rapid-sms
RubyGSM http://mobilehacking.org/index.php/RubyGSM
More Mobile Tools: http://mobilehacking.org/index.php/Main_Page
Common Short Code Admin(CSCA) http://www.usshortcodes.com/

SMS On Rails Engine: SMS in minutes

script/plugin install git://github.com/blythedunham/smsonrails
Support for:

Not included: (yet)

Email Gateway Integration with

phone carrier email domains

Crons tasks or bulk message

delivery

Clickatell HTTPS Integration

Stale message recovery

ORM/DB tables and migrations to

store messages

Pretty UI with rounded corners

customized to your application

RESTful admin views to show

message history

Inbound Message support

Safe Locking and delivery

Safely store phone numbers

Dynamic parameter substitution

Please log tickets on github!

Questions?

Yo Dawg, I heard you like Rails Apps so I put an

SMS Rails App in your Rails App so you can
SMS yourself to be awesome

Photos
Trash can http://www.flickr.com/photos/knittingskwerlgurl/396165625/
Flowers http://www.flickr.com/photos/blondepowers/2722511769/
Timepiece: http://www.flickr.com/photos/lebron/223223725/
Bear http://www.flickr.com/photos/guenterleitenbauer/697065143/
Email http://www.flickr.com/photos/charuca/2448685976/
Golden gate: http://www.flickr.com/photos/h2orange/63606734/
Beetles: http://www.flickr.com/photos/lhtang2006/3490285407/
Computer Cat: http://www.flickr.com/photos/sammrowe/3491788169/
Giant: http://www.flickr.com/photos/andreatallone/2841979961/