= inteltech_sms

InteltechSms is a ruby gem that provides an InteltechSms class to check credit and send SMS text messages to single or multiple recipients.

== Installation

As a Plugin (eg rails 2.3.x)

    % cd vendor/plugins
    % git clone git://github.com/ianheggie/inteltech_sms.git

As a Gem from gemcutter

    % gem install inteltech_sms

== Usage

You will require an account with http://inteltech.com.au for the username and secret key - They offer a free trial so you can try before buying.

Note: Inteltech's gateway assumes numbers not in international format (ie starting with a plus sign) are australian numbers.

Example ruby code:

    require 'rubygems'

    require 'inteltech_sms'

    username = ENV['SMS_USERNAME'] || abort("Missing SMS_USERNAME env variable")
    secure_key = ENV['SMS_KEY'] || abort("Missing SMS_KEY env variable")

    test_sms = '0411111111'
    test_sms2 = '+8611111111111'
    landline_sms = '0862252608' # Inteltech's landline number

    gateway = InteltechSms.new(username, secure_key)

    credit = gateway.get_credit.inspect

    puts "You have #{credit} Credit/s left"

    begin
      res = gateway.send_sms(test_sms,'Test from Ruby')
      puts "send_sms to #{res.sms} was successfull."
    rescue ex => InteltechSms::Error
      puts "send_sms to #{res.sms} failed. Gateway response #{ex.response.class} with code #{ex.response.response_code}."
    end

    res2 = gateway.send_multiple_sms([test_sms, test_sms2, landline_sms],'Test from Ruby to multiple numbers')

    puts "send_multiple_sms (sending to mobiles should work, sending to a landline should fail):"
    puts res2.collect {|r| "sms to #{r.sms} #{r.success? ? 'was successfull' : "failed (#{r.class} with code #{r.response_code})"}."}.join("\n")

=== Dummy for testing

A Dummy class is also provided for use with tests. The dummy class will return a response based on the response code given. 
Instantiate an instance of the DummyInteltechSms, passing the initial credit, and optionally the response code.
Sms messages will be logged to stdout unless log_to_stdout is set to false.

Example ruby code:

    require 'rubygems'

    require 'dummy_inteltech_sms'

    test_sms = '123'

    gateway = DummyInteltechSms.new(1)

    credit = gateway.get_credit.inspect

    puts "You have #{credit} Credit/s left"

    res = gateway.send_sms(test_sms,'Test from Ruby')
    puts "send_sms to #{res.sms} was successfull."

    credit = gateway.get_credit.inspect
    puts "You have #{credit} Credit/s left"

    begin
      # This will return no credit
      res = gateway.send_sms(test_sms,'Test from Ruby')
      puts "send_sms to #{res.sms} was successfull."
    rescue ex => InteltechSms::Error
      puts "send_sms to #{res.sms} failed. Gateway response #{ex.response.class} with code #{ex.response.response_code}."
    end

    res2 = gateway.send_multiple_sms([test_sms, test_sms2, landline_sms],'Test from Ruby to multiple numbers')

    gateway.response_code = InteltechSms::UNAUTHORIZED_RESPONSE_CODE
    # OR
    gateway = DummyInteltechSms.new(1,InteltechSms::UNAUTHORIZED_RESPONSE_CODE)

    puts "send_multiple_sms (sending to mobiles should work, sending to a landline should fail):"
    puts res2.collect {|r| "sms to #{r.sms} #{r.success? ? 'was successfull' : "failed (#{r.class} with code #{r.response_code})"}."}.join("\n")

=== Optional arguments

There are a few optional parameters that the gateway will accept.

• senderid – 15 character custom sender ID which can be a mobile number or a alphanumeric string.
e.g. send message from MYCOMPANY. (Additional cost of 0.5 credits/message applies).
Do not use spaces. If left blank, a random mobile number will be used.

• schedule – Allows you to schedule a message delivery. Must be in unix format. e.g. 1348742950 (Use Time.now.utc.to_i to get the current time)

These are passed to the send_sms and send_multiple_sms methods via an optional hash argument:

    # To schedule the sms in 12 minutes time ...

    res = gateway.send_sms(test_sms,'Test from Ruby', :schedule => Time.now.utc.to_i + (12 * 60))

    # To schedule the sms and supply a custom sender id

    res2 = gateway.send_multiple_sms([test_sms, test_sms2, landline_sms],'Test from Ruby to multiple numbers', :senderid => 'MYCOMPANY', :schedule => 1348742950)

== Continuous integration tests

* Travis CI testing result: {<img src="https://travis-ci.org/ianheggie/inteltech_sms.png" />}[https://travis-ci.org/ianheggie/inteltech_sms]
* Code Coverage: {<img src="https://coveralls.io/repos/ianheggie/inteltech_sms/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/ianheggie/inteltech_sms]

== Contributing to inteltech_sms

* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
* Fork the project.
* Start a feature/bugfix branch.
* Commit and push until you are happy with your contribution.
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2013 Ian Heggie - MIT License. See LICENSE.txt for further details.

=== Known issues

* The SMS Gateway no longer responds with 2015 Bad number when a mobile number is not connected. The gateway accepts the request and charges for it, then posts the failure in the history log. (Previously tested using numbers reserved for fictitious use in films and books etc - tests are now disabled)
* The SMS Gateway no longer responds with 2006 Unathorized when a blank username is submitted (An internal 2102 error is returned instead).

=== Main Contributors

* Ian Heggie - Developer - Heggie Enterprises Pty Ltd - Contributed development of tests and packaging as gem
* Timelapse Pty Ltd (timelapse.com.au) - Paid for development of lib/inteltech_sms.rb and released code for public use

=== Other/Ongoing Contributors

* Intelligent Technologies (inteltech.com.au) - Contributed an hour and 5% commission to development costs