Skip to content

mediaburst/clockwork-ruby

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

62 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Clockwork SMS API Ruby Gem

Gem Version

Install

Just add the following to your Gemfile:

gem 'clockworksms'

Documentation

Full documentation is at http://rubydoc.info/github/mediaburst/clockwork-ruby/master/frames. Alternatively, run yard doc and open doc/index.html.

Usage

For more information on the available optional parameters for the API (Clockwork::API), see here.

For more information on the available optional parameters for each SMS (Clockwork::SMS), see here. For more information on the response object returned from each SMS (Clockwork::SMS::Response), see here.

Send a single SMS message

require 'clockwork'
api = Clockwork::API.new( 'API_KEY_GOES_HERE' ) #Be careful not to post your API Keys to public repositories.
message = api.messages.build( :to => '441234123456', :content => 'This is a test message.' )
response = message.deliver
    
if response.success
    puts response.message_id
else
    puts response.error_code
    puts response.error_description
end

Alternative usage for sending an SMS message

require 'clockwork'
api = Clockwork::API.new( 'API_KEY_GOES_HERE' ) #Be careful not to post your API Keys to public repositories.
    
message = api.messages.build
message.to = '441234123456'
message.content = 'This is a test message.'
response = message.deliver

if response.success
    puts response.message_id
else
    puts response.error_code
    puts response.error_description
end

Send multiple SMS messages (with an optional client ID)

You should not use the Clockwork::Message#deliver method for each message, but instead use the Clockwork::API#deliver method to send multiple messages in the same API request. This will decrease load on the API and ensure your requests are processed significantly faster.

messages = [
    { :to => '441234123456', :content => 'This is a test message.', :client_id => '1' },
    { :to => '441234123456', :content => 'This is a test message 2.', :client_id => '2' },
    { :to => '441234123456', :content => 'This is a test message 3.', :client_id => '3' },
    { :to => '441234123456', :content => 'This is a test message 4.', :client_id => '4' },
    { :to => '441234123456', :content => 'This is a test message 5.', :client_id => '5' },
    { :to => '441234123456', :content => 'This is a test message 6.', :client_id => '6' }
]

require 'clockwork'
api = Clockwork::API.new( 'API_KEY_GOES_HERE' ) #Be careful not to post your API Keys to public repositories.
messages.each do |m|
    api.messages.build(m)
end

responses = api.deliver
responses.each do |response|
    puts response.message.client_id
    if response.success
        puts response.message_id
    else
        puts response.error_code
        puts response.error_description
    end
end

Check balance

require 'clockwork'
api = Clockwork::API.new( 'API_KEY_GOES_HERE' ) #Be careful not to post your API Keys to public repositories.
balance = Clockwork::API.balance
puts balance # => { :account_type => "PAYG", :balance => 575.23, :currency => { :code => "GBP", :symbol => "£" } }

Help & Support

If you find a bug please file a Github issue with as much detail as you can or submit a pull request. If you need a bit of help or just fancy a chat drop us an email at [email protected].

License

This project is licensed under the MIT open-source license.

A copy of this license can be found in LICENSE.

Contributing

If you have any feedback on this wrapper drop us an email to [email protected].

The project is hosted on GitHub at http://www.github.com/mediaburst/clockwork-ruby.

If you would like to contribute a bug fix or improvement please fork the project and submit a pull request. Please add RSpec tests for your use case.

If we don't respond to your bug report or pull request within a few days please email [email protected] or remind @ClockworkSMS on Twitter, we probably haven't spotted the notification.

Test Setup

First, create a file at spec/spec_authentication_details containing the following:

YOUR_API_KEY_HERE

Substitute your own API key on line 1 of the file and replace the telephone numbers in the spec files with your own.

Then, run rspec.

Changelog

1.0.0 (18th July, 2012)

  • Initial release of wrapper [JI]

1.1.0 (10th September, 2012)

  • API#credit is now deprecated: use API#balance instead.

1.2.0 (30th June, 2014)

  • Compatability fixes for Ruby 1.8, 2.0 and 2.1 (Tested with 1.8.7-p375, 1.9.3-p547, 2.0.0-p481 and 2.1.2). Thanks to Paul Volpato, Todd Bealmear and Fawad for the pull requests.

1.2.1 (28th September, 2014)

  • Add some tests for the invalid_char_action and truncate parameters.
  • Fix invalid_char_action parameter as it was passing invalid values to the Clockwork API. Thanks to Tom Pesman for the fix.