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.

Status reports

Get status report of a message is very simple:

Bulksms.report(:batch_id => 123456789)

You can obtain batch_id from response when you send a sms with Bulksms.deliver.

Limitations

This library currently only implements a small portion of the API, allowing you to send messages and check your account balance and status reports. Further parts of the BulkSMS API may be implemented in the future such as the ability to receive messages 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