What is it?

A Ruby interface to the Clickatell SMS gateway API.

Installing

Please note: this gem has been tested on *nix based systems including Linux, BSD and OSX. The sms utility was written with these systems in mind and will not work out of the box on Windows. The API should still work but has not been tested at this time. If you would like Windows support, please submit patches.

Download the latest version of gem or install using RubyGems.

$ sudo gem install clickatell

Getting the latest version from Subversion:

$ svn co svn://lukeredpath.co.uk/var/svn/opensource/clickatell/trunk clickatell-trunk

You can view the RDoc documentation and the code specs.

The basics

To use this gem, you will need sign up for an account at the Clickatell website. Once you are registered and logged into your account centre, you should add an HTTP API connection to your account. This will give you your API_ID.

Demonstration of usage

You can now use the library directly. You will need your API_ID as well as your account username and password.


require 'rubygems'
require 'clickatell'

api = Clickatell::API.authenticate('your_api_id', 'your_username', 'your_password')
api.send_message('447771234567', 'Hello from clickatell')

Full documentation for the API is available in the RDocs.

For debugging purposes, the API allows you to view gateway URIs as they are requested, printed to $stdout. You can enable this by turning on debug_mode.


Clickatell::API.debug_mode = true

Command-line SMS Utility

The Clickatell gem also comes with a command-line utility that will allow you to send an SMS directly from the command-line.

You will need to create a YAML configuration file in your home directory, in a file called .clickatell that resembles the following:


# ~/.clickatell
api_key: your_api_id
username: your_username
password: your_password

You can then use the sms utility to send a message to a single recipient:


$ sms 447771234567 'Hello from clickatell'

Alternatively, you can specify your authentication details manually by passing in options to the sms command.


$ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from clickatell'

These values will take presedence over any values in your ~/.clickatell file.

You can also specify the name or number that will appear in the “From” label on the recipients phone. You can either add a “from” key to your .clickatell file or manually using the—from option:


$ sms --from 'Luke Redpath' 447771234567 'Hello from clickatell'

The “from” option can either be a 16 digit number or an 11 character alpha-numeric string.

You can also use the sms utility to check your Clickatell account balance:


$ sms --show-balance

Whenever you send a message with the sms utility, it will return an alpha-numeric message ID. You can use this message ID to retrieve the message’s current status using the—status option:


$ sms --status 30b7d15bffb38695ba26e77c9c20f4ec

This will return a message status and message status code.

Run sms without any arguments for a full list of options.

License

This code is free to use under the terms of the MIT license.

Contact

Comments are welcome. Send an email to Luke Redpath email.