SmsOnRails

Sms on Rails provides an interface and ORM framework for sending and storing SMS messages through Email Gateway or with Clickatell HTTPS

The models and underlying architecture extend and include a ton of modules and are designed to be configured if necessary. If you do not wish to run the vanilla configuration, copy the vendor/plugins/sms_on_rails/lib/models to your local models directory or copy vendor/plugins/sms_on_rails/lib/service_providers to lib/service_providers.

A lot of care has gone into the locking mechanism to prevent double sends. This is a precursor to mass Smsing machine. Further detailed configuration is necessary. Contact [email protected] if you love grapes.

Install

Install Gem

Add to environment.rb

config.gem 'smsonrails', :source  => 'http://gemcutter.org'
config.gem 'clickatell' #If using Clickatell

Vendor the Gem

rake gems:install
rake gems:unpack

Quick Setup (after Install)

script/generate sms_on_rails setup --default-service-provider=[provider]

rake gems:install or rake gems:unpack (if using Clickatell)

rake db:migrate

Alternate Install

Directly Install Gem

gem sources -a http://gems.github.com
sudo gem install blythedunham-sms_on_rails

Plugin

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

Edit SMS configuration details in config/environment.rb. Sign up for clickatell at clickatell.com and/or update your mail settings for use with the email gateways.

Example Setup

The following creates a new rails project dog and adds the Sms On Rails plugin. As seen at RailsConf2009

rails dog --database=mysql
mysqladmin -uroot create dog_development
cd dog
script/plugin install git://github.com/blythedunham/smsonrails
script/generate sms_on_rails setup --default-service-provider=clickatell
rake db:migrate
mate config/environment.rb

Run Setup Generator

script/generate sms_on_rails setup --default-service-provider=[provider]

Running the generator performs several setup steps:

copy image and stylesheet assets to your public directory
generates 3 database migrations (the 2nd and 3rd have a 2 and 3 appended)
installs clickatell gem and static_record_cache plugin (for email carriers caching)
insert configuration skeleton into environment.rb

Migrate

Three files are created with different timestamps in db/migrate

Email Carrier information (email addresses for each carrier like txt.att.net)
Phone Number setup.
Draft and Outbound tables

Check them out and then run:

rake db:migrate

Configure settings

After running the generator, open up config/environment.rb in your rails application. Update the configuration hash maps, added by the generator, with your settings.

email gateways - SmsOnRails::ServiceProviders::EmailGateway.config. Standard ActionMailer configuration is required for the Email Gateway.
clickatell http - SmsOnRails::ServiceProviders::Clickatell.config. Sign up for an account at clickatell.com

Ensure that the correct default provider is selected. Should be :email_gateway or :clickatell

SmsOnRails::ServiceProviders::Base.set_default_service_provider :clickatell

Also make sure that the correct default provider is selected.

Added to environment.rb

SmsOnRails::ServiceProviders::Clickatell.config = {
  :api_id => 'api_key',
  :user_name => 'user_name',
  :password => 'password'
}

SmsOnRails::ServiceProviders::EmailGateway.config = {
  :sender => 'youremail address',
  :subject => 'Default Subject Text'
  #:bcc => nil,
  #:mailer_klass => nil,
}

SmsOnRails::ServiceProviders::Base.set_default_service_provider = :email_gateway

Avoiding Collisions with existing PhoneNumber class

If you already have a PhoneNumber ActiveRecord class and phone_number database table, you might experience a collision with the SMSOnRails engine. To avoid this, the generator will take the following measures.

PhoneNumber Migration

Instead of creating a new table, the phone number migration created by the generator will add only the columns needed by SMSOnRails. Please make sure to check out the migration for errors.

PhoneNumber ActiveRecord Class Changes

The generator will update PhoneNumber and add SmsOnRails::PhoneNumber

PhoneNumber app/models/sms_on_rails/phone_number.rb This file is added and used to point SmsOnRails::PhoneNumber point to PhoneNumber

PhoneNumber app/models/phone_number.rb The following two modules are included on your PhoneNumber class:

SmsOnRails::ModelSupport::PhoneNumber - basic functionality
SmsOnRails::ModelSupport::PhoneNumberAssociations - associations for PhoneNumber

These modules are defined in:

vendor/plugins/smsonrails/lib/sms_on_rails/model_support

Please manually modify your PhoneNumber class to change the associations if you must.

ActionMailer

You will need to configure ActionMailer in environment.rb if you wish to use the Email Gateway. Refer to the Troubleshooting section for more information.

By default, SmsMailer inherits the ActionMailer settings. If your SMS Mailer settings differ from the default ActionMailer settings, you can define the new settings in enviroment.rb with:

SmsOnRails::ServiceProviders::EmailGatewaySupport::SmsMailer.smtp_settings ={}

Default SMS Routes

Default Links in Your Application

Send SMS: localhost:3000/sms/new
Admin: localhost:3000/admin/sms
- Draft History: localhost:3000/admin/sms/draft
- Phone Numbers: localhost:3000/admin/sms/phone_numbers
- Phone Carriers: localhost:3000/admin/sms/phone_carriers

Send Messages

Access Service Providers Directly

All service providers are singletons and can be accessed by their instance

To send a message without validation use send_message

SmsOnRails::ServiceProviders::<Provider>.instance.send_message '12065551234', 'my message', options

To send a message with validation use send_to_phone_number with a string or SmsOnRails::PhoneNumber instance

 SmsOnRails::ServiceProviders<Provider>.instance.send_to_phone_number(number, message, options)

To send an sms (+Outbound+) (with validation)
 SmsOnRails::ServiceProviders<Provider>.instance.send_sms(sms, options)
However, it is preferred to use the locking mechanism to prevent double messages from being sent
  sms.deliver!

ORM examples:

Clickatell does not need a carrier

SmsOnRails::Outbound.create_sms 'Send this test message', '11234567890', :send_immediately => true

Email gateway needs a carrier specified

sms = SmsOnRails::Outbound.create_sms 'Send this test message', '12065551234',  :carrier => :att
sms.deliver!

Troubleshooting

Clickatell

Install Clickatell gem If you are using clickatell, please install the clickatell gem with either command:

sudo rake gems:unpack
sudo rake gems:install
sudo gem install clickatell

Possible Error messages:

Missing these required gems: clickatell
Cannot set default provider to clickatell. Check that support for clickatell exists.

Email Gateway

ActionMailer If you are using the email gateways, make sure that your ActionMailer settings are configured properly in environment.rb. A good test is to send a normal email.

You can also test your settings by adding the line below to your environment.rb file.

ActionMailer::Base.delivery_method = :test

The message should be print to the log file log/development.rb like below:

To: [email protected]
Subject: Default Subject Text
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8

This is my test message

Developers

Blythe Dunham snowgiraffe.com

Homepage

Project Site: github.com/blythedunham/smsonrails

License

This is MartiniWare. Buy yourself a martini if you like this software! If you like any software that uses this plugin you should also buy yourself a martini. Manhattans are ok too.