twilio-ruby 3.10.1 → 3.11.0

data/docs/usage/recordings.rst

@@ -0,0 +1,96 @@
+.. module:: twilio.rest.resources
+
+================
+Recordings
+================
+
+For more information, see the
+`Recordings REST Resource <http://www.twilio.com/docs/api/rest/recording>`_
+documentation.
+
+
+Audio Formats
+-----------------
+
+Each :class:`Recording` has a few special methods. To get the url
+for the wav format of this recording, use :meth:`Recording.wav`. For the
+mp3 format, use :meth:`Recording.mp3`. To make requests for either of 
+these formats use the same method with a '!' appended. These methods
+both take a block to be executed as soon as the response returns.
+
+
+Listing Your Recordings
+----------------------------
+
+The following code will print out the :attr:`duration`
+for each :class:`Recording`.
+
+.. 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.recordings.list().each do |recording|
+        puts recording.duration
+
+You can filter recordings by CallSid by passing the Sid as :attr:`call`.
+Filter recordings using :attr:`before` and :attr:`after` dates.
+
+The following will only show recordings made before January 1, 2011.
+
+.. 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.recordings.list(before=date(2011,1,1)).each do |recording|:
+        puts recording.duration
+
+
+Deleting Recordings
+---------------------
+
+The :class:`Recordings` resource allows you to delete unnecessary recordings.
+
+.. 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.recordings.get("RC123").delete()
+
+
+Accessing Related Transcptions
+-------------------------------
+
+The :class:`Recordings` allows you to retrieve associated transcriptions.
+The following prints out the text for each of the transcriptions associated
+with this recording.
+
+.. 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
+    @recording = @client.recordings.get("RC123")
+
+    @recording.transcriptions.list().each do |transcription|
+        puts transcription.transcription_text
+

data/docs/usage/sip.rst

@@ -0,0 +1,103 @@
+=============
+Sip In
+=============
+
+Getting started with Sip In
+===========================
+
+If you're unfamiliar with SIP, please see the `SIP API Documentation
+<https://www.twilio.com/docs/api/rest/sip>`_ on our website. If you want
+to make a regular phone call, take a look at :doc:`phone-calls`.
+
+Creating a Sip Domain
+=====================
+
+The :class:`Domains` resource allows you to create a new domain. To
+create a new domain, you'll need to choose a unique domain that lives
+under sip.twilio.com.
+
+.. 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
+
+    @domain = @client.sip.domains.create(
+        {:friendly_name => "The Office Domain",
+         :voice_url => "http://example.com/voice",
+         :domain_name => "dunder-mifflin-scranton.sip.twilio.com",}
+    )
+    puts @domain.sid
+
+Creating a new IpAccessControlList
+==================================
+
+To control access to your new domain, you'll need to explicitly grant access
+to individual ip addresses. To do this, you'll first need to create an
+:class:`IpAccessControlList` to hold the ip addresses you wish to allow. 
+
+.. 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
+
+    @ip_acl = @client.sip.ip_access_control_lists.create(
+        {:friendly_name => "The Office IpAccessControlList",}
+    )
+    puts @ip_acl.sid
+
+Adding a new IpAddress
+=========================
+
+Now it's time to add an :class:`IpAddress` to your new :class:`IpAccessControlList`.
+
+.. 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
+
+    @ip_address = @client.sip.ip_access_control_lists.get(
+        "AL456",  # IpAccessControlList sid
+    ).ip_addresses.create(
+        {:friendly_name => "Dwights's Computer",
+         :ip_address => "192.168.1.42",}
+    )
+    puts @ip_address.sid
+
+Adding an IpAccessControlList to a Domain
+===========================================
+
+Once you've created a :class:`Domain` and an :class:`IpAccessControlList` you need to
+associate them. To do this, create an :class:`IpAccessControlListMapping`.
+
+.. 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
+
+    @ip_acl_mapping = @client.sip.domains.get(
+        "SD456",  # SIP Domain sid
+    ).ip_access_control_list_mappings.create(
+        {:ip_access_control_list_sid => "AL789"})
+
+    puts @ip_acl_mapping.sid
+

