0.02
Low commit activity in last 3 years
A long-lived project that still receives updates
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 (simple http and nexmo by default).
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

 Project Readme

ActionSmser

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.

Install

Common

Gemfile ->

gem 'action_smser'

# To use delivery reports
bundle exec rake railties:install:migrations
rake db:migrate

SMS sending basic

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

Delivery methods

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.

Delivery reports

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.

Other options

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)

Testing

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

Support

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.

Similar gems

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.

Licence

This project rocks and uses MIT-LICENSE. (http://www.opensource.org/licenses/mit-license.php)