twilio-ruby 4.6.1 → 6.9.0

data/README.md

@@ -1,23 +1,51 @@
-[![Gem Version](http://img.shields.io/gem/v/twilio-ruby.svg)][gem]
-[![Build Status](http://img.shields.io/travis/twilio/twilio-ruby.svg)][travis]
-[![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]
+[![Tests](https://github.com/twilio/twilio-ruby/actions/workflows/test-and-deploy.yml/badge.svg)][github-actions]
+[![Gem Version](https://img.shields.io/gem/v/twilio-ruby.svg)](https://rubygems.org/gems/twilio-ruby)
+[![Learn with TwilioQuest](https://img.shields.io/static/v1?label=TwilioQuest&message=Learn%20to%20contribute%21&color=F22F46&labelColor=1f243c&style=flat-square&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAMAAAD04JH5AAAASFBMVEUAAAAZGRkcHBwjIyMoKCgAAABgYGBoaGiAgICMjIyzs7PJycnMzMzNzc3UoBfd3d3m5ubqrhfrMEDu7u739/f4vSb/3AD///9tbdyEAAAABXRSTlMAAAAAAMJrBrEAAAKoSURBVHgB7ZrRcuI6EESdyxXGYoNFvMD//+l2bSszRgyUYpFAsXOeiJGmj4NkuWx1Qeh+Ekl9DgEXOBwOx+Px5xyQhDykfgq4wG63MxxaR4ddIkg6Ul3g84vCIcjPBA5gmUMeXESrlukuoK33+33uID8TWeLAdOWsKpJYzwVMB7bOzYSGOciyUlXSn0/ABXTosJ1M1SbypZ4O4MbZuIDMU02PMbauhhHMHXbmebmALIiEbbbbbUrpF1gwE9kFfRNAJaP+FQEXCCTGyJ4ngDrjOFo3jEL5JdqjF/pueR4cCeCGgAtwmuRS6gDwaRiGvu+DMFwSBLTE3+jF8JyuV1okPZ+AC4hDFhCHyHQjdjPHUKFDlHSJkHQXMB3KpSwXNGJPcwwTdZiXlRN0gSp0zpWxNtM0beYE0nRH6QIbO7rawwXaBYz0j78gxjokDuv12gVeUuBD0MDi0OQCLvDaAho4juP1Q/jkAncXqIcCfd+7gAu4QLMACCLxpRsSuQh0igu0C9Svhi7weAGZg50L3IE3cai4IfkNZAC8dfdhsUD3CgKBVC9JE5ABAFzg4QL/taYPAAWrHdYcgfLaIgAXWJ7OV38n1LEF8tt2TH29E+QAoDoO5Ve/LtCQDmKM9kPbvCEBApK+IXzbcSJ0cIGF6e8gpcRhUDogWZ8JnaWjPXc/fNnBBUKRngiHgTUSivSzDRDgHZQOLvBQgf8rRt+VdBUUhwkU6VpJ+xcOwQUqZr+mR0kvBUgv6cB4+37hQAkXqE8PwGisGhJtN4xAHMzrsgvI7rccXqSvKh6jltGlrOHA3Xk1At3LC4QiPdX9/0ndHpGVvTjR4bZA1ypAKgVcwE5vx74ulwIugDt8e/X7JgfkucBMIAr26ndnB4UCLnDOqvteQsHlgX9N4A+c4cW3DXSPbwAAAABJRU5ErkJggg==)](https://twil.io/learn-open-source)
+
+## Documentation
+
+The documentation for the Twilio API can be found [here][apidocs].
+
+The individual releases [here][refdocs].
+
+## Versions
+
+`twilio-ruby` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.
+
+### 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
+
+### Migrating from 5.x
+
+[Upgrade Guide][upgrade]
 
 ## Installation
 
 To install using [Bundler][bundler] grab the latest stable version:
 
 ```ruby
-gem 'twilio-ruby', '~> 4.2.1'
+gem 'twilio-ruby', '~> 6.9.0'
 ```
 
 To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install:
 
 ```bash
-gem install twilio-ruby
+gem install twilio-ruby -v 6.9.0
 ```
 
 To build and install the development branch yourself from the latest source:
@@ -28,196 +56,271 @@ cd twilio-ruby
 make install
 ```
 
-## Getting Started With REST
+> **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 twilio-ruby`
+
+### Test your installation
 
-### Setup Work
+To make sure the installation was successful, try sending yourself an SMS message, like this:
 
-``` ruby
-require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+```rb
+require "twilio-ruby"
+
+# Your Account SID and Auth Token from console.twilio.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 Twilio 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](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
+
+## Usage
+
+### Authenticate the Client
+
+```ruby
 require 'twilio-ruby'
 
-# put your own credentials here
+# Your Account SID and Auth Token from console.twilio.com
 account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
 auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
 
-# set up a client to talk to the Twilio REST API
+# Initialize the Twilio Client with your credentials
 @client = Twilio::REST::Client.new account_sid, auth_token
+```
 
-# alternatively, you can preconfigure the client like so
-Twilio.configure do |config|
-  config.account_sid = account_sid
-  config.auth_token = auth_token
-end
+### Use An API Key
+
+```ruby
+require 'twilio-ruby'
 
-# and then you can create a new client without parameters
-@client = Twilio::REST::Client.new
+# Your Account SID from console.twilio.com
+account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+# API Key from twilio.com/console/project/api-keys
+api_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz'
+api_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
+
+# set up a client to talk to the Twilio REST API using an API Key
+@client = Twilio::REST::Client.new api_key_sid, api_key_secret, account_sid
 ```
 
-### Send an SMS
+### Specify a Region and/or Edge
 
-``` ruby
-@client.messages.create(
+To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:
+
+```ruby
+# set up a client to talk to the Twilio REST API over a specific region and edge
+@client = Twilio::REST::Client.new account_sid, auth_token, nil, 'au1'
+@client.edge = 'sydney'
+
+# you may also specify the region and/or edge after client creation
+@client = Twilio::REST::Client.new account_sid, auth_token
+@client.region = 'au1'
+@client.edge = 'sydney'
+```
+
+This will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`.
+
+### Make a Call
+
+```ruby
+@client.calls.create(
   from: '+14159341234',
   to: '+16105557069',
-  body: 'Hey there!'
+  url: 'http://example.com'
 )
 ```
 
-### Send an MMS
+### Send an SMS
 
-``` ruby
+```ruby
 @client.messages.create(
   from: '+14159341234',
   to: '+16105557069',
-  body: 'Hey there!',
-  media_url: 'http://example.com/smileyface.jpg'
+  body: 'Hey there!'
 )
 ```
 
-### Do Some Stuff With Calls
+### List your SMS Messages
 
-``` ruby
-# make a new outgoing call
-@call = @client.calls.create(
-  from: '+14159341234',
-  to: '+18004567890',
-  url: 'http://example.com/call-handler'
-)
+```ruby
+@client.messages.list(limit: 20)
+```
 
-# hangup a ringing call, but don't touch it if it's connected
-@call.cancel
+### Fetch a single SMS message by Sid
 
-# if you have the call sid, you can fetch a call object via:
-@call = @client.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662')
+```ruby
+# put the message sid you want to retrieve here:
+message_sid = 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+@client.messages(message_sid).fetch
+```
 
-# redirect an in-progress call
-@call.redirect_to('http://example.com/call-redirect')
+### Iterate through records
 
-# hangup a call, no matter whether it is ringing or connected
-@call.hangup
-```
+The library automatically handles paging for you. Collections, such as `calls` and `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 Calls after a certain time
+`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.
 
-``` 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
-```
+For more information about these methods, view the [auto-generated library docs](https://www.twilio.com/docs/libraries/reference/twilio-ruby).
 
-### Buy a Phone Number
+```rb
+require 'twilio-ruby'
 
-``` ruby
-# print some available numbers
-@numbers = @client.available_phone_numbers.get('US').local.list(
-  contains: 'AWESOME'
-)
-@numbers.each {|num| puts num.phone_number}
+account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+auth_token = 'your_auth_token'
+
+@client = Twilio::REST::Client.new(account_sid, auth_token)
 
-# buy the first one
-@number = @numbers[0].phone_number
-@client.incoming_phone_numbers.create(phone_number: @number)
+@client.calls.list
+       .each do |call|
+         puts call.direction
+       end
 ```
 
-## Create a Task with TaskRouter
+### Enable Debug logging
 
-If you need to create a Task to TaskRouter, you can do so by using the TaskRouterClient.
+In order to enable debug logging, pass in a 'logger' instance to the client with the level set to at least 'DEBUG'
+
+```ruby
+@client = Twilio::REST::Client.new account_sid, auth_token
+myLogger = Logger.new(STDOUT)
+myLogger.level = Logger::DEBUG
+@client.logger = myLogger
+
+@client = Twilio::REST::Client.new account_sid, auth_token
+myLogger = Logger.new('my_log.log')
+myLogger.level = Logger::DEBUG
+@client.logger = myLogger
+```
 
-Additional resources had off of the workspace object (task_queues, workers, workflows, activities, tasks, statistics, events).
+### Handle Exceptions {#exceptions}
 
-``` ruby
-require 'rubygems'
+If the Twilio API returns a 400 or a 500 level HTTP response, the `twilio-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.
+
+```rb
 require 'twilio-ruby'
 
-# put your own account credentials here:
-account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
-auth_token  = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
-workspace_sid = 'WSzzzzzzzzzzzzzzzzzzzzzzzzzzz'
+account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+auth_token = 'your_auth_token'
 
-# set up a client
-client = Twilio::REST::TaskRouterClient.new account_sid, auth_token, workspace_sid
+@client = Twilio::REST::Client.new account_sid, auth_token
 
-# create a task
-workflow_sid = 'WWffffffffffffffffffffffffffff'
-client.workspace.tasks.create(attributes: '{"foo": "bar"}', workflow_sid: "WWfffffffffffffffffffffffffffffff")
+begin
+  messages = @client.messages.list(limit: 20)
+rescue Twilio::REST::RestError => e
+  puts e.message
+end
 ```
 
-## Create a Twilio Client Capability Token
+### 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.
 
-If you just need to generate a Capability Token for use with Twilio Client, you
-can do this:
+For example, you can retrieve the status code of the last response like so:
 
-``` ruby
-require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+```ruby
+require 'rubygems' # Not necessary with ruby 1.9 but included for completeness
 require 'twilio-ruby'
 
-# put your own account credentials here:
-account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
-auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
+# Your Account SID and Auth Token from console.twilio.com
+account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+auth_token = 'your_auth_token'
 
-# set up
-capability = Twilio::Util::Capability.new account_sid, auth_token
+@client = Twilio::REST::Client.new(account_sid, auth_token)
 
-# allow outgoing calls to an application
-capability.allow_client_outgoing 'AP89a0180a1a4ddf1da954efca349b7a20'
+@message = @client.messages.create(
+  to: '+14158675309',
+  from: '+14258675310',
+  body: 'Ahoy!'
+)
 
-# allow incoming calls to 'andrew'
-capability.allow_client_incoming 'andrew'
+# Retrieve the status code of the last response from the HTTP client
+puts @client.http_client.last_response.status_code
+```
 
-# generate the token string
-@token = capability.generate
+### Customize 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
+@client.http_client.adapter = :typhoeus
 ```
 
-There is a slightly more detailed document in the [Capability][capability]
-section of the wiki.
+To use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md).
+
+To apply customizations such as middleware, you can use the `configure_connection` method like so:
+
+```ruby
+@client.http_client.configure_connection do |faraday|
+  faraday.use SomeMiddleware
+end
+```
 
-## Lookup Phone Number information
+### Get started With Client Capability Tokens
 
-You can look up details on phone numbers with the Lookups API.
+If you just need to generate a Capability Token for use with Twilio Client, you can do this:
 
 ```ruby
 require 'twilio-ruby'
 
-# put your own credentials here
+# put your own account 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
+# set up
+capability = Twilio::JWT::ClientCapability.new account_sid, auth_token
+
+# allow outgoing calls to an application
+outgoing_scope = Twilio::JWT::ClientCapability::OutgoingClientScope.new 'AP11111111111111111111111111111111'
+capability.add_scope(outgoing_scope)
 
-# lookup a number
-number = @lookups_client.phone_numbers.get('+14159341234')
+# allow incoming calls to 'andrew'
+incoming_scope = Twilio::JWT::ClientCapability::IncomingClientScope.new 'andrew'
+capability.add_scope(incoming_scope)
 
-# investigate the number
-number.national_format
-# => "(415) 934-1234"
-number.country_code
-# => "US"
+# generate the token string
+@token = capability.to_s
 ```
 
-## Getting Started With TwiML
+There is a slightly more detailed document in the [Capability][capability] section of the wiki.
 
-TwiML support is based on the [Builder][builder] library. You can construct a
-TwiML response like this:
+### Generate TwiML
 
-``` ruby
-require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+To control phone calls, your application needs to output [TwiML][twiml].
+
+You can construct a TwiML response like this:
+
+```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(message: '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>
@@ -227,39 +330,26 @@ This will print the following (except for the whitespace):
 </Response>
 ```
 
-## Supported Ruby Versions
+## Docker Image
 
-This library supports and is [tested against][travis] the following Ruby
-implementations:
-
-- Ruby 2.2.0
-- Ruby 2.1.0
-- Ruby 2.0.0
-- Ruby 1.9.3
-- [JRuby][jruby]
-- [Rubinius][rubinius]
+The `Dockerfile` present in this repository and its respective `twilio/twilio-ruby` Docker image are currently used by Twilio for testing purposes only.
 
 ## 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 need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question.
 
 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
+[apidocs]: https://www.twilio.com/docs/api
+[twiml]: https://www.twilio.com/docs/api/twiml
+[libdocs]: https://www.twilio.com/docs/libraries/reference/twilio-ruby/
+[refdocs]: https://twilio.github.io/twilio-ruby
+[capability]: https://github.com/twilio/twilio-ruby/wiki/JWT-Tokens
 [wiki]: https://github.com/twilio/twilio-ruby/wiki
-[bundler]: http://bundler.io
-[rubygems]: http://rubygems.org
+[bundler]: https://bundler.io
+[rubygems]: https://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
+[github-actions]: https://github.com/twilio/twilio-ruby/actions/workflows/test-and-deploy.yml
+[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

data/UPGRADE.md

@@ -0,0 +1,40 @@
+# Upgrade Guide
+
+_After `5.0.0` all `MINOR` and `MAJOR` version bumps will have upgrade notes
+posted here._
+
+[2023-05-03] 5.x.x to 6.x.x
+-----------------------------
+### Overview
+
+##### Twilio Ruby Helper Library’s major version 6.0.0 is now available. We ensured that you can upgrade to Ruby helper Library 6.0.0 version without any breaking changes
+
+Behind the scenes Ruby Helper is now auto-generated via OpenAPI with this release. This  enables us to rapidly add new features and enhance consistency across versions and languages.
+
+To learn more about the Ruby Helper Library, check out [our docs](https://www.twilio.com/docs/libraries/ruby).
+
+[2017-09-29] 5.x.x to 5.3.x
+---------------------------
+
+### CHANGED - `Body` parameter on Chat `Message` creation is no longer required.
+
+#### Rationale
+This was changed to add support for sending media in Chat messages, users can now either provide a `body` or a `media_sid`.
+
+#### 5.x.x
+```ruby
+require 'twilio-ruby'
+
+@client = Twilio::REST::Client.new "AC123", "auth"
+@client.chat.v2.service('IS123').channel('CH123').message.create("this is the body", "from")
+```
+
+#### 5.3.x
+```ruby
+require 'twilio-ruby'
+
+@client = Twilio::REST::Client.new "AC123", "auth"
+@client.chat.v2.service('IS123').channel('CH123').message.create("from", body:"this is the body")
+```
+
+

data/VERSIONS.md

@@ -0,0 +1,35 @@
+# Versioning Strategy
+
+`twilio-ruby` uses a modified version of [Semantic Versioning][semver] for
+all changes to the helper library. It is strongly encouraged that you pin at
+least the major version and potentially the minor version to avoid pulling in
+breaking changes.
+
+Semantic Versions take the form of `MAJOR.MINOR.PATCH`
+
+When bugs are fixed in the library in a backwards-compatible way, the `PATCH`
+level will be incremented by one. When new features are added to the library
+in a backwards-compatible way, the `PATCH` level will be incremented by one.
+`PATCH` changes should _not_ break your code and are generally safe for upgrade.
+
+When a new large feature set comes online or a small breaking change is
+introduced, the `MINOR` version will be incremented by one and the `PATCH`
+version reset to zero. `MINOR` changes _may_ require some amount of manual code
+change for upgrade. These backwards-incompatible changes will generally be
+limited to a small number of function signature changes.
+
+The `MAJOR` version is used to indicate the family of technology represented by
+the helper library. Breaking changes that require extensive reworking of code
+will cause the `MAJOR` version to be incremented by one, and the `MINOR` and
+`PATCH` versions will be reset to zero. Twilio understands that this can be very
+disruptive, so we will only introduce this type of breaking change when
+absolutely necessary. New `MAJOR` versions will be communicated in advance with
+`Release Candidates` and a schedule.
+
+## Supported Versions
+
+Only the current `MAJOR` version of `twilio-ruby` is supported. New
+features, functionality, bug fixes, and security updates will only be added to
+the current `MAJOR` version.
+
+[semver]: https://semver.org