restcomm-ruby 1.2.0

data/docs/usage/errors.rst

@@ -0,0 +1,31 @@
+Error Handling
+==============
+
+Exceptions
+----------
+If the Restcomm API returns a 400 or a 500 level HTTP response,
+the restcomm-ruby library will throw a :class:`Restcomm::REST::RequestError`.
+400-level errors are normal during API operation ("Invalid number",
+"Cannot deliver SMS to that number", for example) and should be
+handled appropriately.
+
+.. 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"
+	
+
+    begin
+      @client = Restcomm::REST::Client.new account_sid, auth_token, host
+      client.messages.create({
+        from: '+1234567890',
+        to: '+1234567890',
+        body: 'Hello world'
+      })
+    rescue Restcomm::REST::RequestError => e
+      puts e.message
+    end

data/docs/usage/messages.rst

@@ -0,0 +1,142 @@
+.. module:: restcomm.rest.resources.sms_messages
+
+============
+Messages
+============
+
+For more information, see the
+`Message REST Resource <http://docs.telestax.com/restcomm-pages/>`_
+documentation.
+
+
+Sending a Text Message
+----------------------
+
+Send a text message in only a few lines of code.
+
+.. 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
+
+    @message = @client.messages.create(
+      to: "+13216851234",
+      from: "+15555555555",
+      body: "Hello!"
+    )
+
+If you want to send a message from a `short code
+<http://www.restcomm.com/api/sms/short-codes>`_ on Restcomm, just set :attr:`from`
+to your short code's number.
+
+
+Sending a Picture Message
+-------------------------
+
+To send a picture, set :attr:`media_url` to the url of the picture you wish to send.
+
+.. 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
+
+    @message = @client.messages.create(
+      to: "+15558676309",
+      from: "+15555555555",
+      body: "Jenny I need you!",
+      media_url: "http://restcomm.com/heart.jpg"
+    )
+
+You can send multiple pictures in the same message by setting :attr:`media_url` to
+an array of urls.
+
+.. code-block:: ruby
+
+    @message = @client.messages.create(
+      to: "+15558676309",
+      from: "+15555555555",
+      body: "Jenny I need you!",
+      media_url: [
+        "http://restcomm.com/heart.jpg",
+        "http://restcomm.com/rose.jpg"
+      ]
+    )
+
+Retrieving Sent Messages
+-------------------------
+
+.. 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.messages.list.each do |message|
+      puts message.body
+    end
+
+Redacting or Deleting Messages
+------------------------------
+
+.. 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
+    @msg_sid = 'MM123'
+    @msg = @client.messages.get('MM123')
+    # Deletes the Body field contents
+    @msg.redact
+
+    # Removes the entire Message record
+    @msg.delete
+
+Filtering Your Messages
+-------------------------
+
+The :meth:`list` methods supports filtering on :attr:`to`, :attr:`from`,
+and :attr:`date_sent`.
+The following will only show messages to "+5466758723" on January 1st, 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
+
+    @messages = @client.messages.list(
+      to: "+5466758723",
+      date_sent: "2011-01-01"
+    )
+
+    @messages.each do |message|
+      puts message.body
+    end
+

data/docs/usage/notifications.rst

@@ -0,0 +1,72 @@
+.. module:: restcomm.rest.resources
+
+====================
+Notifications
+====================
+
+For more information, see the `Notifications REST Resource
+<http://www.restcomm.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 '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
+
+    @client.notifications.list.each do |notification|
+      puts notification.more_info
+    end
+
+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 '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
+
+    ERROR = 0
+
+    @client.notifications.list(log=ERROR).each do |notification|
+      puts notification.error_code
+    end
+
+.. 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 '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
+    @client.notifications.get("NO123").delete()
+

data/docs/usage/phone-calls.rst

@@ -0,0 +1,193 @@
+.. module:: restcomm.rest
+.. _phone-calls:
+
+=====================
+Phone Calls
+=====================
+
+The :class:`Calls` resource manages all interaction with Restcomm 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 `RCML <http://docs.telestax.com/restcomm-pages/>`_.
+
+.. 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
+    @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 '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
+    sid = "CA12341234"
+    @call = @client.calls.get(sid)
+
+Delete a Call Record
+--------------------
+
+.. 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
+    sid = "CA12341234"
+    @call = @client.calls.get(sid)
+
+    # Removes the entire record from Restcomm'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 '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
+    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 '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
+    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 '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
+    @calls = @client.calls.list(status: "in-progress")
+
+    @calls.each do |call|
+      call.redirect_to("http://twimlets.com/holdmusic?Bucket=com.restcomm.music.ambient")
+    end
+
+
+Ending all live calls is also possible
+
+.. 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
+    @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 '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
+    sid = "CA12341234"
+    @client.calls.get(sid).redirect_to("http://twimlets.com/holdmusic?Bucket=com.restcomm.music.ambient")
+
+Hanging up the call also works.
+
+.. 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
+    sid = "CA12341234"
+    @client.calls.get(sid).hangup()
+

data/docs/usage/phone-numbers.rst

@@ -0,0 +1,192 @@
+.. module:: restcomm.rest.resources
+
+=================
+Phone Numbers
+=================
+
+With Restcomm you can search and buy real phone numbers, just using the API.
+
+For more information, see the
+`IncomingPhoneNumbers REST Resource
+<http://docs.telestax.com/restcomm-pages/>`_ 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 '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
+    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.
+
+The `AvailablePhoneNumbers REST Resource
+<http://www.restcomm.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 Restcomm 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 '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
+    @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://docs.telestax.com/restcomm-pages/>`_
+
+.. 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.available_phone_numbers.list.each do |number|
+      number.update(
+        voice_url: "http://twimlets.com/holdmusic?" \
+                   "Bucket=com.restcomm.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 '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
+
+    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`:
+