twilio-ruby 4.6.1 → 6.9.0

data/docs/usage/phone-calls.rst

@@ -1,185 +0,0 @@
-.. module:: twilio.rest
-.. _phone-calls:
-
-=====================
-Phone Calls
-=====================
-
-The :class:`Calls` resource manages all interaction with Twilio phone calls,
-including the creation and termination of phone calls.
-
-
-Making a Phone Call
--------------------
-
-The :class:`Calls` resource allows you to make outgoing calls. Before a call
-can be successfully started, you'll need a to set up a url endpoint which
-outputs valid `TwiML <http://www.twilio.com/docs/api/twiml/>`_.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @call = @client.calls.create(
-      to: "9991231234",
-      from: "9991231234",
-      url: "http://foo.com/call.xml"
-    )
-    puts @call.length
-    puts @call.sid
-
-
-Retrieve a Call Record
--------------------------
-
-If you already have a :class:`Call` sid,
-you can use the client to retrieve that record.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    sid = "CA12341234"
-    @call = @client.calls.get(sid)
-
-Delete a Call Record
---------------------
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    sid = "CA12341234"
-    @call = @client.calls.get(sid)
-
-    # Removes the entire record from Twilio's storage
-    @call.delete
-
-Accessing Specific Call Resources
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each :class:`Call` resource also has access to its `notifications`,
-`recordings`, and `transcriptions`.
-These attributes are :class:`ListResources`,
-just like the :class:`Calls` resource itself.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    sid = "CA12341234"
-    @call = @client.calls.get(sid)
-
-    puts @call.notifications.list()
-    puts @call.recordings.list()
-    puts @call.transcriptions.list()
-
-However, what if you only have a `CallSid`, and not the actual
-:class:`Resource`? No worries, as :meth:`list` can be filter based on a given
-`CallSid`.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    sid = "CA24234"
-    puts @client.notifications.list(call: sid)
-    puts @client.recordings.list(call: sid)
-    puts @client.transcriptions.list(call: sid)
-
-
-Modifying Live Calls
---------------------
-
-The :class:`Call` resource makes it easy to find current live calls and
-redirect them as necessary
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @calls = @client.calls.list(status: "in-progress")
-
-    @calls.each do |call|
-      call.redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
-    end
-
-
-Ending all live calls is also possible
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @calls = @client.calls.list(status: "in-progress")
-
-    @calls.each do |call|
-      call.hangup()
-    end
-
-Note that :meth:`hangup` will also cancel calls currently queued.
-
-If you already have a :class:`Call` sid, you can use the :class:`Calls`
-resource to update the record without having to use :meth:`get` first.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    sid = "CA12341234"
-    @client.calls.get(sid).redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
-
-Hanging up the call also works.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    sid = "CA12341234"
-    @client.calls.get(sid).hangup()
-

data/docs/usage/phone-numbers.rst

