= TextMagic

+textmagic+ gem is a Ruby interface to the TextMagic's Bulk SMS Gateway.
It can be used to easily integrate SMS features into your application.
It supports sending messages, receiving replies and more. You need to have
a valid TextMagic[http://www.textmagic.com] account to use this gem. You can
get one at http://www.textmagic.com.

To learn more about the TextMagic's Bulk
SMS Gateway, visit the official {API documentation}[http://api.textmagic.com]
or {Google group}[http://groups.google.com/group/textmagic-api].

Links:
Doc[http://tuzinsky.com/textmagic/rdoc]
|
Code[http://github.com/bobes/textmagic/tree/master]
|
Blame[http://tuzinsky.com]


== Installation

Run

  gem install textmagic

Use +sudo+ if required by your system.


== Basic usage

Start with requiring +textmagic+ library:

  require 'rubygems'
  require 'textmagic'

Then create an API instance with your credentials:

  api = TextMagic::API.new(username, password)

These credentials will be used in all requests to the SMS gateway.

=== Account balance

Check your account's balance:

  api.account.balance
  # => 314.15

See TextMagic::API.account for more information on +account+ method.

=== Sending messages

To send a message to a single phone number, run:

  api.send 'Hi Wilma!', '999314159265'

You can even specify multiple phone numbers:

  api.send 'Hello everybody', '999314159265', '999271828182'

Unicode messages are supported as well:

  api.send 'Вильма Привет!', '999314159265'

Long messages will be split to up to 3 parts. To limit maximum number
of parts, specify an optional +max_length+ parameter:

  api.send 'Very very long message...', '999314159265', :max_length => 2

If you want to postpone message delivery, specify a +send_time+ parameter:

  api.send 'Two hours later', '999314159265', :send_time => Time.now.to_i + 7200

See TextMagic::API.send for more information on +send+ method.

=== Checking sent message status

If you want to check sent message status, you have to use +message_id+
returned in response to +send+ command.

  api.send('Hi Wilma!', '999314159265')
  # => '141421'
  status = api.message_status('141421')
  # => 'd'
  status.completed_time
  # => Fri May 22 10:10:18 +0200 2009

You can also check statuses of several messages at once, in which case
you'll get a hash with message ids as keys:

  api.send('Hi Wilma!', '999314159265', '999271828182').message_id
  # => { '999314159265' => '141421', '999271828182' => '173205' }
  statuses = api.message_status('141421', '173205')
  # => { '141421' => 'r', '173205' => 'd' }
  statuses['173205'].created_time
  # => Thu May 28 16:41:45 +0200 2009

See TextMagic::API.message_status for more information on +message_status+ method.

<b>It is strongly recommended to setup callbacks to receive updates on message status
instead of using this method. Learn more about callbacks at
{TextMagic API}[http://api.textmagic.com/https-api] site</b>

=== Receiving replies

To receive all available replies, run:

  replies = api.receive
  # => ['999271828182: Hello Fred!', '999314159265: Good day!']
  replies.first.text
  # => 'Hello Fred!'
  replies.last.from
  # => '999314159265'
  replies.last.message_id
  # => '178082'

To prevent receiving old replies again, supply +last_retrieved_id+ argument:

  api.receive('178082')
  # => []

See TextMagic::API.receive for more information on +message_status+ method.

<b>It is strongly recommended to setup callbacks to receive replies instead of
using this method. Learn more about callbacks at
{TextMagic API}[http://api.textmagic.com/https-api] site</b>

=== Deleting retrieved replies

After you retrieve replies, you can delete them from server by running:

  api.delete_reply '141421', '178082'
  # => true

See TextMagic::API.delete_reply for more information on +message_status+ method.


== Command-line utility

The +textmagic+ gem also features a handy command-line utility. It gives you access
to all of the gem's features. Run

  tm

from your console to see help on its usage.

<i>Note: This has only been tested on a Mac. If you have any troubles using this
utility, contact the author (or submit a patch).</i>

== Copyright

Copyright (c) 2009 Vladimír Bobeš Tužinský. See LICENSE for details.