data/docs/usage/token-generation.rst

@@ -0,0 +1,81 @@
+.. module:: twilio.util
+
+===========================
+Generate Capability Tokens
+===========================
+
+`Twilio Client <http://www.twilio.com/api/client>`_ allows you to make and
+receive connections in the browser.
+You can place a call to a phone on the PSTN network,
+all without leaving your browser. See the `Twilio Client Quickstart
+<http:/www.twilio.com/docs/quickstart/client>`_ to get up and running with
+Twilio Client.
+
+Capability tokens are used by `Twilio Client
+<http://www.twilio.com/api/client>`_ to provide connection
+security and authorization. The `Capability Token documentation
+<http://www.twilio.com/docs/tokens>`_ explains in depth the purpose and
+features of these tokens.
+
+:class:`TwilioCapability` is responsible for the creation of these capability
+tokens. You'll need your Twilio AccountSid and AuthToken.
+
+.. code-block:: ruby
+    
+    require 'twilio-ruby'
+
+    # Find these values at twilio.com/user/account
+    account_sid = "AC123123"
+    auth_token = "secret"
+
+    @capability = Twilio::Util::Capability.new account_sid, auth_token
+
+
+Allow Incoming Connections
+==============================
+
+Before a device running `Twilio Client <http://www.twilio.com/api/client>`_
+can recieve incoming connections, the instance must first register a name
+(such as "Alice" or "Bob").
+The :meth:`allow_client_incoming` method adds the client name to the
+capability token.
+
+.. code-block:: ruby
+
+    @capability.allow_client_incoming("Alice")
+
+
+Allow Outgoing Connections
+==============================
+
+To make an outgoing connection from a
+`Twilio Client <http://www.twilio.com/api/client>`_ device,
+you'll need to choose a
+`Twilio Application <http://www.twilio.com/docs/api/rest/applications>`_
+to handle TwiML URLs. A Twilio Application is a collection of URLs responsible
+for outputting valid TwiML to control phone calls and messages.
+
+.. code-block:: ruby
+
+    # Twilio Application Sid
+    application_sid = "APabe7650f654fc34655fc81ae71caa3ff"
+    @capability.allow_client_outgoing(application_sid)
+
+
+Generate a Token
+==================
+
+.. code-block:: ruby
+
+    @token = @capability.generate()
+
+By default, this token will expire in one hour. If you'd like to change the
+token expiration, :meth:`generate` takes an optional :attr:`ttl` argument.
+
+.. code-block:: ruby
+
+    @token = @capability.generate(ttl=600)
+
+This token will now expire in 10 minutes. If you haven't guessed already,
+:attr:`ttl` is expressed in seconds.
+

data/docs/usage/transcriptions.rst

@@ -0,0 +1,31 @@
+.. module:: twilio.rest.resources
+
+================
+Transcriptions
+================
+
+Transcriptions are generated from recordings via the
+`TwiML <Record> verb <http://www.twilio.com/docs/api/twiml/record>`_.
+Using the API, you can only read your transcription records.
+
+For more information, see the `Transcriptions REST Resource
+<http://www.twilio.com/docs/api/rest/transcription>`_ documentation.
+
+
+Listing Your Transcriptions
+----------------------------
+
+The following code will print out the length of each :class:`Transcription`.
+
+.. 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.transcriptions.list().each do |transcription|
+        puts transcription.duration
+

data/docs/usage/twiml.rst

