Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Integrating SMS services into RubyOnRails applications using BulkSMS gateway
Ruby
branch: master

This branch is 10 commits ahead of Shuntyard:master

Merge pull request #2 from sjkatz/master

Iconv and Ruby 2.0 compatibility.
latest commit 3221a84efc
@samlown authored
Failed to load latest commit information.
examples Fixing issue with encoding, adding more config options
lib Iconv and Ruby 2.0 compatibility.
spec Adding support for special character encoding
.gitignore First commit of brand new fork. Working on rspec testing before makin…
CHANGELOG Adding support for special character encoding
Gemfile First commit of brand new fork. Working on rspec testing before makin…
README.rdoc Adding support for special character encoding
Rakefile
bulksms.gemspec Improving specs reader for an initial release

README.rdoc

Introduction

BulkSMS is a Ruby library that allows you to easily integrate SMS services into your Ruby or Ruby on Rails applications.

It has support for all BulkSMS international sites, including the UK, USA, South Africa, Spain and Europe.

To use the library, you will need an account from www.bulksms.com and some credits.

Configuration

Simply set using the configuration object provided by the Bulksms module:

Bulksms.config do |config|
  config.username = 'testuser'
  config.password = 'zepass'
  config.country = :uk
end

If Rails is available, the library can be configured using the standard environment configs:

SomeRails::Application.configure do

  # set config in one go
  config.bulksms do |c|
    c.username = 'testuser'
    c.password = 'zepass'
  end

  # single config options
  config.bulksms.country = :es

end

Examples

Sending a quick message is very simple:

Bulksms.deliver(:message => 'Hello, I hope you like my message!', :recipient => '44799123456')

Multiple messages

Provide an array of hashes and multiple messages will be sent via the same HTTP connection:

Bulksms.deliver([{:message => 'Test Message', :recipient => "44342134131"}, {:message => "Another Msg", :recipient => "4441234354254"}])

Additional message options

If you prefer more control, the Service and Message objects are also available for direct usage:

s = Bulksms::Service.new
m = Bulksms::Message.new(:message => "Test Message", :recipient => "34901123123")
m.routing_group = 1
m.want_report = 1
s.deliver(m)

Encoding

All messages will be converted to ISO-8859-15 before being sent to the Bulksms servers. Some special characters, including the euro symbol, will be converted and prepended with a special escape character, suitable for GSM-7, so that they will be received correctly. For more details on character encoding, checkout the Bulksms API:

http://www.bulksms.com/int/docs/eapi/submission/character_encoding/

Checking your account balance

Use the main module to request the current user's balance:

Bulksms.credits

A Bulksms::AccountError will be raised if there is a problem.

Limitations

This library currently only implements a small portion of the API, allowing you to send messages and check your account balance. Further parts of the BulkSMS API may be implemented in the future such as the ability to receive messages and status reports and manage the address book provided by BulkSMS.

Testing

Rspec from the console:

rspec spec

Tests still need a bit more work to cover all cases.

Authors

The Original work on “ruby-bulksms” was made by Luke Redpath (email:contact@lukeredpath.co.uk). Modifications were added by Basayel Said (email:eng.basayel.said@gmail.com).

The latest version, “bulksms”, with a simpler interface, rspec testing, and an easier configuration was written by Sam Lown (me@samlown.com).

Modifications include:

  • simple helper module for direct access to classes

  • DRYer support libraries

  • Railtie support for configuration

  • Encoding messages correctly

Something went wrong with that request. Please try again.