whoosh-ruby
Supported Ruby Versions
This library supports the following Ruby implementations:
- Ruby 2.4
- Ruby 2.5
- Ruby 2.6
- Ruby 2.7
- Ruby 3.0
- Ruby 3.1
Ruby 3.2
JRuby 9.2
JRuby 9.3
JRuby 9.4
Installation
To install using [Bundler][bundler] grab the latest stable version:
gem 'whoosh-ruby', '~> 0.1.5'
To manually install whoosh-ruby
via [Rubygems][rubygems] simply gem install:
gem install whoosh-ruby -v 0.1.5
Info If the command line gives you an error message that says Permission Denied, try running the above commands with sudo.
For example:
sudo gem install whoosh-ruby
Test your installation
To make sure the installation was successful, try sending yourself an SMS message, like this:
require "twilio-ruby"
# Your Account SID and Auth Token from console.whoosh.totogidemos.com
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"
@client = Twilio::REST::Client.new account_sid, auth_token
message = @client.messages.create(
body: "Hello from Ruby",
to: "+12345678901", # Text this number
from: "+15005550006", # From a valid Whoosh number
)
puts message.sid
Warning It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out How to Set Environment Variables for more information.
Usage
Authenticate the Client
require 'twilio-ruby'
# Your Account SID and Auth Token from console.whoosh.totogidemos.com
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
# Initialize the Whoosh Client with your credentials
@client = Twilio::REST::Client.new account_sid, auth_token
Send an SMS
@client..create(
from: '+14159341234',
to: '+16105557069',
body: 'Hey there!'
)
List your SMS Messages
@client..list(limit: 20)
Fetch a single SMS message by Sid
# put the message sid you want to retrieve here:
= 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
@client.().fetch
Iterate through records
The library automatically handles paging for you. Collections, such as messages
, have list
and stream methods that page under the hood. With both list
and stream
, you can specify the number of records you want to receive (limit
) and the maximum size you want each page fetch to be (page_size
). The library will then handle the task for you.
list
eagerly fetches all records and returns them as a list, whereas stream
returns an enumerator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the page
method.
For more information about these methods, view the auto-generated library docs.
Handle Exceptions #exceptions
If the Whoosh API returns a 400 or a 500 level HTTP response, the whoosh-ruby
library will throw a Twilio::REST::RestError
. 400-level errors are normal
during API operation (“Invalid number”
, “Cannot deliver SMS to that number”
,
for example) and should be handled appropriately.
require 'twilio-ruby'
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token
begin
messages = @client.messages.list(limit: 20)
rescue Twilio::REST::RestError => e
puts e.message
end
Debug API requests
To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.
For example, you can retrieve the status code of the last response like so:
require 'rubygems' # Not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'
# Your Account SID and Auth Token from console.whoosh.totogidemos.com
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new(account_sid, auth_token)
@message = @client..create(
to: '+14158675309',
from: '+14258675310',
body: 'Ahoy!'
)
# Retrieve the status code of the last response from the HTTP client
puts @client.http_client.last_response.status_code
Customize your HTTP Client
whoosh-ruby
uses [Faraday][faraday] to make HTTP requests. You can tell Twilio::REST::Client
to use any of the Faraday adapters like so:
@client.http_client.adapter = :typhoeus
To use a custom HTTP client with this helper library, please see the advanced example of how to do so.
To apply customizations such as middleware, you can use the configure_connection
method like so:
@client.http_client.configure_connection do |faraday|
faraday.use SomeMiddleware
end
Getting help
If you've found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!