restcomm-ruby 1.2.0

data/docs/usage/twiml.rst

@@ -0,0 +1,69 @@
+.. _usage-twiml:
+
+.. module:: restcomm.twiml
+
+==============
+RCML Creation
+==============
+
+RCML 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 RCML.
+To finish, call the :meth:`toxml` method on the :class:`Response`,
+which returns raw RCML.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    Restcomm::RCML::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:: ruby
+
+    require 'restcomm-ruby'
+
+    Restcomm::RCML::Response.new do |r|
+      r.Play "https://api.restcomm.com/cowbell.mp3", loop: 5
+    end.text
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <Response>
+      <Play loop="3">https://SOME_WEBSITE/cowbell.mp3</Play>
+    <Response>
+
+Any example of nesting nouns in verbs
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    Restcomm::RCML::Response.new do |r|
+      r.Say "hello"
+      r.Gather finishOnKey: => 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,107 @@
+.. module:: restcomm.util
+
+===========================
+Validate Incoming Requests
+===========================
+
+Restcomm requires that your RCML-serving web server be open to the public. This
+is necessary so that Restcomm can retrieve RCML from urls and POST data back to
+your server.
+
+However, there may be people out there trying to spoof the Restcomm service.
+Luckily, there's an easy way to validate that incoming requests are from Restcomm
+and Restcomm alone.
+
+An in-depth guide to our security features can be `found in our online
+documentation <http://docs.telestax.com/restcomm-pages/>`_.
+
+Before you can validate requests, you'll need four pieces of information:
+
+* your Restcomm Auth Token (found in your `Dashboard
+  <https://www.restcomm.com/user/account>`_)
+* the POST data for the request
+* the requested URL
+* the X-Restcomm-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-Restcomm-Signature as strings.
+
+The below example will print out a confirmation message if the request is
+actually from Restcomm.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    auth_token = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+
+    @validator = Restcomm::Util::RequestValidator.new auth_token
+
+    # the callback URL you provided to Restcomm
+    url = "http://www.example.com/my/callback/url.xml"
+
+    # the POST variables attached to the request (eg "From", "To")
+    post_vars = {}
+
+    # X-Restcomm-Signature header value
+    signature = "HpS7PBa1Agvt4OtO+wZp75IuQa0=" # will look something like that
+
+    if @validator.validate(url, post_vars, signature)
+      puts "Confirmed to have come from Restcomm."
+    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/restcomm where the real page
+is served from https://mycompany.com/restcomm/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/restcomm/ for example.
+
+Using the code above, or similar code in another language, you could
+end up with an incorrect hash because Restcomm built the hash using
+https://mycompany.com/restcomm and you may have built the hash using
+https://mycompany.com/restcomm/. More information can be found in our
+documentation on validating requests.
+
+Rack Middleware
+===============
+
+If you are serving up your site using a Rack based framework, such as Sinatra or
+Rails, you can use the Rack middleware that is included in the gem to protect
+from spoofing attempts.
+
+To use the middleware, you need to set it up with your Restcomm Auth Token and a
+set of paths to watch. For example, here is how you would use the middleware in
+a Sinatra application:
+
+.. code-block:: ruby
+
+    require 'sinatra'
+    require 'restcomm-ruby'
+
+    auth_token = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+
+    use Rack::RestcommWebhookAuthentication, auth_token, /\/messages/
+
+    post '/messages' do
+      # response with RCML
+    end
+
+Now, any POST request to /messages in your application that doesn't validate as
+a Restcomm request, will automatically respond with a 403 status code and your
+action will not be hit.
+
+If you use subaccounts and need to validate with different auth tokens, you can pass a block to the middleware instead of an auth token. The block will be passed the Account Sid making the call.
+
+.. code-block:: ruby
+
+    use Rack::RestcommWebhookAuthentication, nil, /\/messages/ do |account_sid|
+      # lookup auth_token from account_sid
+    end
+
+Ensure you pass `nil` for the auth_token when passing a block, otherwise the block will not be called.

data/examples/examples.rb

