tropo-webapi-ruby 0.1.11 → 0.1.13

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA1: 
+  metadata.gz: 9b4ec4c8d2ed601fb2adb371218c73800ece5218
+  data.tar.gz: a1731101b04b7e32c84ac237e7a617c2f58cbb98
+SHA512: 
+  metadata.gz: 1f2290d05796f3f6091796b2143fdff8bf8aaf737db340d089a4077659761f8f8f90461f0a60ac0d528cba609bb6b65cfb7068b3c38211608a80f4209e571b21
+  data.tar.gz: 0508b0d936a4e7b263f557f7a7886acb01c8f17421fdb0ea8dab502017e75b47cc63a4b946d54e70b2edc5795bba2211b8d3718423ca3149365a1401c3373447

data/{README.rdoc → README.md}

@@ -1,20 +1,21 @@
-= Tropo Web API Ruby Library
+# Tropo Web API Ruby Library
+[![Build Status](https://drone.io/github.com/tropo/tropo-webapi-ruby/status.png)](https://drone.io/github.com/tropo/tropo-webapi-ruby/latest)
 
 A Ruby library for interaction with the Tropo Web API (http://tropo.com) using JSON.
 
-== Tropo Web API Overview
+## Tropo Web API Overview
 
 The Tropo Remote API provides a RESTful JSON API for controlling realtime communications applications from
 your own web servers.
 
-== Requirements
+## Requirements
 
-* Unit tests passed on: Ruby MRI v1.8.6/1.8.7 and JRuby v1.5.0
-* RubyGems
+  * Unit tests passed on: Ruby MRI v1.8.6/1.8.7/1.9.3/2.1.0 and JRuby v1.5.0/v1.7.9
+  * RubyGems
 
 Note: If using with ActiveSupport, v2.3.5 or better of ActiveSupport is required.
 
-== Installation
+## Installation
 
   $ sudo gem install tropo-webapi-ruby
 
@@ -22,13 +23,13 @@ Optional, if you would like to use with Sinatra:
 
   $ sudo gem install sinatra
 
-== Generate Documentation
+## Generate Documentation
 
-=== Developer
+### Developer
 
   $ gemserver
 
-=== Project Developer
+### Project Developer
 
   $ sudo gem install yard
 
@@ -36,8 +37,8 @@ From within the project:
 
   $ yardoc
 
-== Usage
-
+## Usage
+```ruby
   require 'rubygems'
   require 'tropo-webapi-ruby'
 
@@ -52,15 +53,15 @@ From within the project:
   response = tropo.parse(json_string)
   p 'Hey, this is a voice session!' if tropo.voice_session
   p 'Hey, this is a text messaging session!' if tropo.text_session
+```
+## Examples
 
-== Examples
-
-=== Sinatra
+### Sinatra
 
 Using the great RESTful Web Services framework Sinatra for Ruby.
 
-==== Hello World
-
+#### Hello World
+```ruby
   require 'rubygems'
   require 'sinatra'
   require 'tropo-webapi-ruby'
@@ -82,9 +83,9 @@ Using the great RESTful Web Services framework Sinatra for Ruby.
     tropo.say 'Hello again.'
     tropo.response
   end
-
-==== Getting Session Information
-
+```
+#### Getting Session Information
+```ruby
   # Produces a Ruby hash:
   #
   # { :session => 
@@ -117,9 +118,9 @@ Using the great RESTful Web Services framework Sinatra for Ruby.
     tropo_session = Tropo::Generator.parse request.env["rack.input"].read
     p tropo_session
   end
-
-==== Asking for input and receiving the response, or catching a hangup
-
+```
+#### Asking for input and receiving the response, or catching a hangup
+```ruby
   post '/ask.json' do
     tropo = Tropo::Generator.new do
               on :event => 'hangup', :next => '/hangup.json'
@@ -170,23 +171,23 @@ Using the great RESTful Web Services framework Sinatra for Ruby.
     tropo_event = Tropo::Generator.parse request.env["rack.input"].read
     p tropo_event
   end
-
-==== Redirect a call before answering
-
+```
+#### Redirect a call before answering
+```ruby
   # A redirect method
   post '/redirect.json' do
     Tropo::Generator.redirect({ :to => 'sip:1234', :from => '4155551212' })
   end
-
-==== Reject a call before answering
-
+```
+#### Reject a call before answering
+```ruby
   # A reject method
   post '/reject.json' do
     Tropo::Generator.reject
   end
-
-==== Setting a default voice for speech synthesis (text-to-speech/TTS)
-
+```
+#### Setting a default voice for speech synthesis (text-to-speech/TTS)
+```ruby
   post '/speak.json' do
     t = Tropo::Generator.new(:voice => 'kate')
     t.say 'Hello!' # Will speak as kate now
@@ -197,9 +198,9 @@ Using the great RESTful Web Services framework Sinatra for Ruby.
     t.voice = 'kate'
     t.say 'Hello!' # Will speak as kate now
   end
-
-==== Setting a default recognizer for speech recognition (ASR)
-
+```
+#### Setting a default recognizer for speech recognition (ASR)
+```ruby
   post '/ask.json' do
     t = Tropo::Generator.new(:recognizer => 'fr-fr')
     t.ask({ :name    => 'account_number', # Will now use the French speech recognition engine
@@ -222,12 +223,12 @@ Using the great RESTful Web Services framework Sinatra for Ruby.
               choices :value => '[5 DIGITS]'
             end
   end
-
-=== Additional Examples
+```
+### Additional Examples
 
 May be found by checking out the project from Github, and then looking in $PROJECT_HOME/examples and $PROJECT_HOME/spec/tropo-webapi-ruby_spec.rb.
 
-=== Documentation
+### Documentation
 
 * API Documentation:
 
@@ -237,12 +238,12 @@ http://voxeo.github.com/tropo-webapi-ruby
 
 http://docs.tropo.com/webapi/2.0/home.htm
 
-== Notes
+## Notes
 
 In order to maintain compatibility between Ruby MRI and JRuby the gem requires 'json_pure'. If you are using the Ruby MRI and would prefer to use the C version of 'json', simply install the 'json' gem as follows:
 
   sudo gem install json
 
-== Copyright
+## Copyright
 
-Copyright (c) 2010 Voxeo, Corporation. See LICENSE for details.
+Copyright (c) 2014 Tropo, Inc. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.1.11
+0.1.13

data/examples/conferenceJoinLeave.rb

@@ -0,0 +1,27 @@
+require 'tropo-webapi-ruby'
+require 'sinatra'
+
+post '/index.json' do
+
+  v = Tropo::Generator.parse request.env["rack.input"].read
+  t = Tropo::Generator.new
+  
+  callerID = v[:session][:from][:id]
+    
+  t.say({:value => "You are about to enter the conference room"})
+  
+  t.conference({
+    :name => "joinLeave",
+    :id => "1234",
+    :joinPrompt => {
+      :value => "Please welcome #{callerID} to the party"
+      },
+    :leavePrompt => {
+      :value => "#{callerID} has left the party"
+    }
+  })
+  
+  t.response
+    
+end
+

data/examples/machineDetection.rb

@@ -0,0 +1,31 @@
+require 'tropo-webapi-ruby'
+require 'sinatra'
+
+post '/index.json' do
+
+  t = Tropo::Generator.new
+  
+  t.call :to => "+14071234321",
+         :machineDetection => {
+           :introduction => "This is just a test to see if you are a human or a machine. PLease hold while we determine. Almost finished. Thank you!",
+           :voice => "Victor"
+         }
+  
+  t.on :event => 'continue', :next => '/continue.json'
+  t.response
+    
+end
+
+
+post '/continue.json' do
+  
+  v = Tropo::Generator.parse request.env["rack.input"].read
+  t = Tropo::Generator.new
+  puts v
+  userType = v[:result][:user_type]
+  puts userType
+  t.say(:value => "You are a  #{userType}")
+  
+  t.response
+  
+end

data/examples/transferWhisper.rb

@@ -0,0 +1,38 @@
+require 'tropo-webapi-ruby'
+require 'sinatra'
+
+post '/index.json' do
+
+  t = Tropo::Generator.new
+  
+  t.say("Please hold while we transfer your call")
+  
+  whisper = [{
+    :event => "connect",
+    :ask => {
+      :say => {:value => "Press 1 to accept this call or any other key to decline"},
+      :choices => {:value => "1", :mode => "dtmf"},
+      :name => "transfer",
+      :interdigitTimeout => 1
+    },
+    :event => "connect",
+    :say => {:value => "You are now being connected to the transfer"}
+  }]
+  puts whisper
+  
+  t.transfer :to => "+14071234321",
+             :on => whisper
+
+  t.on :event => 'incomplete', :next => '/hangup.json', :say => {:value =>'You have opted out from accepting this call. Goodbye'}
+  
+  t.response
+    
+end
+
+post '/hangup.json' do
+  t = Tropo::Generator.new
+
+  t.hangup
+  t.response
+
+end

data/lib/tropo-webapi-ruby/tropo-webapi-ruby-helpers.rb

@@ -39,6 +39,8 @@ module Tropo
           return build_elements(params)
         when 'transfer'
           has_params?(params, 'transfer', 'to')
+        when 'wait'
+          has_params?(params, 'wait', 'milliseconds')
         end
 
         if action == 'on'

data/lib/tropo-webapi-ruby/tropo-webapi-ruby.rb

@@ -53,21 +53,33 @@ module Tropo
     #
     # @overload ask(params)
     #   @param [Hash] params the options to create an ask action request with.
-    #   @option params [String] :name the name to assign to the result when returned to the application, default is true
+    #   @option params [required, String] :choices indicates the structure of the expected data and acceptable modes of input - value, mode, terminator
+    #   @option params [optional, String] :say determines what is played or sent to the caller - also takes an event key to determine if prompt will be played based on a nomatch or timeout
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to ask which can be used with REST to interrupt the function 
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
     #   @option params [optional, Integer] :attempts (1) the number of times to prompt the user for input
-    #   @option params [optional, Boolean] :bargein (true) allows a user to enter a key to stop the ask action
-    #   @option params [optional, Float] :min_confidence (.5) the minimum confidence by which to accept the response expressed from 0-1, as opposed to asking again
-    #   @option params [optional, Boolean] :required (true) if this is a field that must be completed by the user
+    #   @option params [optional, Boolean] :bargein (true) allows a user to say or enter a key to stop the prompt from playing further
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
+    #   @option params [optional, Integer] :min_confidence (30) the minimum confidence by which to accept the response, as opposed to asking again
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
     #   @option params [optional, Integer] :timeout (30) the amount of time, in seconds, to wait for a response before moving on
+    #   @option params [optional, String] :recognizer this tells Tropo what language to listen for
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
     # @overload ask(params, &block)
     #   @param [Hash] params the options to create an ask action request with.
     #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
-    #   @option params [String] :name the name to assign to the result when returned to the application
+    #   @option params [required, String] :choices indicates the structure of the expected data and acceptable modes of input - value, mode, terminator
+    #   @option params [optional, String] :say determines what is played or sent to the caller - also takes an event key to determine if prompt will be played based on a nomatch or timeout
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to ask which can be used with REST to interrupt the function
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
     #   @option params [optional, Integer] :attempts (1) the number of times to prompt the user for input
-    #   @option params [optional, Boolean] :bargein (true) allows a user to enter a key to stop the ask action
-    #   @option params [optional, Float] :min_confidence (.5) the minimum confidence by which to accept the response expressed from 0-1, as opposed to asking again
-    #   @option params [optional, Boolean] :required (true) if this is a field that must be completed by the user
+    #   @option params [optional, Boolean] :bargein (true) allows a user to say or enter a key to stop the prompt from playing further
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
+    #   @option params [optional, Integer] :min_confidence (30) the minimum confidence by which to accept the response, as opposed to asking again
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
     #   @option params [optional, Integer] :timeout (30) the amount of time, in seconds, to wait for a response before moving on
+    #   @option params [optional, String] :recognizer this tells Tropo what language to listen for
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
     # @return [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def ask(params={}, &block)
@@ -89,25 +101,31 @@ module Tropo
     #
     # @overload call(params)
     #   @param [Hash] params the options to create a call action request with.
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
     #   @option params [String] :to the destination of the call, may be a phone number, SMS number or IM address
     #   @option params [optional, String] :from the phone number or IM address the call will come from
     #   @option params [optional, String] :network which network the call will be initiated with, such as SMS
     #   @option params [optional, String] :channel the channel the call will be initiated over, may be TEXT or VOICE
     #   @option params [optional, Integer] :timeout (30) the amount of time, in seconds, to wait for a response before moving on
-    #   @option params [optional, Boolean] :answer_on_media (true) 
+    #   @option params [optional, Boolean] :answer_on_media (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc)
     #   @options params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call
-    #   @options params [optional, Hash] :recording Refer to the recording method for paramaters in the hash
-    # @overload ask(params, &block)
+    #   @options params [optional, Hash] :recording allow you to start call recording as soon as the call is answered; refer to the recording method for paramaters in the hash
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to call which can be used with REST to interrupt the function 
+    # @overload call(params, &block)
     #   @param [Hash] params the options to create an message action request with.
     #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
     #   @option params [String] :to the destination of the call, may be a phone number, SMS number or IM address
     #   @option params [optional, String] :from the phone number or IM address the call will come from
     #   @option params [optional, String] :network which network the call will be initiated with, such as SMS
-    #   @option params [optional, String] :channel the channel the call will be initiated over, may be TEXT or VOICE
+    #   @option params [optional, String] :channel (voice) the channel the call will be initiated over, may be TEXT or VOICE
     #   @option params [optional, Integer] :timeout (30) the amount of time, in seconds, to wait for a response before moving on
-    #   @option params [optional, Boolean] :answer_on_media (true) 
+    #   @option params [optional, Boolean] :answer_on_media (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc)
     #   @options params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call
-    #   @options params [optional, Hash] :recording Refer to the recording method for paramaters in the hash
+    #   @options params [optional, Hash] :recording allow you to start call recording as soon as the call is answered; refer to the recording method for paramaters in the hash
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to call which can be used with REST to interrupt the function 
     # @return [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def call(params={}, &block)
@@ -126,10 +144,9 @@ module Tropo
     # Choices to give the user on input
     #
     # @param [Hash] params the options used to construct the grammar for the user
-    # @option params [String] :value the name to assign to the result when returned to the app
+    # @option params [String] :value this is the grammar which determines the type of expected data, such as [DIGITS]
     # @option params [optional, String] :mode (ANY) the mode to use when asking the user [DTMF, SPEECH or ANY]
-    # @option params [optional, String] :term_char the user may enter a keypad entry to stop the request
-    # @option params [optional, String] :type (simple/grammar) the type of grammar to use
+    # @option params [optional, String] :terminator (#) the user may enter a keypad entry to stop the request
     # @option [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def choices(params={})
@@ -148,21 +165,25 @@ module Tropo
     #
     # @overload conference(params)
     #   @param [Hash] params the options to create a message with.
-    #   @option params [String] :name the name to assign to the conference room and to identify events back to the application
-    #   @option params [Integer] :id the number to assign to the conference room
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [required, Integer] :id the number to assign to the conference room
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
     #   @option params [optional, Boolean] :mute (false) whether to mute this caller in the conference
-    #   @option params [optional, Integer] :max_time the maximum time, in seconds, to allow this user to stay in conference
-    #   @option params [optional, Integer] :send_tones whether to send the DTMF a user may enter to the audio of the conference
-    #   @option params [optional, String] :exit_tone whether to play a beep when this user exits a conference
+    #   @option params [optional, Integer] :play_tones whether to allow the DTMF input from a user to play into the conference
+    #   @option params [optional, String] :terminator this is the touch-tone key (DTMF) used to exit the conference
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to conference which can be used with REST to interrupt the function 
     # @overload conference(params, &block)
     #   @param [Hash] params the options to create a message with.
     #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
-    #   @option params [String] :name the name to assign to the conference room and to identify events back to the application
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
     #   @option params [Integer] :id the number to assign to the conference room
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
     #   @option params [optional, Boolean] :mute (false) whether to mute this caller in the conference
-    #   @option params [optional, Integer] :max_time the maximum time, in seconds, to allow this user to stay in conference
-    #   @option params [optional, Integer] :send_tones whether to send the DTMF a user may enter to the audio of the conference
-    #   @option params [optional, String] :exit_tone whether to play a beep when this user exits a conference
+    #   @option params [optional, Integer] :play_tones whether to allow the DTMF input from a user to play into the conference
+    #   @option params [optional, String] :terminator this is the touch-tone key (DTMF) used to exit the conference
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to conference which can be used with REST to interrupt the function 
     # @return [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def conference(params={}, &block)
@@ -183,7 +204,13 @@ module Tropo
     # May trigger these events:
     #   - hangup
     #   - error
-    #
+    # @overload hangup(params)
+    #   @param [Hash] params the options to create a message action request with.
+    #   @option params [String] :headers contains the Session Initiation Protocol (SIP) Headers for the current session.
+    # @overload hangup(params, &block)
+    #   @param [Hash] params the options to create an message action request with.
+    #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
+    #   @option params [String] :headers contains the Session Initiation Protocol (SIP) Headers for the current session.
     # @return [String, nil] returns the JSON string to hangup/stop the current session or nil
     #   if the method has been called from inside a block
     def hangup
@@ -198,25 +225,29 @@ module Tropo
     #
     # @overload message(params)
     #   @param [Hash] params the options to create a message action request with.
-    #   @option params [String] :to the destination of the call, may be a phone number, SMS number or IM address
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [required, String] :say determines what is played or sent to the caller
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
+    #   @option params [required, String] :to the destination of the call, may be a phone number, SMS number or IM address
     #   @option params [optional, String] :from the phone number or IM address the call will come from
     #   @option params [optional, String] :network which network the call will be initiated with, such as SMS
     #   @option params [optional, String] :channel the channel the call will be initiated over, may be TEXT or VOICE
     #   @option params [optional, Integer] :timeout (30) the amount of time, in seconds, to wait for a response before moving on
-    #   @option params [optional, Boolean] :answer_on_media (true) 
-    #   @options params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call
-    #   @options params [optional, Hash] :recording Refer to the recording method for paramaters in the hash
-    # @overload ask(params, &block)
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Boolean] :answer_on_media (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc)
+    # @overload message(params, &block)
     #   @param [Hash] params the options to create an message action request with.
     #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
-    #   @option params [String] :to the destination of the call, may be a phone number, SMS number or IM address
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [required, String] :say determines what is played or sent to the caller
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
+    #   @option params [required, String] :to the destination of the call, may be a phone number, SMS number or IM address
     #   @option params [optional, String] :from the phone number or IM address the call will come from
     #   @option params [optional, String] :network which network the call will be initiated with, such as SMS
     #   @option params [optional, String] :channel the channel the call will be initiated over, may be TEXT or VOICE
     #   @option params [optional, Integer] :timeout (30) the amount of time, in seconds, to wait for a response before moving on
-    #   @option params [optional, Boolean] :answer_on_media (true) 
-    #   @options params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call
-    #   @options params [optional, Hash] :recording Refer to the recording method for paramaters in the hash
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Boolean] :answer_on_media (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc)
     # @return [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def message(params={}, &block)
@@ -236,13 +267,15 @@ module Tropo
     #
     # @overload initialize(params)
     #   @param [Hash] params the options to create a message with.
-    #   @option params [String] :event the event name that should trigger the callback
-    #   @option params [String] :next the resource to send the callback to, such as '/error.json'
+    #   @option params [required, String] :event the event name that should trigger the callback
+    #   @option params [optional, String] :next the resource to send the callback to, such as '/error.json'
+    #   @option params [optional, String] :say determines what is played or sent to the caller
     # @overload initialize(params, &block)
     #   @param [Hash] params the options to create a message with.
-    #   @option params [String] :event the event name that should trigger the callback
-    #   @option params [String] :next the resource to send the callback to, such as '/error.json'
     #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
+    #   @option params [required, String] :event the event name that should trigger the callback
+    #   @option params [optional, String] :next the resource to send the callback to, such as '/error.json'
+    #   @option params [optional, String] :say determines what is played or sent to the caller
     # @option [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def on(params={}, &block)
@@ -314,21 +347,49 @@ module Tropo
     #
     # @overload record(params)
     #   @param [Hash] params the options to create a message with.
-    #   @option params [String] :name the event name that should trigger the callback
-    #   @option params [String] :url a valid URI, an HTTP, FTP or email address to POST the recording file to
+    #   @option params [optional, Integer] :attempts (1) the number of times to prompt the user for input
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to record which can be used with REST to interrupt the function 
+    #   @option params [optional, Boolean] :bargein (true) allows a user to say or enter a key to stop the prompt from playing further
+    #   @option params [optional, Boolean] :beep (true) when true, callers will hear a tone indicating the recording has begun
+    #   @option params [optional, String] :choices when used with record, this defines the terminator
+    #   @option params [required, String] :say determines what is played or sent to the caller
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
     #   @option params [optional, String] :format (audio/wav) the audio format to record in, either a wav or mp3
+    #   @option params [optional, Float] :max_silence (5.0) the max amount of time in seconds to wait for silence before considering the user finished speaking
+    #   @option params [optional, Float] :max_time (30.0) the max amount of time in seconds the user is allotted for input
+    #   @option params [optional, String] :method (POST) this defines how to send the audio file, either POST or PUT, and only applies to HTTP
+    #   @option params [optional, Integer] :min_confidence (30) the minimum confidence by which to accept the response, as opposed to asking again
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Hash] :transcription allows you to submit a recording to be transcribed - takes parameters id, url and emailFormat
+    #   @option params [optional, String] :url the destination URL to send the recording, either via FTP or HTTP
     #   @option params [optional, String] :username if posting to FTP, the username for the FTP server
     #   @option params [optional, String] :password if posting to FTP, the password for the FTP server