@@ -0,0 +1,70 @@
+.. _usage-twiml:
+
+.. module:: twilio.twiml
+
+==============
+TwiML Creation
+==============
+
+TwiML creation begins with the :class:`Response` verb.
+Each successive verb is created by calling various methods on the response,
+such as :meth:`say` or :meth:`play`.
+These methods return the verbs they create to ease creation of nested TwiML.
+To finish, call the :meth:`toxml` method on the :class:`Response`,
+which returns raw TwiML.
+
+.. code-block:: python
+
+    require 'twilio-ruby'
+
+    Twilio::TwiML::Response.new do |r|
+        r.Say "Hello"
+    end.text
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="utf-8"?>
+   <Response><Say>Hello</Say><Response>
+
+The verb methods (outlined in the :doc:`complete reference </api/twiml>`)
+take the body (only text) of the verb as the first argument.
+All attributes are keyword arguments.
+
+.. code-block:: python
+
+    require 'twilio-ruby'
+
+    Twilio::TwiML::Response.new do |r|
+        r.Play "https://api.twilio.com/cowbell.mp3", :loop => 5
+    end.text
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <Response>
+        <Play loop="3">https://api.twilio.com/cowbell.mp3</Play>
+    <Response>
+
+Python 2.6+ added the :const:`with` statement for context management.
+Using :const:`with`, the module can *almost* emulate Ruby blocks.
+
+.. code-block:: python
+
+    require 'twilio-ruby'
+
+    Twilio::TwiML::Response.new do |r|
+        r.Say "hello"
+        r.Gather :finish_on_key => 4 do |g|
+            g.Say "world"
+        end
+    end.text
+
+which returns the following
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <Response>
+      <Say>Hello</Say>
+      <Gather finishOnKey="4"><Say>World</Say></Gather>
+    </Response>

data/docs/usage/validation.rst

@@ -0,0 +1,71 @@
+.. module:: twilio.util
+
+===========================
+Validate Incoming Requests
+===========================
+
+Twilio requires that your TwiML-serving web server be open to the public. This
+is necessary so that Twilio can retrieve TwiML from urls and POST data back to
+your server.
+
+However, there may be people out there trying to spoof the Twilio service.
+Luckily, there's an easy way to validate that incoming requests are from Twilio
+and Twilio alone.
+
+An in-depth guide to our security features can be `found in our online
+documentation <http://www.twilio.com/docs/security>`_.
+
+Before you can validate requests, you'll need four pieces of information:
+
+* your Twilio Auth Token (found in your `Dashboard
+  <https://www.twilio.com/user/account>`_)
+* the POST data for the request
+* the requested URL
+* the X-Twilio-Signature header value
+
+Obtaining the last three pieces of information depends on the framework you are
+using to process requests. The below example assumes that you have the POST
+data as a dictionary and the url and X-Twilio-Signature as strings.
+
+The below example will print out a confirmation message if the request is
+actually from Twilio.
+
+.. code-block:: python
+
+    require 'twilio-ruby'
+
+    auth_token = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+
+    @validator = Twilio::Util::RequestValidator.new auth_token
+
+    # the callback URL you provided to Twilio
+    url = "http://www.example.com/my/callback/url.xml"
+
+    # the POST variables attached to the request (eg "From", "To")
+    post_vars = {}
+
+    # X-Twilio-Signature header value
+    signature = "HpS7PBa1Agvt4OtO+wZp75IuQa0=" # will look something like that
+
+    if @validator.validate(url, post_vars, signature)
+        puts "Confirmed to have come from Twilio."
+    else
+        puts "NOT VALID.  It might have been spoofed!"
+    end
+
+
+Trailing Slashes
+==================
+
+If your URL uses an "index" page, such as index.php or index.html to handle
+the request, such as: https://mycompany.com/twilio where the real page
+is served from https://mycompany.com/twilio/index.php, then Apache or
+PHP may rewrite that URL a little bit so it's got a trailing slash, such as
+https://mycompany.com/twilio/ for example.
+
+Using the code above, or similar code in another language, you could
+end up with an incorrect hash because Twilio built the hash using
+https://mycompany.com/twilio and you may have built the hash using
+https://mycompany.com/twilio/. More information can be found in our
+documentation on validating requests.
+