@@ -0,0 +1,200 @@
+#Welcomme to Restcomm 
+#The examples below will help you get started using Restcomm-ruby wraper
+# examples version 1.2.0
+# You must make sure the @account_sid, @auth_token and @host variables are correctly filled
+#
+#The @host is the IP address on which Restcomm is running (This could be a local install or a remote)
+#
+#
+#
+####### Account Settings #########
+
+require 'restcomm-ruby'
+
+
+
+@account_sid = 'ACae6e420f425248d6a26948c17a9e2acf'
+@auth_token = 'YourPassWord' #
+@host = '192.168.1.3'  #IP address of your Restcomm instance  
+# set up a client
+@client = Restcomm::REST::Client.new(@account_sid, @auth_token, @host)
+
+################ ACCOUNTS ################
+
+# shortcut to grab your account object (account_sid is inferred from the client's auth credentials)
+@account = @client.account
+
+#list of all accounts and (sub)accounts
+	@client.accounts.list.each do |x|
+	puts "Account name: " + x.friendly_name + "      Account Sid: " + x.sid 
+	end
+
+# grab an account instance resource of a given account and display the friendly_name
+	puts @client.accounts.get(@account_sid).friendly_name
+
+# grab an account instance resource of a given account and display the sid
+	puts @client.accounts.get(@account_sid).sid
+
+# update an account's friendly name
+@client.accounts.get(@account_sid).update(friendly_name: 'A Super Cool Name')
+
+
+################ CALLS ################
+
+	
+# print a list of calls (without parameters)
+	 @account.calls.list().each do |x|
+	 puts "Call Sid " + x.sid + "      Call Status: " + x.status 
+	 end
+
+
+# print a list of calls (with some optional parameters)
+
+@account.calls.list(page: 0, page_size: 1000,).each do |x|
+  puts x.sid
+end
+
+# get a particular call and list its status
+puts @account.calls.get('CAb358e7b349924ece8a968f7089222039').status
+
+# get a particular call and list its start time
+puts @account.calls.get('CAb358e7b349924ece8a968f7089222039').start_time
+
+# get a particular call and list its recording URI
+puts @account.calls.get('CAb358e7b349924ece8a968f7089222039').subresource_uris["recordings"]
+
+#################### RECORDINGS ##################################
+
+#get a list of recordings linked to the current account and output the call SID and date created
+@account.recordings.list.each do |x|
+  puts "Recording SID: " + x.call_sid + " **** " + "Date Created: " + x.date_created
+end
+
+
+#get a list of recordings URLs with ext .wav 
+#use ext .mp3 to get the corresponding  mp3 list
+@account.recordings.list.each do |r|
+  puts r.wav
+end
+
+
+
+#################### MAKING CALLS ##################################
+
+# make a new outgoing call. returns a call object just like calls.get
+@call = @account.calls.create(
+  from: 'sip:+32145687',
+  to: 'sip:+1111@192.168.1.3',
+  url: 'http://192.168.1.3:8080/restcomm-rvd/services/apps/test/controller'
+)
+
+
+# cancel the call if not already in progress
+@account.calls.get(@call.sid).update(status: 'canceled')
+# or equivalently
+@call.update(status: 'canceled')
+
+
+
+####### Terminate a call that is currently in-progress ########
+
+@account.calls.get(@call.sid).update(status: 'completed')
+
+
+
+# redirect and then terminate a call
+
+@call.update(url: 'http://192.168.1.3:8080/restcomm/demos/hello-play.xml')
+@call.update(status: 'completed')
+# or, use the aliases...
+@call.redirect_to('http://192.168.1.3:8080/restcomm/demos/hello-play.xml')
+@call.hangup
+
+################ SMS MESSAGES ################
+
+# print a list of messages
+@account.messages.list(date_sent: '2010-09-01').each do |message|
+  puts message.body
+end
+
+# print a particular sms message
+puts @account.messages.get('SMXXXXXXXX').body
+
+# send an sms
+@account.messages.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  body: 'Hey there!'
+)
+
+# send an mms the from DID should be a number from your  DID provider
+@account.messages.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  media_urls: 'http://example.com/media.png'
+)
+
+################ PHONE NUMBERS ################
+
+# get a list of supported country codes
+@account.available_phone_numbers.list
+
+# print some available numbers
+@numbers = @account.available_phone_numbers.get('US').local.list(
+  AreaCode: '305'
+)
+
+@numbers.each { |num| puts num.phone_number }
+
+# buy the first one
+@account.incoming_phone_numbers.create(phone_number: @numbers[0].phone_number)
+
+# update an existing phone number's voice url
+number = @account.incoming_phone_numbers.get('PNdba508c5616a7f5e141789f44f022cc3')
+number.update(voice_url: 'http://example.com/voice')
+
+# decommission an existing phone number
+numbers = @account.incoming_phone_numbers.list(
+  friendly_name: 'A Fabulous Friendly Name'
+)
+numbers[0].delete
+################ CONFERENCES  ################
+
+# get a particular conference's participants object and stash it
+conference = @account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39')
+@participants = conference.participants
+
+# list participants
+@participants.list.each do |p|
+  puts p.sid
+end
+
+# update a conference participant
+@participants.get('CA386025c9bf5d6052a1d1ea42b4d16662').update(muted: 'true')
+# or an easier way
+@participants.get('CA386025c9bf5d6052a1d1ea42b4d16662').mute
+
+# and, since we're lazy loading, this would only incur one http request
+@account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39').participants
+  .get('CA386025c9bf5d6052a1d1ea42b4d16662').update(muted: 'true')
+
+################ QUEUES ###################
+
+# create a new queue
+@queue = @account.queues.create(friendly_name: 'MyQueue', max_size: 50)
+
+# get a list of queues for this account
+@queues = @account.queues.list
+
+# get a particular queue and its members
+@queue = @account.queues.get("QQb6765b0458714964970a73dcaf55efd1")
+@members = @queue.members
+
+#list members
+@members.list.each do |m|
+  puts m.wait_time
+end
+
+# dequeue a particular user and run twiml at a specific url
+@member = @members.get('CA386025c9bf5d6052a1d1ea42b4d16662')
+@member.dequeue('http://myapp.com/deque')

