README.rdoc in textmagic-0.2.2 vs README.rdoc in textmagic-0.3.0

- old
+ new

@@ -1,22 +1,25 @@ = TextMagic -Code[http://github.com/bobes/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: +Code[http://github.com/bobes/textmagic/tree/master] | -RDoc[http://textmagic.rubyforge.org] +Doc[http://bobes.github.com/textmagic/rdoc] | -Forum[http://groups.google.com/group/textmagic-api] -| -Issues[http://github.com/bobes/textmagic/issues] +Blame[http://bobes.github.com] -+textmagic+ gem is a Ruby interface to the TextMagic's Bulk SMS Gateway. -It can be used to send SMS messages and receive replies, check statuses -of sent messages and retrieve account balance. -You need to have a valid TextMagic[http://www.textmagic.com] account to use this gem. Sign up at -http://www.textmagic.com to get one. - == Installation Run gem install textmagic @@ -24,94 +27,108 @@ Use +sudo+ if required by your system. == Basic usage -To create an API instance, run: +Start with requiring +textmagic+ library: + require 'rubygems' + require 'textmagic' + +Then create an API instance with your credentials: + api = TextMagic::API.new(username, password) -with your credentials. Created instance will remember the username and password -and will use them in all requests to the SMS gateway. +These credentials will be used in all requests to the SMS gateway. === Account balance -To retrieve your account's balance, run: +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 Vilma!', '999314159265' + api.send 'Hi Wilma!', '999314159265' You can even specify multiple phone numbers: - api.send 'Hi everybody!', '999314159265', '999271828182' + 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. If you want to limit maximum number -of parts, you can specify an optional +max_length+ parameter: +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 long message...', '999314159265', :max_length => 2 + api.send 'Very very long message...', '999314159265', :max_length => 2 +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 respose to +send+ command. +returned in response to +send+ command. - api.send('Hi Vilma!', '999314159265').message_id + api.send('Hi Wilma!', '999314159265') # => '141421' - api.message_status('141421').status + status = api.message_status('141421') # => 'd' + status.completed_time + # => Fri May 22 10:10:18 +0200 2009 -You can also supply several message_ids, in which case you'll get a hash with -message_ids as keys: +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 Vilma!', '999314159265', '999271828182').message_ids - # => ['141421', '173205'] + api.send('Hi Wilma!', '999314159265', '999271828182').message_id + # => { '999314159265' => '141421', '999271828182' => '173205' } statuses = api.message_status('141421', '173205') - statuses['141421'].status - # => 'r' + # => { '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 encouraged to setup callbacks to receive updates on message status +instead of using this method.</b> + === Receiving replies To receive all available replies, run: - replies = api.receive.messages - # => [{ 'timestamp' => Fri May 22 12:12:55 +0200 2009, 'from' => '999314159265', 'text' => 'Hi Fred!', 'message_id' => '1780826' }] + replies = api.receive + # => ['999271828182: Hello Fred!', '999314159265: Good day!'] replies.first.text - # => 'Hi Fred!' + # => 'Hello Fred!' + replies.last.from + # => '999314159265' + replies.last.message_id + # => '223606' To prevent receiving old replies again, supply +last_retrieved_id+ argument: - replies = api.receive('1780826').messages + api.receive('178082') # => [] +See TextMagic::API.receive for more information on +message_status+ method. + +<b>It is strongly encouraged to setup callbacks to receive replies instead of +using this method.</b> + === Deleting retrieved replies After you retrieve replies, you can delete them from server by running: - message_ids = api.receive.message_ids - # => ['141421', '1780826'] - api.delete_reply '141421', '1780826' + api.delete_reply '141421', '178082' + # => true - -== Links - -The code is hosted at GitHub[http://github.com/bobes/textmagic] and released to -RubyForge[http://rubyforge.org/projects/textmagic]. -You can find documentation for the gem at project's homepage[http://textmagic.rubyforge.org] -at RubyForge. - -For general information on TextMagic's Bulk SMS Gateway, visit the -official API documentation[http://api.textmagic.com] or -Google group[http://groups.google.com/group/textmagic-api]. +See TextMagic::API.delete_reply for more information on +message_status+ method. == Copyright Copyright (c) 2009 Vladimír Bobeš Tužinský. See LICENSE for details.