restcomm-ruby 1.2.0

data/docs/usage/addresses.rst

@@ -0,0 +1,102 @@
+.. module:: restcomm.rest.resources
+
+=========
+Addresses
+=========
+
+An Address instance resource represents your or your customer’s physical
+location within a country. Around the world, some local authorities require the
+name and address of the user to be on file with Restcomm to purchase and own a
+phone number.
+
+For more information, see the `Address REST Resource
+<http://docs.telestax.com/restcomm-pages/`_ documentation.
+
+Creating an Address
+-------------------
+
+Addresses contain the name of your company or your customer’s company in
+addition to location information and an optional friendly name.
+
+.. 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
+    @address = @client.addresses.create(
+      friendly_name: "Homer",
+      customer_name: "Homer Simpson",
+      street: "742 Evergreen Terrace",
+      city: "Springfield",
+      region "IL",
+      postal_code: "62701",
+      iso_country: "US"
+    )
+
+Listing Addresses
+-----------------
+
+The following code will print out the :attr:`customer_name` for each :class:`Address`.
+
+.. code-block:: ruby
+
+    @addresses = @client.addresses.list()
+    @addresses.each do |address|
+      puts address.customer_name
+    end
+
+Filtering Addresses
+-------------------
+
+The list of Addresses can be filtered on :attr:`friendly_name`,
+:attr:`customer_name`, and/or :attr:`iso_country`.
+
+.. code-block:: ruby
+
+    @addresses = @client.addresses.list(iso_country: 'AU')
+    @addresses.each do |address|
+      puts address.customer_name
+    end
+
+Updating an Address
+-------------------
+
+All Address attributes other than :attr:`iso_country` can be updated.
+To create an Address with a different country, see the "Creating an Address" section.
+
+.. code-block:: ruby
+
+    @sid = 'AD123' # the address you'd like to update
+    @address = @client.addresses.get(@sid)
+    @address.update(customer_name: "Marge Simpson")
+
+Deleting an Address
+-------------------
+
+.. code-block:: ruby
+
+    address_sid = 'AD123'
+    @address = @client.addresses.get(address_sid)
+    @address.delete()
+
+Listing Dependent Phone Numbers
+-------------------------------
+
+Restcomm will not permit you to delete an Address if it is the sole
+Address resource on your account that satisfies the address requirements
+for one or more of your purchased phone numbers.
+
+To see which phone numbers depend on a given address:
+
+.. code-block:: ruby
+
+    address_sid = 'AD123'
+    @address = @client.addresses.get(address_sid)
+    @address.dependent_phone_numbers.list.each do |number|
+      puts number.sid
+    end

data/docs/usage/applications.rst

@@ -0,0 +1,111 @@
+.. module:: restcomm.rest.resources
+
+=================
+Applications
+=================
+
+An application inside of Restcomm is just a set of URLs and other configuration
+data that tells Restcomm how to behave when one of your Restcomm numbers receives
+a call or message.
+
+For more information, see the `Application REST Resource
+<http://docs.telestax.com/restcomm-pages/>`_ documentation.
+
+
+Listing Your Applications
+--------------------------
+
+The following code will print out the :attr:`friendly_name` for each :class:`Application`.
+
+.. 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.applications.each do |app|
+      puts app.friendly_name
+    end
+
+
+Filtering Applications
+---------------------------
+
+You can filter applications by FriendlyName
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @client.applications.list(friendly_name: 'FOO').each do |app|
+      puts app.sid
+    end
+
+
+Creating an Application
+-------------------------
+
+When creating an application, no fields are required. We create an application
+with only a :attr:`friendly_name`. The :meth:`Applications.create()` method
+accepts many other arguments for url configuration.
+
+.. 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
+    @application = @client.applications.create(
+      friendly_name: "My New App"
+    )
+
+Updating an Application
+------------------------
+
+.. 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
+
+
+
+    @application = @client.applications.get(app_sid)
+    @application.update(voice_url: url)
+
+Deleting an Application
+-------------------------
+
+.. 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
+
+    app_sid = 'AP123' # the app you'd like to delete
+    @client.applications.get(app_sid)
+    @application.delete()
+

data/docs/usage/basics.rst

