SMS Carrier

SMS Carrier is a framework for designing SMS service layers. This is modified from Action Mailer of Rails framework, so the most of usage is just like Action Mailer.

Installation

Add this line to your application's Gemfile:

gem 'sms_carrier'

And then execute:

bundle

Or install it yourself as:

gem install sms_carrier

Usage

Sending SMSes

You can use carrier and template to send SMSes.

class RegistrationCarrier < SmsCarrier::Base
  default from: '+886987654321'

  def welcome(recipient, token)
    @token = token
    sms(to: recipient)
  end
end

In your view, eg. app/views/registration_carrier/welcome.erb.html

Your token is <%= @token %>, please confirm your phone number

If the token was given as 1234, the SMS generated would look like this:

Your token is 1234, please confirm your phone number

In order to send SMSes, you simply call the method and then call deliver_now on the return value.

Calling the method returns a Sms object:

sms = RegistrationCarrier.welcome("+886912345678", "1234")
sms.deliver_now

Or you can just chain the methods together like:

RegistrationCarrier.welcome("+886912345678", "1234").deliver_now

Or you can send SMS without carrier and template:

SmsCarrier::Base.sms(from: "+886987654321", to: "+886912345678", body: "Your token is #{token}, please confirm your phone number").deliver_now

Deliver Later

SMS Carrier use Active Job like Action Mailer. So you can deliver SMS later, too:

sms.deliver_later
sms.deliver_later(wait_until: Date.tomorrow.noon)
sms.deliver_later(wait: 1.week)

Options are defined by Active Job, please refer to Active Job.

Setting defaults

You can set up default settings in carrier by default method.

class AuthenticationCarrier < SmsCarrier::Base
  default from: "+886987654321", body: Proc.new { "SMS was generated at #{Time.now}" }
end

You can also set up in rails config, eg. config/environments/production.rb

config.sms_carrier.default_options = { from: "+886987654321" }

Generators

You can run following commands to generate carriers:

rails g carrier [name] [action] [action]...

Eg

rails g carrier registration welcome

It creates a Registration carrier class and test:

Carrier:     app/carriers/registration_carrier.rb
Test:        test/carriers/registration_carrier_test.rb
or
RSpec:       spec/carriers/registration_carrier_spec.rb

And class looks like this:

class RegistrationCarrier < ApplicationCarrier
  def welcome
    # ...
  end
end

Delivery Methods

You can also refer to the projects:

• twilio-carrier: Twilio SMS service.
• yunpian-carrier: Yunpian(云片) SMS service.
• dynamic-carrier: A delivery method layer that decides the delivery method dynamically by your rules.
• virtual_sms: You can send SMS to a virtual SMS box instead of real SMS service in development environment.

You can implement your delivery method.

class MyCarrier
  attr_accessor :settings

  def initialize(settings)
    self.settings = settings
  end

  def deliver!(sms)
    # sms.to is Array
    # my_deliver(sms.from, sms.to, sms.body)
  end
end
SmsCarrier::Base.add_delivery_method :my, MyCarrier

In your Rails project, you can set up in configuration:

config.sms_carrier.delivery_method = :my
config.sms_carrier.my_settings = {
  :settings => :pass_to_initialize
}

Difference with Action Mailer

• SMS Carrier removed preview.
• SMS Carrier removed attachments feature.
• SMS Carrier removed multiple part rendering.
• SMS Carrier use Hash as options to replace the Mail::Header as headers in Action Mailer.

License

The gem is available as open source under the terms of the MIT License.

Contact

The project's website is located at https://github.com/emn178/sms_carrier
Author: emn178@gmail.com