ActionSmser == SMS && ActionMailer. Simple way to use SMS (Short Message Service) in the same way as ActionMailer. Includes also delivery reports and easy way to add custom gateways. See examples below.
Gemfile ->
gem 'action_smser'
# To use delivery reports
bundle exec rake railties:install:migrations
rake db:migrate
Initializing
in /config/initializers/active_smser.rb
if Rails.env.development? || Rails.env.production?
ActionSmser.delivery_options[:delivery_method] = :simple_http
ActionSmser.delivery_options[:simple_http] = {
:server => 'server_to_use', :username => 'username', :password => 'password',
:use_ssl => true
}
# ActionSmser.delivery_options[:save_delivery_reports] = true
end
Mailer classes
in /app/mailers/test_sms.rb
class TestSms < ActionSmser::Base
def hello_user(to, from, user)
str = "Hello #{user}."
sms(:to => to, :from => from, :body => str)
end
end
Sending sms
E.g. from console or controller
sms = TestSms.hello_user('358407573855', '358407573855', "Olli")
sms.deliver
Optional delivery methods can be used by creating classes under "ActionSmser::DeliveryMethods" and referring them as downcase infos. See example of :simple_http at https://github.com/holli/action_smser/blob/master/lib/action_smser/delivery_methods/simple_http.rb
Simplest case is to use simple_http and override path
# Example of changing simple_http delivery path. Options are the same options that were presented above.
module ActionSmser::DeliveryMethods
class SimpleHttp
def self.deliver_path(sms, options)
"/my_gateways_api/send?user=#{options[:username]}&password=#{options[:password]}&ValidityPeriod=24:00&sender=#{sms.from_encoded}&SMSText=#{sms.body_encoded_escaped}&GSM=#{sms.to_encoded}"
end
end
end
Vonage/Nexmo (http://nexmo.com/) is supported. Nexmo was renamed to Vonage, but naming has not been updated this lib.
ActionSmser.delivery_options[:delivery_method] = :nexmo
ActionSmser.delivery_options[:nexmo] = {
:username => 'key', :password => "password"
}
# set callback url to nexmo http://localhost:3000/action_smser/delivery_reports/gateway_commit/nexmo
ActionSmser.delivery_options[:gateway_commit]['nexmo'] = ActionSmser::DeliveryMethods::Nexmo
DelayedJob (https://github.com/collectiveidea/delayed_job)
# Sending can often take couple seconds and you might want to do it in the background so that user gets instant feedback.
# Need DelayedJob > 3.0.0 in your gemfile. Set the real delivery_method through delivery_options[:delayed_job]
ActionSmser.delivery_options[:delayed_job] = { :delivery_method => :patidure, :priority => 0 }
If you add other common gateways to this framework, plz generate tests and send us a patch.
Gem handles collecting and analysing of delivery reports. This enables you to make sure that your gateway works.
Delivery reports and a summary can be seen at http://localhost.inv:3000/action_smser/delivery_reports/ . Summary includes info about the amount of sent sms, delivery times, types of sms, etc.
Parsers and access infos can be implemented by creating a class with admin_access and process_delivery_report methods. See example below.
in /config/initializers/active_smser.rb
ActionSmser.delivery_options[:save_delivery_reports] = true
class ActionSmserConfigExample
# This returns true if we can show delivery reports page, return true if always permissed
def self.admin_access(controller)
if controller.session[:admin_logged].blank?
return controller.session[:admin_logged]
else
return true
end
end
# This has to return array of hashes. In hash msg_id is the key and other params are updated to db
def self.process_delivery_report(request)
params = request.params
processable_array = []
if params["DeliveryReport"] && params["DeliveryReport"]["message"]
reports = params["DeliveryReport"]["message"]
reports = [reports] unless reports.is_a?(Array)
reports.each do |report|
processable_array << {'msg_id' => report['id'], 'status' => report['status']}
end
end
return processable_array
end
end
# This is simple proc that is used in a before filter, if it returns true it allows access to
# http://localhost.inv:3000/action_smser/delivery_reports/ with infos about delivery reports
ActionSmser.delivery_options[:admin_access] = ActionSmserConfigExample
# Parser is used with urls like
# /action_smser/delivery_reports/gateway_commit/test_gateway
# where 'test_gateway' is the part that is used for locating right parser.
ActionSmser.delivery_options[:gateway_commit]['test_gateway'] = ActionSmserConfigExample
DeliveryReports can be searched by "dr = ::ActionSmser::DeliveryReport.where(xxx).first". Some helpers in delivery_reports include
- dr.to_sms => creates new sms message from deliveryreport.
- dr.resent(:gateway) => creates new sms and sends it through given gateway.
Observers can be used by implementing "delivery_observer" in your sms class
class TestSms < ActionSmser::Base
def hello_user(to, from, user)
str = "Hello #{user}."
sms(:to => to, :from => from, :body => str)
end
def before_delivery()
puts "Called just before delivery"
end
def after_delivery(response_from_delivery_method)
puts "Done with delivery"
end
end
Gateway committed status updates can also have observers
in /config/initializers/active_smser.rb
class ActionSmserConfigGatewayObserver
def self.after_gateway_commit(delivery_reports)
puts delivery_reports.inspect
end
end
ActionSmser.gateway_commit_observer_add(ActionSmserConfigGatewayObserver)
Default delivery method is "test_array". It saves delivered sms to ActionSmser::DeliveryMethods::TestArray.deliveries to help test your own software. Its normal array, see sms by 'ActionSmser::DeliveryMethods::TestArray.deliveries' and clear it between tests by 'ActionSmser::DeliveryMethods::TestArray.deliveries.clear'
E.g. in functional tests
test "should send right msg" do
ActionSmser::DeliveryMethods::TestArray.deliveries.clear
get :send_invite, :user_id => 1
assert_equal 1, ActionSmser::DeliveryMethods::TestArray.deliveries.size
assert_equal "UserSms.sent_invite", ActionSmser::DeliveryMethods::TestArray.deliveries.first.sms_type
end
Submit suggestions or feature requests as a GitHub Issue or Pull Request. Remember to update tests. Tests are quite extensive.
Check github actions for what environments are supported: https://github.com/holli/action_smser/blob/master/.github/workflows/ci.yaml and https://github.com/holli/action_smser/actions . See https://github.com/holli/action_smser/blob/master/CHANGELOG.md for changes and to see what version to use with older Rails versions.
There are many gems to use custom gateways but none of them had a possibility to create classes like smser. Also these don't have delivery reporting.
This project rocks and uses MIT-LICENSE. (http://www.opensource.org/licenses/mit-license.php)