twilio-ruby 3.10.1 → 3.11.0

data/docs/usage/notifications.rst

@@ -0,0 +1,70 @@
+.. module:: twilio.rest.resources
+
+====================
+Notifications
+====================
+
+For more information, see the `Notifications REST Resource
+<http://www.twilio.com/docs/api/rest/notification>`_ documentation.
+
+
+Listing Your Notifications
+----------------------------
+
+The following code will print out additional information about each of your
+current :class:`Notification` resources.
+
+.. 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.notifications.list().each do |notification|:
+        puts notification.more_info
+
+You can filter transcriptions by :attr:`log` and :attr:`message_date`.
+The :attr:`log` value is 0 for `ERROR` and 1 for `WARNING`.
+
+.. 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
+
+    ERROR = 0
+
+    @client.notifications.list(log=ERROR).each do |notification|:
+        puts notification.error_code
+
+.. note:: Due to the potentially voluminous amount of data in a notification,
+    the full HTTP request and response data is only returned in the
+    :class:`Notification` instance resource representation.
+
+
+Deleting Notifications
+------------------------
+
+Your account can sometimes generate an inordinate amount of
+:class:`Notification` resources. The :class:`Notifications` resource allows
+you to delete unnecessary notifications.
+
+.. 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.notifications.get("NO123").delete()
+

data/docs/usage/phone-calls.rst

@@ -0,0 +1,168 @@
+.. 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)
+
+
+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:: python
+
+.. 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

@@ -0,0 +1,159 @@
+.. 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 number in area code 530.
+Once we find one, we'll purchase it for our account.
+
+.. code-block:: python
+
+    from twilio.rest import TwilioRestClient
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
+    numbers = client.phone_numbers.search(area_code=530)
+
+    if numbers:
+        numbers[0].purchase()
+    else:
+        print "No numbers in 530 available"
+
+
+Toll Free Numbers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, :meth:`PhoneNumbers.search` looks for local phone numbers. Add a
+:data:`type` : ``tollfree`` parameter to search toll-free numbers instead.
+
+.. code-block:: python
+
+    numbers = client.phone_numbers.search(type="tollfree")
+
+
+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:: python
+
+    numbers = client.phone_numbers.search(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:: python
+
+    numbers = client.phone_numbers.search(contains="D*D")
+
+
+International Numbers
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the client library will look for US numbers. Set the
+:data:`country` keyword to a country code of your choice to search for
+international numbers.
+
+.. code-block:: python
+
+    numbers = client.phone_numbers.search(country="FR")
+
+
+: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.
+
+The `AvailablePhoneNumbers REST Resource
+<http://www.twilio.com/docs/api/rest/available-phone-numbers>`_ documentation
+has more information on the various search options.
+
+
+Buying a Number
+---------------
+
+If you've found a phone number you want, you can purchase the number.
+
+.. code-block:: python
+
+    from twilio.rest import TwilioRestClient
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
+    number = client.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:: python
+
+    from twilio.rest import TwilioRestClient
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
+    for number in client.phone_numbers.list(api_version="2010-04-01"):
+        number.update(voice_url="http://twimlets.com/holdmusic?" + 
+            "Bucket=com.twilio.music.ambient", 
+            status_callback="http://example.com/callback")
+
+
+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:: python
+
+    from twilio.rest import TwilioRestClient
+
+    phone_sid = "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+
+    # To find these visit https://www.twilio.com/user/account
+    ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
+    AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
+
+    client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
+    number = client.phone_numbers.update(phone_sid, sms_application_sid="AP123")
+
+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/queues.rst

@@ -0,0 +1,112 @@
+.. 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|
+        print 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')