-    #   @option params [optional, Hash] :transcription parameters used to transcribe the recording
+    #   @option params [optional, Float] :timeout amount of time Tropo will wait--in seconds and after sending or playing the prompt--for the user to begin a response
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
     # @overload record(params, &block)
     #   @param [Hash] params the options to create a message with.
     #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
-    #   @option params [String] :name the event name that should trigger the callback
-    #   @option params [String] :url a valid URI, an HTTP, FTP or email address to POST the recording file to
+    #   @option params [optional, Integer] :attempts (1) the number of times to prompt the user for input
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to record which can be used with REST to interrupt the function 
+    #   @option params [optional, Boolean] :bargein (true) allows a user to say or enter a key to stop the prompt from playing further
+    #   @option params [optional, Boolean] :beep (true) when true, callers will hear a tone indicating the recording has begun
+    #   @option params [optional, String] :choices when used with record, this defines the terminator
+    #   @option params [required, String] :say determines what is played or sent to the caller
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
     #   @option params [optional, String] :format (audio/wav) the audio format to record in, either a wav or mp3
+    #   @option params [optional, Float] :max_silence (5.0) the max amount of time in seconds to wait for silence before considering the user finished speaking
+    #   @option params [optional, Float] :max_time (30.0) the max amount of time in seconds the user is allotted for input
+    #   @option params [optional, String] :method (POST) this defines how to send the audio file, either POST or PUT, and only applies to HTTP
+    #   @option params [optional, Integer] :min_confidence (30) the minimum confidence by which to accept the response, as opposed to asking again
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Hash] :transcription allows you to submit a recording to be transcribed - takes parameters id, url and emailFormat
+    #   @option params [optional, String] :url the destination URL to send the recording, either via FTP or HTTP
     #   @option params [optional, String] :username if posting to FTP, the username for the FTP server
     #   @option params [optional, String] :password if posting to FTP, the password for the FTP server
