nibbme

= Nibbme - SMS web service proxy

The library is a simple {ActiveResource}[http://api.rubyonrails.org/classes/ActiveResource/Base.html]-based proxy that allows you to communicate with the {Nibbme bulk SMS web service}[http://www.nibbme.com]. {Nibbme}[http://www.nibbme.com] is a restfull-designed sistem and you can easily {create your own plugin/gem}[http://www.nibbme.com/wiki] based on the Wiki they provide. If you like plugins and gems read on :).

== Installation

The recommended way is to install a gem:

gem install nibbme

Add this line to your rails project's {RAILS_ROOT}/config/environment.rb:

config.gem 'nibbme'

Because Rails can't load rake tasks from gems open {RAILS_ROOT}/Rakefile and add this:

begin require 'nibbme/tasks' rescue LoadError STDERR.puts "Run rake gems:install to install nibbme" end

Open the console, go to your project's root and run the install task:

$ rake nibbme:install

The task creates a configuration file inside your {RAILS_ROOT}/config directory. Now open this file and set variables. The file should look something like this:

Nibbme configuration file

default: &defaults site: 'https://www.nibbme.com' email: [e-mail] password: mypassword

development: <<: *defaults

test: <<: *defaults

production: <<: *defaults

If you do not already have a Nibbme account then {sign up}[http://www.nibbme.com/account?m=signUp].

That's it! You are ready to rock&role.

== Examples

You will use this library like you use any other {ActiveResource}[http://api.rubyonrails.org/classes/ActiveResource/Base.html] classes.

=== Gateway

A "Simple SMS Gateway" controller is for single SMS delivery.

message = Nibbme::Message.create(:text => 'This is my SMS message.', :country_code => 44, :cell_phone => 99999999) message = Nibbme::Message.create(:text => 'This is my SMS message.', :country_code => 44, :cell_phone => 99999999, :full_name => 'John Rony')

Note that if a client (recipient) does not exist in your profile, he will be automatically created.

=== Groups

You can request data simply by calling a +find+ method.

groups = Nibbme::Group.find(:all) groups = Nibbme::Group.find(:first) groups = Nibbme::Group.find(:last) group = Nibbme::Group.find(15) # Where 15 is a Group ID number

Note that this will return only the items on the first page. You can pass the +page+ variable to get the items on the subpage. If the request is empty you know there is no more items.

Request the second page

groups = Nibbme::Group.find(:all, :params => { :page => 1 })

You can also filter the list through a +tags+ variable.

Request the second page but filter only the items containing the words 'sun' and 'fun'

groups = Nibbme::Group.find(:all, :params => { :page => 1, :tags => 'sun fun' })

You can check if an item exists by calling the +exists?+ method.

Check if the group with ID=1 exists

exists = Nibbme::Group.exists?(1)

You can also create, update and destroy groups.

Create an empty group

group = Nibbme::Group.create

Create a group with title and destription

group = Nibbme::Group.create(:title => 'School friends', :description => 'All my friends from the school in US.')

Update a group with ID=15

group = Nibbme::Group.find(15) group.title = 'Nibbme Members' group.save

Destroy a group with ID=12

group = Nibbme::Group.find(12) group.destroy

=== Clients

You can request data simply by calling a +find+ method.

clients = Nibbme::Client.find(:all) clients = Nibbme::Client.find(:first) clients = Nibbme::Client.find(:last) client = Nibbme::Client.find(15) # Where 15 is a Client ID number

Note that this will return only the items on the first page. You can pass the +page+ variable to get the items on the subpage. If the request is empty you know there is no more items.

Request the second page

clients = Nibbme::Client.find(:all, :params => { :page => 1 })

You can also filter the list through a +tags+ variable.

Request the second page but filter only the items containing the word 'john'

clients = Nibbme::Client.find(:all, :params => { :page => 1, :tags => 'john' })

You can check if an item exists by calling the +exists?+ method.

Check if the client with ID=1 exists

exists = Nibbme::Client.exists?(1)

You can also create, update and destroy clients.

Create an empty client

client = Nibbme::Client.create

Create a client with all information

client = Nibbme::Client.create(:cell_phone => '99999999', :country_id => 44, :name => 'John', :surname => 'Hill', :group_ids => '22,41,512')

Update a client with ID=15

client = Nibbme::Client.find(15) client.country_id = 44 client.save

Destroy a client with ID=12

client = Nibbme::Client.find(12) client.destroy

=== Messages

You can request data simply by calling a +find+ method.

messages = Nibbme::Message.find(:all) messages = Nibbme::Message.find(:first) messages = Nibbme::Message.find(:last) message = Nibbme::Message.find(15) # Where 15 is a Message ID number

Note that this will return only the items on the first page. You can pass the +page+ variable to get the items on the subpage. If the request is empty you know there is no more items.

Request the second page

messages = Nibbme::Message.find(:all, :params => { :page => 1 })

You can also filter the list through a +tags+ variable.

Request the second page but filter only the items containing the word 'john'

messages = Nibbme::Message.find(:all, :params => { :page => 1, :tags => 'john' })

You can check if an item exists by calling the +exists?+ method.

Check if the message with ID=1 exists

exists = Nibbme::Message.exists?(1)

You can also create, update and destroy messages.

Create an empty message

message = Nibbme::Message.create

Create a message with a full info

message = Nibbme::Message.create(:text => 'This is my SMS message.', :active_from => 3.hours.from_now, :group_ids => '21,44,5')

Update a message with ID=15

message = Nibbme::Message.find(15) message.text = 'Nibbme is rocks!' message.save

Destroy a message with ID=12

message = Nibbme::Message.find(12) message.destroy

You can queue a message by calling a +queue+ method.

Queue a message with ID=12

message = Nibbme::Message.find(12) message.queue

You can reset/restart the delivery process by calling a +reset+ method.

Reset delivery process for a message with ID=12

message = Nibbme::Message.find(12) message.reset

=== Error Handling

Similar to ActiveRecord all errors are logged as part of +errors+ variable.

Producing an error on the cell_phone field

message = Message.create(:cell_phone => 'aaaaa') message.errors[:cell_phone]

You can find more about error handling {here}[http://api.rubyonrails.org/classes/ActiveResource/Validations.html].

=== Logs (Tracking SMS Status)

You can request data simply by calling a +find+ method.

logs = Nibbme::SmsLog.find(:all) logs = Nibbme::SmsLog.find(:first) logs = Nibbme::SmsLog.find(:last) logs = Nibbme::SmsLog.find(15) # Where 15 is a SmsLog ID number

Note that this will return only the items on the first page. You can pass the +page+ variable to get the items on the subpage. If the request is empty you know there is no more items.

Request the second page

logs = Nibbme::SmsLog.find(:all, :params => { :page => 1 })

You can also filter the list through a +tags+ variable.

Request the second page but filter only the items containing the word '313'

logs = Nibbme::SmsLog.find(:all, :params => { :page => 1, :tags => '313' })

You can check if an item exists by calling the +exists?+ method.

Check if the SmsLog with ID=1 exists

exists = Nibbme::SmsLog.exists?(1)

Usually you will know a message and client ID. You can check an SMS status as follows

Find log for a message with ID=14 and client ID=50

log = Nibbme::SmsLog.find_one(14, 50)

Check if the message has been delivered

log.delivered?

Check if the message has failed

log.failed?

Show the message state

log.state

== Links

• Detailed information about the Nibbme web service is available on {the official Nibbme site}[http://www.nibbme.com].
• All the latest Nibbme news and tutorials are available on {the official Nibbme blog site}[http://blog.nibbme.com].
• You can find more about Nibbme integration on {the Nibbme WikiBook}[http://www.nibbme.com/wiki].