restcomm-ruby 1.2.0

data/docs/usage/queues.rst

@@ -0,0 +1,117 @@
+.. module:: restcomm.rest.resources
+
+==============================
+Queues and Members
+==============================
+
+For more information, see the
+`Queue REST Resource <http://docs.telestax.com/restcomm-pages/>`_
+and `Member REST Resource <http://docs.telestax.com/restcomm-pages/>`_
+documentation.
+
+
+Listing Queues
+-----------------------
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    queue_sid = "QUAAAAAAAAAAAAA"
+
+    @members = @client.queues.get(queue_sid).members
+
+    # Dequeue the first call in the queue
+    puts @members.dequeue('http://SOME_WEBSITE/welcome/call')

data/docs/usage/recordings.rst

@@ -0,0 +1,102 @@
+.. module:: restcomm.rest.resources
+
+================
+Recordings
+================
+
+For more information, see the
+`Recordings REST Resource <http://docs.telestax.com/restcomm-pages/>`_
+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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @client.recordings.list().each do |recording|
+      puts recording.duration
+    end
+
+You can filter recordings by CallSid by passing the Sid as :attr:`call`.
+Filter recordings using :attr:`DateCreated<` and :attr:`DateCreated>` dates.
+
+The following will only show recordings made before January 1, 2011.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @client.recordings.list('DateCreated<' => '2011-01-01').each do |recording|
+      puts recording.duration
+    end
+
+Deleting Recordings
+---------------------
+
+The :class:`Recordings` resource allows you to delete unnecessary recordings.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @recording = @client.recordings.get("RC123")
+
+    @recording.transcriptions.list().each do |transcription|
+      puts transcription.transcription_text
+    end
+

data/docs/usage/sip.rst

@@ -0,0 +1,108 @@
+=============
+Sip In
+=============
+
+Getting started with Sip In
+===========================
+
+If you're unfamiliar with SIP, please see the `SIP API Documentation
+<http://docs.telestax.com/restcomm-pages/>`_ 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.restcomm.com.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @domain = @client.sip.domains.create(
+      friendly_name: "The Office Domain",
+      voice_url: "http://example.com/voice"
+      domain_name: "dunder-mifflin-scranton.sip.restcomm.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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @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 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @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,96 @@
+.. module:: restcomm.util
+
+===========================
+Generate Capability Tokens
+===========================
+
+`Restcomm Client <http://docs.telestax.com/restcomm-pages/>`_ 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 `Restcomm Client Quickstart
+<http://docs.telestax.com/restcomm-pages/>`_ to get up and running with
+Restcomm Client.
+
+Capability tokens are used by `Restcomm Client
+<http://docs.telestax.com/restcomm-pages/>`_ to provide connection
+security and authorization. The `Capability Token documentation
+<http://docs.telestax.com/restcomm-pages/>`_ explains in depth the purpose and
+features of these tokens.
+
+:class:`Restcomm::Util::Capability` is responsible for the creation of these
+capability tokens. You'll need your Restcomm AccountSid and AuthToken.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # Find these values at restcomm.com/user/account
+    account_sid = "AC123123"
+    auth_token = "secret"
+
+    @capability = Restcomm::Util::Capability.new account_sid, auth_token
+
+You can also configure capability tokens using the top level configure method,
+like so:
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    Restcomm.configure do |config|
+      config.account_sid = "ACXXXXXXXXXXXXXXXXX"
+      config.auth_token = "YYYYYYYYYYYYYYYYYY"
+    end
+
+    @capability = Restcomm::Util::Capability.new
+
+
+
+Allow Incoming Connections
+==============================
+
+Before a device running `Restcomm Client <http://docs.telestax.com/restcomm-pages/>`_
+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
+`Restcomm Client <http://docs.telestax.com/restcomm-pages/>`_ device,
+you'll need to choose a
+`Restcomm Application <http://www.restcomm.com/docs/api/rest/applications>`_
+to handle RCML URLs. A Restcomm Application is a collection of URLs responsible
+for outputting valid RCML to control phone calls and messages.
+
+.. code-block:: ruby
+
+    # Restcomm 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,34 @@
+.. module:: restcomm.rest.resources
+
+================
+Transcriptions
+================
+
+Transcriptions are generated from recordings via the
+`RCML <Record> verb <http://www.restcomm.com/docs/api/twiml/record>`_.
+Using the API, you can only read your transcription records.
+
+For more information, see the `Transcriptions REST Resource
+<http://docs.telestax.com/restcomm-pages/>`_ documentation.
+
+
+Listing Your Transcriptions
+----------------------------
+
+The following code will print out the length of each :class:`Transcription`.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @client.transcriptions.list().each do |transcription|
+      puts transcription.duration
+    end
+