-    #   @option params [optional, Hash] :transcription parameters used to transcribe the recording
+    #   @option params [optional, Float] :timeout amount of time Tropo will wait--in seconds and after sending or playing the prompt--for the user to begin a response
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
     # @option [String, nil] the JSON string to be passed back to Tropo or nil
     #   if the method has been called from inside a block
     def record(params={}, &block)
@@ -344,16 +405,15 @@ module Tropo
     end
     
     ##
-    # The redirect function forwards an incoming call to another destination / phone number before answering it. 
+    # The redirect function forwards an incoming SIP call to another destination before answering it. 
     # The redirect function must be called before answer is called; redirect expects that a call be in the ringing or answering state. 
     # Use transfer when working with active answered calls.
     #
-    #  tel: classic phone number (See RFC 2896), must be proceeded by a + and the country code (ie - +14155551212 for a US #)
-    #  sip: Session Initiation Protocol (SIP) address
     #
     # @param [Hash] params the options to create a message with.
-    # @option params [required, String] :to where to redirect the session to
-    # @option params [optional, String] :from set the from id for the session when redirecting
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [required, String] :to where to redirect the session to
     # @return [String, nil] the JSON string to redirect the current session or nil
     #   if the method has been called from inside a block
     def redirect(params={})
@@ -400,19 +460,22 @@ module Tropo
     #
     # @overload say(params)
     #   @param [Hash] params the options to create a message with.
