diff --git a/README.rdoc b/README.rdoc index 6e44bb8..960156a 100644 --- a/README.rdoc +++ b/README.rdoc @@ -87,30 +87,30 @@ Using the great RESTful Web Services framework Sinatra for Ruby. # Produces a Ruby hash: # - # { :session => - # { :timestamp => Tue Jan 19 18:27:46 -0500 2010, - # :user_type =>"HUMAN", + # { :session => + # { :timestamp => Tue Jan 19 18:27:46 -0500 2010, + # :user_type =>"HUMAN", # :initial_text => nil, - # :account_id =>"0", - # :headers => [{ "value" => "70", "key"=>"Max-Forwards" }, - # { "value" => "385", "key"=>"Content-Length" }, - # { "value" => "", "key"=>"Contact" }, - # { "value" => "replaces", "key"=>"Supported" }, - # { "value" => "", "key"=>"To" }, - # { "value" => "1 INVITE", "key"=>"CSeq" }, - # { "value" => "SJphone-M/1.65.382f (SJ Labs)", "key"=>"User-Agent" }, - # { "value" => "SIP/2.0/UDP 127.0.0.1:49152;branch=z9000000a9;rport=49152", "key"=>"Via" }, - # { "value" => "3FA7C70A1DD211B286B7A583D7B46DDD0xac106207", "key"=>"Call-ID" }, - # { "value" => "application/sdp", "key"=>"Content-Type" }, + # :account_id =>"0", + # :headers => [{ "value" => "70", "key"=>"Max-Forwards" }, + # { "value" => "385", "key"=>"Content-Length" }, + # { "value" => "", "key"=>"Contact" }, + # { "value" => "replaces", "key"=>"Supported" }, + # { "value" => "", "key"=>"To" }, + # { "value" => "1 INVITE", "key"=>"CSeq" }, + # { "value" => "SJphone-M/1.65.382f (SJ Labs)", "key"=>"User-Agent" }, + # { "value" => "SIP/2.0/UDP 127.0.0.1:49152;branch=z9000000a9;rport=49152", "key"=>"Via" }, + # { "value" => "3FA7C70A1DD211B286B7A583D7B46DDD0xac106207", "key"=>"Call-ID" }, + # { "value" => "application/sdp", "key"=>"Content-Type" }, # { "value" => "unknown ;tag=750b1b1648e9c876", "key"=>"From" }], - # :id => "3FA7C70A1DD211B286B7A583D7B46DDD0xac106207", - # :to => { :network => "PSTN", - # :channel => "VOICE", - # :name => "unknown", - # :id => "sample.json"}, - # :from => { :network => "PSTN", - # :channel => "VOICE", - # :name => "unknown", + # :id => "3FA7C70A1DD211B286B7A583D7B46DDD0xac106207", + # :to => { :network => "PSTN", + # :channel => "VOICE", + # :name => "unknown", + # :id => "sample.json"}, + # :from => { :network => "PSTN", + # :channel => "VOICE", + # :name => "unknown", # :id => "unknown"}}} # post '/start_session.json' do @@ -124,8 +124,8 @@ Using the great RESTful Web Services framework Sinatra for Ruby. tropo = Tropo::Generator.new do on :event => 'hangup', :next => '/hangup.json' on :event => 'continue', :next => '/answer.json' - ask({ :name => 'account_number', - :bargein => true, + ask({ :name => 'account_number', + :bargein => true, :timeout => 30, :require => 'true' }) do say :value => 'Please say your account number' @@ -137,18 +137,18 @@ Using the great RESTful Web Services framework Sinatra for Ruby. # Produces a Ruby hash, if the user gives a response before hanging up: # - # { :result => - # { :actions => { :attempts => 1, - # :disposition => "SUCCESS", - # :interpretation => "12345", - # :confidence => 100, - # :name => "account_number", - # :utterance => "1 2 3 4 5" }, - # :session_duration => 3, - # :error => nil, - # :sequence => 1, - # :session_id => "5325C262-1DD2-11B2-8F5B-C16F64C1D62E@127.0.0.1", - # :state => "ANSWERED", + # { :result => + # { :actions => { :attempts => 1, + # :disposition => "SUCCESS", + # :interpretation => "12345", + # :confidence => 100, + # :name => "account_number", + # :utterance => "1 2 3 4 5" }, + # :session_duration => 3, + # :error => nil, + # :sequence => 1, + # :session_id => "5325C262-1DD2-11B2-8F5B-C16F64C1D62E@127.0.0.1", + # :state => "ANSWERED", # :complete => true } } # post '/answer.json' do @@ -157,13 +157,13 @@ Using the great RESTful Web Services framework Sinatra for Ruby. end # Produces a Ruby hash, if the user hangs up before giving a reponse - # { :result => - # { :actions => {}, - # :session_duration => 1, - # :error => nil, - # :sequence => 1, - # :session_id => "812BEF50-1DD2-11B2-8F5B-C16F64C1D62E@127.0.0.1", - # :state => "DISCONNECTED", + # { :result => + # { :actions => {}, + # :session_duration => 1, + # :error => nil, + # :sequence => 1, + # :session_id => "812BEF50-1DD2-11B2-8F5B-C16F64C1D62E@127.0.0.1", + # :state => "DISCONNECTED", # :complete => true } } # post '/hangup.json' do @@ -190,7 +190,7 @@ Using the great RESTful Web Services framework Sinatra for Ruby. post '/speak.json' do t = Tropo::Generator.new(:voice => 'kate') t.say 'Hello!' # Will speak as kate now - + # or t = Tropo::Generator.new @@ -203,7 +203,7 @@ Using the great RESTful Web Services framework Sinatra for 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 - :bargein => true, + :bargein => true, :timeout => 30, :require => 'true' }) do say :value => "S'il vous plaît dire votre numéro de compte", :voice => 'florence' @@ -215,7 +215,7 @@ Using the great RESTful Web Services framework Sinatra for Ruby. t = Tropo::Generator.new t.recognizer = 'fr-fr' t.ask({ :name => 'account_number', # Will now use the French speech recognition engine - :bargein => true, + :bargein => true, :timeout => 30, :require => 'true' }) do say :value => "S'il vous plaît dire votre numéro de compte", :voice => 'florence' diff --git a/examples/sinatra_server.rb b/examples/sinatra_server.rb index e578acf..ca25363 100644 --- a/examples/sinatra_server.rb +++ b/examples/sinatra_server.rb @@ -7,8 +7,8 @@ post '/index.json' do tropo = Tropo::Generator.new do on :event => 'continue', :next => '/the_answer.json' - ask({ :name => 'account_number', - :bargein => 'true', + ask({ :name => 'account_number', + :bargein => 'true', :timeout => 30, :require => 'true' }) do say :value => 'Please enter your account number' @@ -35,8 +35,8 @@ tropo = Tropo::Generator.new do on :event => 'hangup', :next => '/hangup.json' on :event => 'continue', :next => '/answer.json' - ask({ :name => 'account_number', - :bargein => 'true', + ask({ :name => 'account_number', + :bargein => 'true', :timeout => 30, :require => 'true' }) do say :value => 'Please say your account number' @@ -84,8 +84,8 @@ end post '/conference.json' do - tropo = Tropo::Generator.conference({ :name => 'foo', - :id => '1234', + tropo = Tropo::Generator.conference({ :name => 'foo', + :id => '1234', :mute => false, :send_tones => false, :exit_tone => '#' }) do @@ -127,8 +127,8 @@ end post '/record.json' do - response = Tropo::Generator.record({ :name => 'foo', - :url => 'http://sendme.com/tropo', + response = Tropo::Generator.record({ :name => 'foo', + :url => 'http://sendme.com/tropo', :beep => true, :send_tones => false, :exit_tone => '#' }) do diff --git a/lib/tropo-webapi-ruby/tropo-webapi-ruby.rb b/lib/tropo-webapi-ruby/tropo-webapi-ruby.rb index 45f93b4..2431fba 100644 --- a/lib/tropo-webapi-ruby/tropo-webapi-ruby.rb +++ b/lib/tropo-webapi-ruby/tropo-webapi-ruby.rb @@ -1,14 +1,14 @@ # @author Jason Goecke module Tropo - class Generator + class Generator include Tropo::Helpers - + ## - # Set a couple of Booleans to indicate the session type as a convenience + # Set a couple of Booleans to indicate the session type as a convenience # Set a default voice for speech synthesis # Set a default recognizer for speech recognition attr_reader :voice_session, :text_session, :voice, :recognizer - + ## # Defines the actions on self so that we may call them individually # @@ -19,7 +19,7 @@ def method_missing(method_id, *args, &block) g.send(method_id, *args, &block) end end - + ## # Initializes the Generator class # @@ -36,7 +36,7 @@ def initialize(params={}, &block) @response = { :tropo => Array.new } @voice = params[:voice] if params[:voice] @recognizer = params[:recognizer] if params[:recognizer] - + if block_given? # Lets us know were are in the midst of building a block, so we only rendor the JSON # response at the end of executing the block, rather than at each action @@ -45,10 +45,10 @@ def initialize(params={}, &block) render_response end end - + ## - # Prompts the user (audio file or text to speech) and optionally waits for a response from the user. - # If collected, responses may be in the form of DTMF, speech recognition or text using a grammar or + # Prompts the user (audio file or text to speech) and optionally waits for a response from the user. + # If collected, responses may be in the form of DTMF, speech recognition or text using a grammar or # free-form text. # # @overload ask(params) @@ -83,7 +83,7 @@ def ask(params={}, &block) render_response if @building.nil? end alias :prompt :ask - + ## # Prompts initiates a new call. May only be used when no call is active. # @@ -94,7 +94,7 @@ def ask(params={}, &block) # @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 (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) @@ -105,7 +105,7 @@ def ask(params={}, &block) # @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 (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 # @return [String, nil] the JSON string to be passed back to Tropo or nil @@ -121,7 +121,7 @@ def call(params={}, &block) end render_response if @building.nil? end - + ## # Choices to give the user on input # @@ -134,7 +134,7 @@ def call(params={}, &block) # if the method has been called from inside a block def choices(params={}) hash = build_action('choices', params) - + if @nested_hash @nested_hash[@nested_name.to_sym].merge!(hash) else @@ -142,7 +142,7 @@ def choices(params={}) render_response if @building.nil? end end - + ## # Creates a conference or pushes a user to an existing conference # @@ -176,7 +176,7 @@ def conference(params={}, &block) end render_response if @building.nil? end - + ## # This function instructs Tropo to "hang-up" or disconnect the current session. # @@ -188,10 +188,10 @@ def conference(params={}, &block) # if the method has been called from inside a block def hangup @response[:tropo] << { :hangup => nil } - render_response if @building.nil? + render_response if @building.nil? end alias :disconnect :hangup - + ## # Message initiates a new message to a destination and then hangs up on that destination. Also takes a say method # in order to deliver a message to that desintation and then hangup. @@ -203,7 +203,7 @@ def hangup # @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 (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) @@ -214,7 +214,7 @@ def hangup # @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 (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 # @return [String, nil] the JSON string to be passed back to Tropo or nil @@ -230,7 +230,7 @@ def message(params={}, &block) end render_response if @building.nil? end - + ## # Sets event handlers to call a REST resource when a particular event occurs # @@ -266,7 +266,7 @@ def on(params={}, &block) end ## - # Parses the JSON string recieved from Tropo into a Ruby Hash, or + # Parses the JSON string recieved from Tropo into a Ruby Hash, or # if already a Ruby Hash parses it with the nicities provided by # the gem # @@ -278,12 +278,12 @@ def parse(response) # Check to see what type of response we are working with if response['session'] transformed_response = { 'session' => { } } - + response['session'].each_pair do |key, value| value = transform_hash value if value.kind_of? Hash transformed_response['session'].merge!(transform_pair(key, value)) end - + elsif response['result'] transformed_response = { 'result' => { } } @@ -296,7 +296,7 @@ def parse(response) transformed_response = Hashie::Mash.new(transformed_response) end - + ## # Sets the default recognizer for the object # @@ -304,12 +304,12 @@ def parse(response) def recognizer=(recognizer) @recognizer = recognizer end - + ## - # Plays a prompt (audio file or text to speech) and optionally waits for a response from the caller that is recorded. - # If collected, responses may be in the form of DTMF or speech recognition using a simple grammar format defined below. - # The record funtion is really an alias of the prompt function, but one which forces the record option to true regardless of how it is (or is not) initially set. - # At the conclusion of the recording, the audio file may be automatically sent to an external server via FTP or an HTTP POST/Multipart Form. + # Plays a prompt (audio file or text to speech) and optionally waits for a response from the caller that is recorded. + # If collected, responses may be in the form of DTMF or speech recognition using a simple grammar format defined below. + # The record funtion is really an alias of the prompt function, but one which forces the record option to true regardless of how it is (or is not) initially set. + # At the conclusion of the recording, the audio file may be automatically sent to an external server via FTP or an HTTP POST/Multipart Form. # If specified, the audio file may also be transcribed and the text returned to you via an email address or HTTP POST/Multipart Form. # # @overload record(params) @@ -342,10 +342,10 @@ def record(params={}, &block) end render_response if @building.nil? end - + ## - # The redirect function forwards an incoming call to another destination / phone number 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. + # The redirect function forwards an incoming call to another destination / phone number 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 #) @@ -361,10 +361,10 @@ def redirect(params={}) @response[:tropo] << hash render_response if @building.nil? end - + ## - # Allows Tropo applications to reject incoming calls before they are answered. - # For example, an application could inspect the callerID variable to determine if the caller is known, + # Allows Tropo applications to reject incoming calls before they are answered. + # For example, an application could inspect the callerID variable to determine if the caller is known, # and then use the reject call accordingly. # # @return [String, nil] the JSON string to reject the current session or nil @@ -373,7 +373,7 @@ def reject @response[:tropo] << { :reject => nil } render_response if @building.nil? end - + ## # Renders the JSON string to be sent to Tropo to execute a set of actions # @@ -381,7 +381,7 @@ def reject def response @response.to_json end - + ## # Resets the action hash if one desires to reuse the same Generator object # @@ -391,7 +391,7 @@ def reset @voice_session = false @text_session = false end - + ## # Plays a prompt (audio file, text to speech or text for IM/SMS). There is no ability to wait for a response from a user. # An audio file used for playback may be in one of the following two formats: @@ -415,7 +415,7 @@ def reset # @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={}) - + # This will allow a string to be passed to the say, as opposed to always having to specify a :value key/pair, # or still allow a hash or Array to be passed as well if value.kind_of? String @@ -427,7 +427,7 @@ def say(value=nil, params={}) else raise ArgumentError, "An invalid paramater type #{value.class} has been passed" end - + response = { :say => Array.new } if params.kind_of? Array @@ -441,7 +441,7 @@ def say(value=nil, params={}) hash = build_action('say', params) response[:say] << hash end - + if @nested_hash && @nested_on_hash.nil? @nested_hash[@nested_name.to_sym].merge!(response) elsif @nested_on_hash @@ -452,9 +452,9 @@ def say(value=nil, params={}) render_response if @building.nil? end end - + ## - # Allows Tropo applications to begin recording the current session. + # Allows Tropo applications to begin recording the current session. # 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. @@ -487,10 +487,10 @@ def stop_recording render_response if @building.nil? end alias :stop_call_recording :stop_recording - + ## - # Transfers an already answered call to another destination / phone number. - # Call may be transferred to another phone number or SIP address, which is set through the "to" parameter and is in URL format. + # Transfers an already answered call to another destination / phone number. + # Call may be transferred to another phone number or SIP address, which is set through the "to" parameter and is in URL format. # Supported formats include: # tel: classic phone number (See RFC 2896), must be proceeded by a + and the country code (ie - +14155551212 for a US #) # sip: SIP protocol address @@ -534,7 +534,7 @@ def transfer(params={}, &block) end render_response if @building.nil? end - + ## # Returns the current hash object of the response, as opposed to JSON # @@ -542,7 +542,7 @@ def transfer(params={}, &block) def to_hash @response end - + ## # Sets the default voice for the object #