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 theMail::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