-    #   @option params [String] :value the text or audio to be spoken or played back to the user
-    #   @option params [Boolean] :event assigns a callback when a particular event occurs
-    #   @option params [Integer] :as instructs the engine on how to handle the grammar
-    #   @option params [Boolean] :format instructs the engine on how to handle the grammar
-    #   @return [String, nil] the JSON string to be passed back to Tropo or nil
-    #     if the method has been called from inside a block
-    # @overload say(value, params)
-    #   @param [String] the text or audio to be spoken or played back to the user
+    #   @option params [required, String] :value the text or audio to be spoken or played back to the user
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Integer] :as specifies the type of data being spoken, so the TTS Engine can interpret it correctly. The possible values are "DATE", "DIGITS" and "NUMBER"
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to say which can be used with REST to interrupt the function 
+    # @overload say(params, &block)
     #   @param [Hash] params the options to create a message with.
-    #   @option params [Boolean] :event assigns a callback when a particular event occurs
-    #   @option params [Integer] :as instructs the engine on how to handle the grammar
-    #   @option params [Boolean] :format instructs the engine on how to handle the grammar
-    #   @return [String, nil] the JSON string to be passed back to Tropo or nil
+    #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
+    #   @option params [required, String] :value the text or audio to be spoken or played back to the user
+    #   @option params [optional, String] :voice (allison) specifies the voice to be used when speaking text to a user
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Integer] :as specifies the type of data being spoken, so the TTS Engine can interpret it correctly. The possible values are "DATE", "DIGITS" and "NUMBER"
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to say which can be used with REST to interrupt the function 
+    # @return [String, nil] the JSON string to be passed back to Tropo or nil
     #     if the method has been called from inside a block
     def say(value=nil, params={})
       
