/sms_kit

Easily send text messages via an HTTP SMS gateway.

Primary LanguageRubyMIT LicenseMIT

SmsKit

Gem Version Build Status

Easily send text messages via an HTTP SMS gateway.
The goal is to offer one streamlined API for any provider adapter.

Installation

Add this line to your application's Gemfile:

gem 'sms_kit'

And then execute:

$ bundle

Or install it yourself as:

$ gem install sms_kit

Usage

Configuration

You can store arbitrary options in a provider's configuration:

require 'sms_kit/providers/mobi_web'
SmsKit::MobiWeb.configure do |config|
  config.username = 'user'
  config.password = 'pass'
  config.sender   = 123456
end

Send text message

provider = SmsKit::MobiWeb.new text: 'Hello World.', to: 491231234567
result   = provider.deliver

# returns the message id from MobiWeb or nil if something went wrong
puts result // 1234

There's also a short version:

SmsKit::MobiWeb.deliver text: 'Hello World.', to: 491231234567

Sending "Objects"

If your class responds to to_sms, you can send it itself:

class TextMessage
  def to_sms
    {
      to: 491231234567
      text: 'hello world'
    }
  end
end

SmsKit.deliver :provider_name, TextMessage.new

# or on a provider level

class MyProvider < SmsKit::Provider
  # ...
end

MyProvider.deliver TextMessage.new

Custom Provider

class MyProvider < SmsKit::Provider
  # default url that the built-in http client will use
  HTTP_ENDPOINT = 'https://www.example.com'.freeze

  # ...

  # custom connection configuration
  # the default implementation (`super`) accepts a block
  # which yields you a faraday instance
  def connection
    super do |conn|
      conn.headers[:user_agent] = 'custom user agent'
    end
  end
end

Error handling

SmsKit will throw a SmsKit::DeliveryError if something goes wrong. Though it depends on the specific provider this generally happens upon authentication errors as well as returned error codes from the web service.

begin
  provider = :provider_symbol
  SmsKit.deliver provider, text: 'hello world', to: '...'
rescue SmsKit::DeliveryError => e
  logger.error e
end

Common SMS options

Which options the #deliver method expects generallly depends on provider implementation. However, core providers expect the following options, at least:

  • :to The number to send the message to
  • :from The sender ID
  • :text The text message

Packaged providers

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

SmsKit is released under the MIT License.