@@ -1,189 +0,0 @@
-.. module:: twilio.rest.resources
-
-=================
-Phone Numbers
-=================
-
-With Twilio you can search and buy real phone numbers, just using the API.
-
-For more information, see the
-`IncomingPhoneNumbers REST Resource
-<http://www.twilio.com/docs/api/rest/incoming-phone-numbers>`_ documentation.
-
-
-Searching and Buying a Number
---------------------------------
-
-Finding numbers to buy couldn't be easier.
-We first search for a US number in area code 530.
-Once we find one, we'll purchase it for our account.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    numbers = @client.available_phone_numbers.get('US').list(area_code: "530")
-
-    if numbers.any?
-      numbers[0].purchase()
-    else
-      puts "No numbers in 530 available"
-    end
-
-
-Local, Toll-Free, and Mobile Numbers
-------------------------------------
-
-By default, :meth:`PhoneNumbers.search` looks for local phone numbers. You can
-search for different types of numbers by using a type subresource.
-
-Available subresources for AvailablePhoneNumbers are:
-- `local`
-- `toll_free`
-- `mobile`
-
-You can search for numbers for a given type.
-
-.. code-block:: ruby
-
-    # local
-    numbers = @client.available_phone_numbers.get('US').local.list()
-
-    # toll free
-    numbers = @client.available_phone_numbers.get('US').toll_free.list()
-
-    # mobile
-    numbers = @client.available_phone_numbers.get('UK').mobile.list()
-
-Numbers Containing Words
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Phone number search also supports looking for words inside phone numbers.
-The following example will find any phone number with "FOO" in it.
-
-.. code-block:: ruby
-
-    numbers = @client.available_phone_numbers.get('US').list(contains: "FOO")
-
-You can use the ''*'' wildcard to match any character. The following example finds any phone number that matches the pattern ''D*D''.
-
-.. code-block:: ruby
-
-    numbers = @client.available_phone_numbers.get('US').list(contains: "D*D")
-
-Other Number Searches
-^^^^^^^^^^^^^^^^^^^^^
-
-:meth:`PhoneNumbers.search` method has plenty of other options to augment your search :
-
-- :data:`region`: When searching the US, show numbers in this state
-- :data:`postal_code`: Only show numbers in this area code
-- :data:`rate_center`: US only.
-- :data:`near_lat_long`: Find numbers near this latitude and longitude.
-- :data:`distance`: Search radius for a Near- query in miles.
-- :data:`beta`: Include or exclude numbers that are new to the Twilio platform.
-
-The `AvailablePhoneNumbers REST Resource
-<http://www.twilio.com/docs/api/rest/available-phone-numbers>`_ documentation
-has more information on the various search options.
-
-Numbers Requiring Addresses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Some phone numbers require you to have an address on file with Twilio to satisfy legal
-requirements before they can be purchased. By default, the client library will
-include numbers in the result lists regardless of their address requirements; you can
-filter these numbers out when searching for phone numbers to purchase.
-
-.. code-block:: ruby
-
-    # Exclude all numbers requiring addresses
-    numbers = @client.available_phone_numbers.get('AU').list(exclude_all_address_required: true)
-
-    # Exclude numbers requiring local addresses
-    numbers = @client.available_phone_numbers.get('AU').list(exclude_local_address_required: true)
-
-    # Exclude numbers requiring foreign addresses
-    numbers = @client.available_phone_numbers.get('AU').list(exclude_foreign_address_required: true)
-
-
-Buying a Number
----------------
-
-If you've found a phone number you want, you can purchase the number.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @number = @client.available_phone_numbers.purchase(
-      phone_number: "+15305431234"
-    )
-
-However, it's easier to purchase numbers after finding them using search (as
-shown in the first example).
-
-
-Updating Properties on a Number
--------------------------------
-
-To update the properties on a phone number, call :meth:`update`
-on the phone number object, with any of the parameters
-listed in the `IncomingPhoneNumbers Resource documentation
-<http://www.twilio.com/docs/api/rest/incoming-phone-numbers>`_
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @client.available_phone_numbers.list.each do |number|
-      number.update(
-        voice_url: "http://twimlets.com/holdmusic?" \
-                   "Bucket=com.twilio.music.ambient",
-        status_callback: "http://example.com/callback"
-      )
-    end
-
-Changing Applications
-----------------------
-
-An :class:`Application` encapsulates all necessary URLs for use with phone numbers. Update an application on a phone number using :meth:`update`.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-
-    phone_sid = "PNXXXXXXXXXXXXXXXXX"
-
-    @number = @client.available_phone_numbers.get(phone_sid)
-    @number.update(sms_application_sid: "APXXXXXXXXXXXXXXXXXX")
-
-See :doc:`/usage/applications` for instructions on updating and maintaining Applications.
-
-
-Validate a Phone Number
------------------------
-
-See validation instructions here: :doc:`/usage/caller-ids`:
-

data/docs/usage/pricing.rst