@@ -458,10 +521,11 @@ module Tropo
     # The resulting recording may then be sent via FTP or an HTTP POST/Multipart Form.
     #
     # @param [Hash] params the options to create a message with.
-    # @option params [String] :url a valid URI, an HTTP, FTP or email address to POST the recording file to
+    # @option params [required, String] :url a valid URI, an HTTP, FTP or email address to POST the recording file to
     # @option params [optional, String] :format (audio/wav) the audio format to record in, either a wav or mp3
     # @option params [optional, String] :username if posting to FTP, the username for the FTP server
     # @option params [optional, String] :password if posting to FTP, the password for the FTP server
+    # @option params [optional, String] :method (POST) defines how to send the audio file - values are POST or PUT and applies only to HTTP
     # @return [String, nil] returns the JSON string to start the recording of a session or nil
     #   if the method has been called from inside a block
     def start_recording(params={})
@@ -506,22 +570,34 @@ module Tropo
     #
     # @overload transfer(params)
     #   @param [Hash] params the options to create a transfer action request with
-    #   @option params [String] :name the name to assign to the result when returned to the application, default is true
-    #   @option params [optional, Boolean] :answer_on_media ???
-    #   @option params [optional, Integer] :answer_timeout the amount of time to ring the far side before giving up and going to the next step
-    #   @option params [optional, Boolean] :required (true) ???
-    #   @option params [required, String] :to where to redirect the session to
+    #   @option params [required, String] :to the new destination for the incoming call as a URL
     #   @option params [optional, String] :from set the from id for the session when redirecting
