Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 app
Octocat-spinner-32 config
Octocat-spinner-32 db
Octocat-spinner-32 lib
Octocat-spinner-32 script
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 Gemfile
Octocat-spinner-32 MIT-LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 action_smser.gemspec
README.md

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

Nexmo (http://nexmo.com/) is supported also.

  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(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

Requirements

Gem has been tested with ruby 1.9.3, ruby 2.1, Rails 3.1 and Rails 4

http://travis-ci.org/#!/holli/action_smser

Changes

Version 2.0 dropped support for ruby 1.8.7. Versions below 2.0 were tested also with ruby 1.8.7

Support

Submit suggestions or feature requests as a GitHub Issue or Pull Request. Remember to update tests. Tests are quite extensive.

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)

Something went wrong with that request. Please try again.