<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
<link rel="stylesheet" href="stylesheets/limechoc.css" type="text/css" media="screen" />
<script type="text/javascript" charset="utf-8" src="javascripts/codehighlighter/code_highlighter.js"></script>
<script type="text/javascript" charset="utf-8" src="javascripts/codehighlighter/ruby.js"></script>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Clickatell Ruby API</title>
</head>
<body>
<div id="wrapper">
<div id="container">
<div id="header">
<h1>Clickatell Ruby API <span class="version">0.5.0</span>
<span class="tagline">gem install clickatell</span></h1>
</div>
<div id="content">
<div class="article"><h3>What is it?</h3>
<p>A Ruby interface to the <a href="http://www.clickatell.com">Clickatell</a> SMS gateway <span class="caps">API</span>.</p>
<h3>Installing</h3>
<p><strong>Please note:</strong> this gem has been tested on *nix based systems including Linux, <span class="caps">BSD</span> and <span class="caps">OSX</span>. The <code>sms</code> utility was written with these systems in mind and will not work out of the box on Windows. The <span class="caps">API</span> should still work but has not been tested at this time. If you would like Windows support, please submit patches.</p>
<p>Download the <a href="http://rubyforge.org/projects/clickatell">latest version of gem</a> or install using RubyGems.</p>
<pre><code>$ sudo gem install clickatell</code></pre>
<h4>Clickatell on GitHub</h4>
<p>The source repository for clickatell has been <a href="http://github.com/lukeredpath/clickatell/">moved to GitHub</a>.</p>
<pre><code>git clone git://github.com/lukeredpath/clickatell.git</code></pre>
<p>You can still access the old subversion repository although this is unlikely to be updated:</p>
<pre><code>$ svn co svn://lukeredpath.co.uk/var/svn/opensource/clickatell/trunk clickatell-trunk</code></pre>
<p>You can view the <a href="/rdoc">RDoc documentation</a> and the <a href="/specs.html">code specs</a>.</p>
<h3>The basics</h3>
<p>To use this gem, you will need sign up for an account at <a href="http://www.clickatell.com">the Clickatell website</a>.
Once you are registered and logged into your account centre, you should add
an <span class="caps">HTTP API</span> connection to your account. This will give you your <span class="caps">API</span>_ID.</p>
<h3>Demonstration of usage</h3>
<p>You can now use the library directly. You will need your <span class="caps">API</span>_ID as well as your
account username and password.</p>
<pre><code class="ruby">
require 'rubygems'
require 'clickatell'
api = Clickatell::API.authenticate('your_api_id', 'your_username', 'your_password')
api.send_message('447771234567', 'Hello from clickatell')
</code></pre>
<p>Full documentation for the <span class="caps">API</span> is available in the <a href="rdoc/">RDocs</a>.</p>
<p>For debugging purposes, the <span class="caps">API</span> allows you to view gateway URIs as they are requested, printed to $stdout. You can enable this by turning on <ins>debug_mode</ins>.</p>
<pre><code class="ruby">
Clickatell::API.debug_mode = true
</code></pre>
<h4>Command-line <span class="caps">SMS</span> Utility</h4>
<p>The Clickatell gem also comes with a command-line utility that will allow you
to send an <span class="caps">SMS</span> directly from the command-line.</p>
<p>You will need to create a <span class="caps">YAML</span> configuration file in your home directory, in a
file called .clickatell that resembles the following:</p>
<pre><code>
# ~/.clickatell
api_key: your_api_id
username: your_username
password: your_password
</code></pre>
<p>You can then use the <ins>sms</ins> utility to send a message to a single recipient:</p>
<pre><code>
$ sms 447771234567 'Hello from clickatell'
</code></pre>
<p>Alternatively, you can specify your authentication details manually by passing in options to the <ins>sms</ins> command.</p>
<pre><code>
$ sms -u your_username -p your_password -k your_api_key 447771234567 'Hello from clickatell'
</code></pre>
<p>These values will take presedence over any values in your ~/.clickatell file.</p>
<p>You can also specify a custom Sender ID – 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:</p>
<pre><code>
$ sms --from 'Luke Redpath' 447771234567 'Hello from clickatell'
</code></pre>
<p>The “from” option can either be a 16 digit number or an 11 character alpha-numeric string.</p>
<p><strong>Important note about custom sender IDs:</strong> Since November 2007, Clickatell have implemented a policy whereby all Sender IDs must be registered in your account centre before they can be used (the mobile number that you signed up with will have automatically been registered). If you try to specify a custom sender ID that has not been registered, the <span class="caps">SMS</span> will not be delivered.</p>
<p>In addition, if you do not specify a sender ID, a default Clickatell number will be used instead. If you are using the sms utility to send messages from your own number, make sure you have added the ‘from’ field to your .clickatell file otherwise you will need to specify it every time you send a message.</p>
<p>You can also use the <ins>sms</ins> utility to check your Clickatell account balance:</p>
<pre><code>
$ sms --show-balance
</code></pre>
<p>Whenever you send a message with the <ins>sms</ins> 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:</p>
<pre><code>
$ sms --status 30b7d15bffb38695ba26e77c9c20f4ec
</code></pre>
<p>This will return a message status and message status code.</p>
<p>Run <ins>sms</ins> without any arguments for a full list of options.</p>
<h3>License</h3>
<p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
<h3>Contact</h3>
<p>Comments are welcome. Send an email to <a href="mailto:contact@lukeredpath.co.uk">Luke Redpath</a> email.</p></div>
</div>
</div>
<div id="footer_wrapper">
<div id="footer">
<p class="copyright">
<a href="http://rubyforge.org/projects/clickatell">Rubyforge Project Page</a> |
<a href="http://rubyforge.org/frs/?group_id=4295&release_id=13922">Download latest version (0.5.0)</a> |
<a href="rdoc/">RDoc</a>
</p>
</div>
</div>
</div>
</body>
</html>