-    #   @option params [optional, Integer] :ring_repeat ???
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
+    #   @option params [optional, Integer] :ring_repeat This specifies the number of times the audio file specified in the ring event will repeat itself.
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Float] :timeout amount of time Tropo will wait--in seconds--for the other party to answer the call
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to record which can be used with REST to interrupt the function 
+    #   @option params [optional, String] :on adds event callback to enable "ring" event, which allows you to play an audio file or say something while the outbound call rings
+    #   @option params [optional, Boolean] :answer_on_media (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc)
+    #   @options params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call
+    #   @option params [optional, String] :choices when used with transfer, this defines the terminator
     # @overload transfer(params, &block)
     #   @param [Hash] params the options to create a transfer action request with
-    #   @option params [String] :name the name to assign to the result when returned to the application, default is true
-    #   @option params [optional, Boolean] :answer_on_media ???
-    #   @option params [optional, Integer] :answer_timeout the amount of time to ring the far side before giving up and going to the next step
-    #   @option params [optional, Boolean] :required (true) ???
-    #   @option params [required, String] :to where to redirect the session to
+    #   @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event
+    #   @option params [required, String] :to the new destination for the incoming call as a URL
     #   @option params [optional, String] :from set the from id for the session when redirecting
-    #   @option params [optional, Integer] :ring_repeat ???
+    #   @option params [optional, Integer] :ring_repeat This specifies the number of times the audio file specified in the ring event will repeat itself.
+    #   @option params [optional, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results
+    #   @option params [optional, Boolean] :required (true) determines whether Tropo should move on to the next verb - if true, Tropo will only move on if the current operation completed
+    #   @option params [optional, Float] :timeout amount of time Tropo will wait--in seconds--for the other party to answer the call
+    #   @option params [optional, Integer] :interdigit_timeout (nil) defines how long to wait between key presses to determine the user has stopped entering input
+    #   @option params [optional, String or Array] :allow_signals allows you to assign a signal to record which can be used with REST to interrupt the function 
+    #   @option params [optional, String] :on adds event callback to enable "ring" event, which allows you to play an audio file or say something while the outbound call rings
+    #   @option params [optional, Boolean] :answer_on_media (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc)
+    #   @options params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call
+    #   @option params [optional, String] :choices when used with transfer, this defines the terminator
     # @return [nil, String]
     def transfer(params={}, &block)
       if block_given?