@@ -1,169 +0,0 @@
-.. module:: twilio.rest.pricing
-
-======================================
-Accessing Twilio Pricing API Resources
-======================================
-
-To access Twilio Pricing resources, you'll first need to instantiate a
-:class:`Twilio::REST::PricingClient`.
-
-
-Authentication
---------------
-
-The :class:`Twilio::REST::PricingClient` needs your Twilio credentials. To get
-your credentials, visit `your Twilio account portal
-<https://www.twilio.com/user/account>`_. If you don't have a Twilio account
-yet, go `here <https://www.twilio.com/try-twilio>`_ to get started.
-
-Once you have your credentials, you can create create a new :class:`PricingClient` and get started.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::PricingClient.new account_sid, auth_token
-
-You can also configure the client using the top level configure method, like so:
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    Twilio.configure do |config|
-      config.account_sid = "ACXXXXXXXXXXXXXXXXX"
-      config.auth_token = "YYYYYYYYYYYYYYYYYY"
-    end
-
-    @client = Twilio::REST::PricingClient.new
-
-
-=============
-Voice Pricing
-=============
-
-Twilio Voice pricing information is available by country and by phone number.
-
-Voice calls are priced per minute and reflect the current Twilio list price
-and any discounts available to the requesting account at the time of the
-request.
-
-Voice Countries
----------------
-
-To retrieve a list of countries where Twilio Voice services are available:
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::PricingClient.new account_sid, auth_token
-    @countries = @client.voice.countries.list
-    @countries.each do |c|
-        puts c.country
-    end
-
-Note that the country objects in the returned list will not have pricing
-information populated; you will need to retrieve the specific information
-for each country you are interested in individually:
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::PricingClient.new account_sid, auth_token
-    @country = @client.voice.countries.get('US')
-    puts @country.iso_country
-    puts @country.price_unit
-
-    # A list of price rates for inbound calls to each type of Twilio Number
-    # available in this country
-    @country.inbound_call_prices.each do |p|
-        puts p.number_type
-        puts p.base_price # List price per minute
-        puts p.current_price # Discounted price per minute
-    end
-
-    # A list of price rates for outbound calls to number, organized
-    # by prefix.
-    @country.outbound_prefix_prices.each do |p|
-        puts p.prefixes # List of one or more prefixes this price applies to
-        puts p.base_price # Base price per minute
-        puts p.current_price # Discounted price per minute
-
-Voice Numbers
--------------
-
-To retrieve pricing information for Twilio Voice calls to and from a specific
-number:
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::PricingClient.new account_sid, auth_token
-    @number = @client.voice.phone_numbers.get('+15105551234')
-    puts @number.iso_country
-    puts @number.price_unit
-    puts @number.outbound_call_price.base_price
-    puts @number.inbound_call_price.number_type # inbound_call_price will be nil if the number is not Twilio-hosted
-
-
-Phone Number Pricing
-====================
-
-To retrieve a list of countries where Twilio phone numbers are available:
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::PricingClient.new account_sid, auth_token
-    @countries = @client.phone_numbers.countries.list
-    @countries.each do |c|
-        puts c.country
-    end
-
-
-Note that the country objects in the returned list will not have pricing
-information populated; you will need to retrieve the specific information for
-each country you are interested in individually:
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::PricingClient.new account_sid, auth_token
-    @country = @client.phone_numbers.countries.get('US')
-    puts @country.iso_country
-    puts @country.price_unit
-
-    @country.phone_number_prices.each do |p|
-        puts p.number_type # 'local', 'mobile', 'national', or 'toll_free'
-        puts p.base_price # Price per month before any discounts have been applied
-        puts p.current_price # Price per month after any available discounts from the requesting account have applied
-

data/docs/usage/queues.rst

@@ -1,112 +0,0 @@
-.. module:: twilio.rest.resources
-
-==============================
-Queues and Members
-==============================
-
-For more information, see the
-`Queue REST Resource <http://www.twilio.com/docs/api/rest/queue>`_
-and `Member REST Resource <http://www.twilio.com/docs/api/rest/member>`_
-documentation.
-
-
-Listing Queues
------------------------
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @queues = @client.queues.list
-
-    @queues.each do |queue|
-      puts queue.sid
-    end
-
-
-Listing Queue Members
-----------------------
-
-Each :class:`Queue` has a :attr:`members` instance which
-represents all current calls in the queue.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-    @queue = @client.queues.get("QU123")
-
-    @queue.members.list().each do |member|
-      puts member.call_sid
-    end
-
-
-Getting a specific Queue Member
--------------------------------
-
-To retrieve information about a specific member in the queue, each
-:class:`Members` has a :attr:`get` method. :attr:`get` accepts one
-argument. The argument can either be a `call_sid` thats in the queue,
-in which case :attr:`get` will return a :class:`Member` instance
-representing that call, or the argument can be 'Front', in which case
-:attr:`Get` will return a :class:`Member` instance representing the
-first call in the queue.
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-
-    queue_sid = "QUAAAAAAAAAAAAA"
-    call_sid = "CAXXXXXXXXXXXXXX"
-
-    @members = @client.queues.get(queue_sid).members
-
-    # Get the first call in the queue
-    puts members.front.date_enqueued
-
-    # Get the call with the given call sid in the queue
-    puts members.get(call_sid).current_position
-
-
-Dequeueing Queue Members
-------------------------
-
-To dequeue a specific member from the queue, each
-:class:`Members` has a :attr:`dequeue` method. :attr:`dequeue` accepts an
-argument and two optional keyword arguments. The first argument is the
-url of the twiml document to be executed when the member is
-dequeued. The other two are :attr:`call_sid` and :attr:`method`, their
-default values are 'Front' and 'GET'
-
-.. code-block:: ruby
-
-    require 'twilio-ruby'
-
-    # To find these visit https://www.twilio.com/user/account
-    account_sid = "ACXXXXXXXXXXXXXXXXX"
-    auth_token = "YYYYYYYYYYYYYYYYYY"
-
-    @client = Twilio::REST::Client.new account_sid, auth_token
-
-    queue_sid = "QUAAAAAAAAAAAAA"
-
-    @members = @client.queues.get(queue_sid).members
-
-    # Dequeue the first call in the queue
-    puts @members.dequeue('http://www.twilio.com/welcome/call')