data/examples/print-call-log.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'restcomm-ruby'
+
+# print a list of all phone calls, what phone number each was to/from, and how
+# much each one cost.
+
+# put your Restcomm credentials here. you can find your AccountSid and AuthToken
+# at the top of your account dashboard page located at:
+#   
+account_sid = 'AC043dcf9844e04758bc3a36a84c29761'
+auth_token = '62ea81de3a5b414154eb263595357c69'
+host = 'IP_Address_Restcomm_Instance'
+
+# set up a client
+client = Restcomm::REST::Client.new(account_sid, auth_token, host)
+
+calls = client.calls.list
+
+begin
+  calls.each do |call|
+    price = call.price || '0.00' # since apparently prices can be nil...
+    puts call.sid + "\t" + call.from + "\t" + call.to + "\t" + price
+  end
+  calls = calls.next_page
+end while not calls.empty?

data/lib/rack/restcomm_webhook_authentication.rb

@@ -0,0 +1,47 @@
+module Rack
+  # Middleware that authenticates webhooks from Restcomm using the request
+  # validator.
+  #
+  # The middleware takes an auth token with which to set up the request
+  # validator and any number of paths. When a path matches the incoming request
+  # path, the request will be checked for authentication.
+  #
+  # Example:
+  #
+  # require 'rack'
+  # use Rack::RestcommWebhookAuthentication, ENV['AUTH_TOKEN'], /\/messages/
+  #
+  # The above appends this middleware to the stack, using an auth token saved in
+  # the ENV and only against paths that match /\/messages/. If the request
+  # validates then it gets passed on to the action as normal. If the request
+  # doesn't validate then the middleware responds immediately with a 403 status.
+
+  class RestcommWebhookAuthentication
+    def initialize(app, auth_token, *paths, &auth_token_lookup)
+      @app = app
+      @auth_token = auth_token
+      define_singleton_method(:get_auth_token, auth_token_lookup) if block_given?
+      @path_regex = Regexp.union(paths)
+    end
+
+    def call(env)
+      return @app.call(env) unless env["PATH_INFO"].match(@path_regex)
+      request = Rack::Request.new(env)
+      original_url = request.url
+      params = request.post? ? request.POST : {}
+      auth_token = @auth_token || get_auth_token(params['AccountSid'])
+      validator = Restcomm::Util::RequestValidator.new(auth_token)
+      signature = env['HTTP_X_TWILIO_SIGNATURE'] || ""
+      if validator.validate(original_url, params, signature)
+        @app.call(env)
+      else
+        [
+          403,
+          {'Content-Type' => 'text/plain'},
+          ["Restcomm Request Validation Failed."]
+        ]
+      end
+    end
+  end
+
+end