@@ -0,0 +1,120 @@
+.. module:: restcomm.rest
+
+=========================
+Accessing REST Resources
+=========================
+
+To access Restcomm REST resources, you'll first need to instantiate a
+:class:`Restcomm::REST::Client`.
+
+Authentication
+--------------------------
+
+The :class:`Restcomm::REST::Client` needs your Restcomm credentials. To get
+your credentials, visit `your Restcomm account portal
+<http://docs.telestax.com/restcomm-pages/>`_. If you don't have a Restcomm account
+yet, go `here <http://docs.telestax.com/restcomm-pages/>`_ to get started.
+
+Once you have your credentials, you can create create a new :class:`Client` and get started.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+You can also configure the client 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"
+    host = "XXX.XXX.XXX.XXX"
+    end
+
+    @client = Restcomm::REST::Client.new
+
+
+Listing Resources
+-------------------
+
+The :class:`Client` gives you access to various list resources.
+:meth:`ListResource.list`, by default, returns the most recent 50 instance resources.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+	@calls = @client.calls.list()
+
+:meth:`ListResource.list` accepts paging arguments.
+The following will return page 3 with page size of 25.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+	@calls = @client.calls.list(page: 3, page_size: 25)
+
+
+Get an Individual Resource
+-----------------------------
+
+To get an individual instance resource, use :meth:`ListResource.get`.
+Provide the :attr:`sid` of the resource you'd like to get.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @call = @client.calls.get("CA123")
+    puts @call.to
+
+
+Deleting a Resource
+-------------------------------
+
+Resources can only be deleted via their instance object. This means
+you must instantiate an instance object using :meth:`ListResource.get`
+and then call :meth:`delete` on it.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    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.delete()
+

data/docs/usage/caller-ids.rst

@@ -0,0 +1,47 @@
+.. module:: restcomm.rest.resources
+
+=================
+Caller Ids
+=================
+
+
+Validate a Phone Number
+-----------------------
+
+Validating a phone number is quick and easy.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token
+    @response = @client.outgoing_caller_ids.create(
+      phone_number: "+44 9876543212"
+    )
+    puts @response.validation_code
+
+Restcomm will call the provided number and wait for the validation code to be
+entered.
+
+Delete a Phone Number
+---------------------
+
+Deleting a phone number is quick and easy.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit https://www.restcomm.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token
+
+    @response = @client.outgoing_caller_ids.list(phone_number: "+15555555555")
+    @callerid = response[0]
+    @callerid.delete()

data/docs/usage/conferences.rst

@@ -0,0 +1,112 @@
+.. module:: restcomm.rest.resources
+
+==============================
+Conferences and Participants
+==============================
+
+For more information, see the `Conference REST Resource <http://docs.telestax.com/restcomm-pages/>`_
+and `Participant REST Resource <http://docs.telestax.com/restcomm-pages/>`_ documentation.
+
+
+Listing Conferences
+-----------------------
+
+.. 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
+    @conferences = @client.conferences.list()
+
+    @conferences.each do |conference|
+      puts conference.sid
+    end
+
+
+Filtering Conferences
+-----------------------
+
+The :meth:`Restcomm::REST::Conferences.list` method supports filtering on :attr:`status`,
+:attr:`date_updated`, :attr:`date_created` and :attr:`friendly_name`. The following code
+will return a list of all in-progress conferences and print their friendly name.
+
+.. 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
+    @conferences = @client.conferences.list(status: "in-progress")
+
+    @conference.each do |conference|
+      puts conference.friendly_name
+    end
+
+
+Listing Participants
+----------------------
+
+Each :class:`Conference` has a :attr:`participants` instance which represents all current users in the conference
+
+.. 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
+    @conference = @client.conferences.get("CF123")
+
+    @conference.participants.list.each.do |paricipant|
+      puts participant.sid
+    end
+
+:class:`Conferences` and :class:`Participants` are subclasses of :class:`ListResource`.
+Therefore, their instances have the inherited methods such as :meth:`count`.
+
+
+Managing Participants
+----------------------
+
+Each :class:`Conference` has a :attr:`participants` function that returns a
+:class:`Participants` instance. This behavior differs from other list resources
+because :class:`Participants` needs a participant sid AND a conference sid to
+access the participants resource.
+
+Participants can be either muted or kicked out of the conference. The following
+code kicks out the first participant and mutes the rest.
+
+.. 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
+    @participants = @client.conferences.get("CF123").participants.list()
+
+    return if @participants.empty?
+
+    # Kick the first person out
+    @participants.pop().kick()
+
+    # And mute the rest
+    @participants.each do |participant|
+      participant.mute()
+    end
+