README.md in twilio-ruby-4.13.0 vs README.md in twilio-ruby-5.0.0.alpha1

- old
+ new

@@ -1,41 +1,49 @@ -[![Gem Version](http://img.shields.io/gem/v/twilio-ruby.svg)][gem] +# twilio-ruby + [![Build Status](http://img.shields.io/travis/twilio/twilio-ruby.svg)][travis] +[![Gem Version](http://img.shields.io/gem/v/twilio-ruby.svg)][gem] [![Code Quality](http://img.shields.io/codeclimate/github/twilio/twilio-ruby.svg)][codeclimate] -# twilio-ruby - A module for using the Twilio REST API and generating valid [TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - Twilio Markup Language"). [Click here to read the full documentation.][documentation] ## Installation To install using [Bundler][bundler] grab the latest stable version: ```ruby -gem 'twilio-ruby', '~> 4.11.1' +gem 'twilio-ruby', '~> 5.0.0.rc26' ``` To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install: ```bash -gem install twilio-ruby +gem install twilio-ruby -v 5.0.0.rc26 ``` To build and install the development branch yourself from the latest source: ```bash git clone git@github.com:twilio/twilio-ruby.git cd twilio-ruby make install ``` -## Getting Started With REST +### Migration from 4.x +[Upgrade Guide][upgrade] +## Documentation +[Here][documentation] + +## Feedback +During the Release Candidate period of this library, please leave all feedback and issues in the [Github Issues][issues] for `twilio-ruby`. + +## Getting Started + ### Setup Work -``` ruby -require 'rubygems' # not necessary with ruby 1.9 but included for completeness +```ruby require 'twilio-ruby' # put your own credentials here account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' @@ -51,175 +59,90 @@ # and then you can create a new client without parameters @client = Twilio::REST::Client.new ``` -### Send an SMS +### Make a Call -``` ruby -@client.messages.create( +```ruby +@client.api.account.calls.create( from: '+14159341234', to: '+16105557069', - body: 'Hey there!' + url: 'http://example.com' ) ``` -### Send an MMS +### Send an SMS -``` ruby -@client.messages.create( +```ruby +@client.api.account.messages.create( from: '+14159341234', to: '+16105557069', - body: 'Hey there!', - media_url: 'http://example.com/smileyface.jpg' + body: 'Hey there!' ) ``` -### Do Some Stuff With Calls +### Customizing your HTTP Client +twilio-ruby uses [Faraday][faraday] to make HTTP requests. You can tell Twilio::REST::Client to use any of the Faraday adapters like so: -``` ruby -# make a new outgoing call -@call = @client.calls.create( - from: '+14159341234', - to: '+18004567890', - url: 'http://example.com/call-handler' -) - -# hangup a ringing call, but don't touch it if it's connected -@call.cancel - -# if you have the call sid, you can fetch a call object via: -@call = @client.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662') - -# redirect an in-progress call -@call.redirect_to('http://example.com/call-redirect') - -# hangup a call, no matter whether it is ringing or connected -@call.hangup +```ruby +@client.http_client.adapter = :typhoeus ``` -### List Calls after a certain time +## Getting Started With Client Capability Tokens -``` ruby -# list calls made or received on or after May 13, 2013 -@client.calls.list("start_time>" => "2013-05-13") # Notice we omit the "=" in the "start_time>=" parameter because it is automatically added -``` - -### Buy a Phone Number - -``` ruby -# print some available numbers -@numbers = @client.available_phone_numbers.get('US').local.list( - contains: 'AWESOME' -) -@numbers.each {|num| puts num.phone_number} - -# buy the first one -@number = @numbers[0].phone_number -@client.incoming_phone_numbers.create(phone_number: @number) -``` - -## Create a Task with TaskRouter - -If you need to create a Task to TaskRouter, you can do so by using the TaskRouterClient. - -Additional resources had off of the workspace object (task_queues, workers, workflows, activities, tasks, statistics, events). - -``` ruby -require 'rubygems' -require 'twilio-ruby' - -# put your own account credentials here: -account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' -workspace_sid = 'WSzzzzzzzzzzzzzzzzzzzzzzzzzzz' - -# set up a client -client = Twilio::REST::TaskRouterClient.new account_sid, auth_token, workspace_sid - -# create a task -workflow_sid = 'WWffffffffffffffffffffffffffff' -client.workspace.tasks.create(attributes: '{"foo": "bar"}', workflow_sid: "WWfffffffffffffffffffffffffffffff") -``` - -## Create a Twilio Client Capability Token - If you just need to generate a Capability Token for use with Twilio Client, you can do this: -``` ruby -require 'rubygems' # not necessary with ruby 1.9 but included for completeness +```ruby require 'twilio-ruby' # put your own account credentials here: account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' # set up -capability = Twilio::Util::Capability.new account_sid, auth_token +capability = Twilio::JWT::ClientCapability.new account_sid, auth_token + # allow outgoing calls to an application -capability.allow_client_outgoing 'AP89a0180a1a4ddf1da954efca349b7a20' +outgoingScope = Twilio::JWT::ClientCapability::OutgoingClientScope.new 'AP11111111111111111111111111111111' +capability.add_scope(outgoingScope) # allow incoming calls to 'andrew' -capability.allow_client_incoming 'andrew' +incomingScope = Twilio::JWT::ClientCapability::IncomingClientScope.new 'tom' +capability.add_scope(incomingScope) # generate the token string -@token = capability.generate +@token = capability.to_s ``` There is a slightly more detailed document in the [Capability][capability] section of the wiki. -## Lookup Phone Number information - -You can look up details on phone numbers with the Lookups API. - -```ruby -require 'twilio-ruby' - -# put your own credentials here -account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' -auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy' - -# set up a client to talk to the Twilio REST API -@lookups_client = Twilio::REST::LookupsClient.new account_sid, auth_token - -# lookup a number -number = @lookups_client.phone_numbers.get('+14159341234') - -# investigate the number -number.national_format -# => "(415) 934-1234" -number.country_code -# => "US" -``` - ## Getting Started With TwiML TwiML support is based on the [Builder][builder] library. You can construct a TwiML response like this: -``` ruby -require 'rubygems' # not necessary with ruby 1.9 but included for completeness +```ruby require 'twilio-ruby' -# build up a response -response = Twilio::TwiML::Response.new do |r| - r.Say 'hello there', voice: 'alice' - r.Dial callerId: '+14159992222' do |d| - d.Client 'jenny' +response = Twilio::TwiML::VoiceResponse.new do |r| + r.say('hello there', voice: 'alice') + r.dial(caller_id: '+14159992222') do |d| + d.client 'jenny' end end # print the result -puts response.text +puts response.to_s ``` This will print the following (except for the whitespace): -``` xml +```xml <?xml version="1.0" encoding="UTF-8"?> <Response> <Say voice="alice">hello there</Say> <Dial callerId="+14159992222"> <Client>jenny</Client> @@ -230,36 +153,24 @@ ## Supported Ruby Versions This library supports and is [tested against][travis] the following Ruby implementations: +- Ruby 2.4.0 +- Ruby 2.3.0 - Ruby 2.2.0 - Ruby 2.1.0 - Ruby 2.0.0 -- Ruby 1.9.3 -- [JRuby][jruby] -- [Rubinius][rubinius] -## Getting help - -If you need help installing or using the library, please contact Twilio Support at help@twilio.com first. Twilio's Support staff are well-versed in all of the Twilio Helper Libraries, and usually reply within 24 hours. - -If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo! - -## More Information - -There are more detailed examples in the included [examples][examples] -directory. Also for those upgrading, the [upgrade guide][upgrade] is available in the [twilio-ruby github wiki][wiki]. - [capability]: https://github.com/twilio/twilio-ruby/wiki/Capability [builder]: http://builder.rubyforge.org/ [examples]: https://github.com/twilio/twilio-ruby/blob/master/examples -[documentation]: http://twilio-ruby.readthedocs.org/en/latest -[upgrade]: https://github.com/twilio/twilio-ruby/wiki/UpgradeGuide +[documentation]: http://twilio.github.io/twilio-ruby [wiki]: https://github.com/twilio/twilio-ruby/wiki [bundler]: http://bundler.io [rubygems]: http://rubygems.org [gem]: https://rubygems.org/gems/twilio [travis]: http://travis-ci.org/twilio/twilio-ruby [codeclimate]: https://codeclimate.com/github/twilio/twilio-ruby -[jruby]: http://www.jruby.org -[rubinius]: http://rubini.us +[upgrade]: https://github.com/twilio/twilio-ruby/wiki/Ruby-Version-5.x-Upgrade-Guide +[issues]: https://github.com/twilio/twilio-ruby/issues +[faraday]: https://github.com/lostisland/faraday