@@ -550,5 +626,17 @@ module Tropo
     def voice=(voice)
       @voice = voice
     end
+    
+    def wait(params={}, &block)
+      if block_given?
+        create_nested_hash('wait', params)
+        instance_exec(&block)
+        @response[:tropo] << @nested_hash
+      else
+        hash = build_action('wait', params)
+        @response[:tropo] << hash
+      end
+      render_response if @building.nil?
+    end
   end
 end

data/spec/tropo-webapi-ruby_spec.rb

@@ -2,6 +2,9 @@ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe "Tropo" do
 
+
+   response = Tropo::Generator.wait({ :milliseconds => 10, :allowSignals => "exit"})
+
   # Ask action tests (and alias Prompt)
   it "should generate a complete 'ask' JSON document" do
     response = Tropo::Generator.ask({ :name    => 'foo',
@@ -362,15 +365,6 @@ describe "Tropo" do
     @@new_session.should == 'foobar'
   end
 
-  it "should see an object passed into the block" do
-    session = 'foobar'
-    result = Tropo::Generator.new(session) do
-      session.should == 'foobar'
-      say :value => 'blah'
-      on  :event => 'error', :next => 'error.json'
-    end
-  end
-
   it "should allow you to create a Tropo::Generator object and build up a JSON request with two says" do
     tropo = Tropo::Generator.new
     tropo.say('foo')

data/tropo-webapi-ruby.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{tropo-webapi-ruby}
-  s.version = "0.1.11"
+  s.version = "0.1.13"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jason Goecke"]
@@ -14,16 +14,19 @@ Gem::Specification.new do |s|
   s.email = %q{jsgoecke@voxeo.com}
   s.extra_rdoc_files = [
     "LICENSE",
-    "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
-    "HISTORY.rdoc",
+    # "HISTORY.rdoc",
     "LICENSE",
-    "README.rdoc",
+    "README.md",
     "Rakefile",
     "VERSION",
     "examples/sinatra_server.rb",
+    "examples/conferenceJoinLeave.rb",
+    "examples/machineDetection.rb",
+    "examples/transferWhisper.rb",
     "lib/tropo-webapi-ruby.rb",
     "lib/tropo-webapi-ruby/object_patch.rb",
     "lib/tropo-webapi-ruby/tropo-webapi-ruby-helpers.rb",

metadata

@@ -1,13 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tropo-webapi-ruby
 version: !ruby/object:Gem::Version 
-  hash: 13
-  prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 11
-  version: 0.1.11
+  version: 0.1.13
 platform: ruby
 authors: 
 - Jason Goecke
@@ -15,22 +9,15 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-24 00:00:00 -07:00
-default_executable: 
+date: 2011-06-24 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 13
-        segments: 
-        - 1
-        - 2
-        - 9
         version: 1.2.9
   type: :development
   version_requirements: *id001
@@ -38,15 +25,9 @@ dependencies:
   name: json_pure
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 31
-        segments: 
-        - 1
-        - 2
-        - 0
         version: 1.2.0
   type: :runtime
   version_requirements: *id002
@@ -54,15 +35,9 @@ dependencies:
   name: hashie
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 23
-        segments: 
-        - 0
-        - 2
-        - 0
         version: 0.2.0
   type: :runtime
   version_requirements: *id003
@@ -74,15 +49,17 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.md
 files: 
 - .document
-- HISTORY.rdoc
 - LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
+- examples/conferenceJoinLeave.rb
+- examples/machineDetection.rb
 - examples/sinatra_server.rb
+- examples/transferWhisper.rb
 - lib/tropo-webapi-ruby.rb
 - lib/tropo-webapi-ruby/object_patch.rb
 - lib/tropo-webapi-ruby/tropo-webapi-ruby-helpers.rb
@@ -91,41 +68,33 @@ files:
 - spec/spec_helper.rb
 - spec/tropo-webapi-ruby_spec.rb
 - tropo-webapi-ruby.gemspec
-has_rdoc: true
 homepage: http://tropo.com
 licenses: []
 
+metadata: {}
+
 post_install_message: 
 rdoc_options: []
 
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 59
-      segments: 
-      - 1
-      - 8
-      - 6
       version: 1.8.6
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 3
 summary: Tropo Web API Ruby Gem
 test_files: []
 
+has_rdoc: 

data/HISTORY.rdoc

@@ -1,19 +0,0 @@
-= Tropo Release History
-
-== Version 0.1.5
-
-- First public release
-
-== Version 0.1.6
-
-- Added the appropriate ActiveSupport dependency for 'instance_exec' for Ruby 1.8.6 support.
-- Added a dependency and support for Hashie.
-
-== Version 0.1.9
-
-- Fixed the start_recording so it does not require a 'name' parameter
-- Aliased start_call_recording -> start_recording
-- Aliased stop_call_recording -> stop_recording
-- Fixes to the README
-- Fixed the yardoc install
-- The Tropo::Generator.parse method will now take a JSON string or a Ruby hash.