Integrating SMS Messaging

with your Rails Application

Blythe Dunham
blythe@snowgiraffe.com
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:2065551234@txt.att.net
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 & MT
gateway &
other
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
Doesn’t scale (only 6 to 10 messages per second)
Must connect modem to a server
Talk directly to all SMS Centers

SMSC SMSC SMSC

Awesome
App
 Mission Impossible: Coding for each SMSC
Large number of SMS Centers
Each use different and proprietary communication protocols

Don’t do this unless

you are me!
SMS Gateway translates SMSC protocols

SMSC SMSC SMSC

SMS Gateway

Rockstar
App
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.  Choose a short code (selected or random)

2.  Apply by sending registration data for 3, 6 or 12 months
3.  Receive approval email from CSCA
4.  Pay all up front $500 per month for Random, $1000/mo for Selected
5.  Apply for approval from each wireless service provider
6.  Sign a contract with each provider
7.  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
Outbound
Status
Delivery By Date
Time Sent
Sender/User
Username
Service Provider UID
Password
Favorite beer

PhoneNumber
Number
WhiteList? PhoneCarrier
DoNotSend? 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 NOT_PROCESSED Cron/Background

Action Task
Producer SUCCESS 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 s

•  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-content-
delivery.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
•  Crons tasks or bulk message
phone carrier email domains delivery
•  Clickatell HTTPS Integration •  Stale message recovery
•  ORM/DB tables and migrations to
•  Pretty UI with rounded corners
store messages
customized to your application
•  RESTful admin views to show
•  Inbound Message support
message history
•  Safe Locking and delivery
Please log tickets on github!
•  Safely store phone numbers
•  Dynamic parameter substitution
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/