class Tropo::Generator
Attributes
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
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
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
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
Public Class Methods
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 17 def method_missing(method_id, *args, &block) g = Generator.new g.send(method_id, *args, &block) end
Initializes the Generator
class
@overload initialize() @overload initialize(params)
@param [String] voice sets the value of the default voice @param [Object] pass in an object that may be accessed inside the block
@overload initialize(params, &block)
@param [Object] pass in an object that may be accessed inside the block @param [String] voice sets the value of the default voice @param [Block] a block of code to execute (optional)
@return [Object] a new Generator
object
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 35 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 @building = true instance_exec(&block) render_response end end
Public Instance Methods
Prompts initiates a new answer.
@overload answer(params)
@param [Hash] params the options to create a answer action request with. @option params [optional, Hash] :headers A set of key/values
@overload answer(params, &block)
@param [Hash] params the options to create an answer 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, Hash] :headers A set of key/values
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 152 def answer(params={}, &block) if block_given? create_nested_hash('answer', params) instance_exec(&block) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('answer', params) @response[:tropo] << hash end render_response if @building.nil? 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 free-form text.
@overload ask(params)
@param [Hash] params the options to create an ask action request with. @option params [required, Object] :choices indicates the structure of the expected data and acceptable modes of input - value, mode, terminator @option params [required, Object] :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] :allowSignals 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 say or enter a key to stop the prompt from playing further @option params [optional, Integer] :interdigitTimeout (Default: 5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, Integer] :minConfidence (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, Float] :sensitivity (0.5) determines how loud or soft audio needs to be before detecting as an attempt to answer the question @option params [optional, Float]: speechCompleteTimeout (0.5) determines how long the application should wait - in seconds - after input before determining a match @option params [optional, Float]: speechIncompleteTimeout (0.5) determines how long the application should wait - in seconds - after partial input before determining a "no match" @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 @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. @option params [optional, String] :asrLogSecurity Control whether Tropo should log the input from the user in response to the ask method. @option params [optional, String] :maskTemplate When asrLogSecurity is set to "mask", this parameter defines the pattern that should be masked.
@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 [required, Object] :choices indicates the structure of the expected data and acceptable modes of input - value, mode, terminator @option params [required, Object] :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] :allowSignals 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 say or enter a key to stop the prompt from playing further @option params [optional, Integer] :interdigitTimeout (Default: 5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, Integer] :minConfidence (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, Float] :sensitivity (0.5) determines how loud or soft audio needs to be before detecting as an attempt to answer the question @option params [optional, Float]: speechCompleteTimeout (0.5) determines how long the application should wait - in seconds - after input before determining a match @option params [optional, Float]: speechIncompleteTimeout (0.5) determines how long the application should wait - in seconds - after partial input before determining a "no match" @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 @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. @option params [optional, String] :asrLogSecurity Control whether Tropo should log the input from the user in response to the ask method. @option params [optional, String] :maskTemplate When asrLogSecurity is set to "mask", this parameter defines the pattern that should be masked.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 97 def ask(params={}, &block) params = set_language(params) if block_given? @ask_hash = {:ask => build_elements(params)} #create_nested_hash('ask', params) instance_exec(&block) has_params?(@ask_hash[:ask], 'ask', ['choices', 'say']) if @nested_on_hash if @nested_on_hash[:on][0][:ask].nil? @nested_on_hash[:on][0][:ask] = @ask_hash[:ask] elsif @nested_on_hash[:on][0][:ask].is_a? Array @nested_on_hash[:on][0][:ask] << @ask_hash[:ask] else ask = @nested_on_hash[:on][0][:ask] @nested_on_hash[:on][0][:ask] = Array.new @nested_on_hash[:on][0][:ask] << ask @nested_on_hash[:on][0][:ask] << @ask_hash[:ask] end else @response[:tropo] << @ask_hash @ask_hash = nil end else hash = build_action('ask', params) if @nested_on_hash if @nested_on_hash[:on][0][:ask].nil? @nested_on_hash[:on][0][:ask] = hash[:ask] elsif @nested_on_hash[:on][0][:ask].is_a? Array @nested_on_hash[:on][0][:ask] << hash[:ask] else ask = @nested_on_hash[:on][0][:ask] @nested_on_hash[:on][0][:ask] = Array.new @nested_on_hash[:on][0][:ask] << ask @nested_on_hash[:on][0][:ask] << hash[:ask] end else @response[:tropo] << hash end end render_response if @building.nil? end
Prompts initiates a new call. May only be used when no call is active.
@overload call(params)
@param [Hash] params the options to create a call action request with. @option params [required, 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 or Array] :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, Float] :timeout (30) the amount of time, in seconds, to wait for a response before moving on @option params [optional, Boolean] :answerOnMedia (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc) @option params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call @option params [optional, Boolean or Hash] :machineDetection (false) determines if a call is coming from machine or human @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] :allowSignals allows you to assign a signal to call which can be used with REST to interrupt the function @option params [optional, String] :voice ""(undefined) sets the voice in a call; all prompt action within the call will inherit the same voice defined here @option params [optional, String] :callbackUrl Configures a URL for a webhook for CDRs to be sent at the completion of the call. @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. @option params [optional, String] :label Set by you, an arbitrary label for this call. The label you set will appear in your CDR, allowing you to track a CDR by a string you define.
@overload call(params, &block)
@param [Hash] params the options to create an call action request with. @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event @option params [required, 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 or Array] :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 (voice) the channel the call will be initiated over, may be TEXT or VOICE @option params [optional, Float] :timeout (30) the amount of time, in seconds, to wait for a response before moving on @option params [optional, Boolean] :answerOnMedia (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc) @option params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call @option params [optional, Boolean or Hash] :machineDetection (false) determines if a call is coming from machine or human @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] :allowSignals allows you to assign a signal to call which can be used with REST to interrupt the function @option params [optional, String] :voice ""(undefined) sets the voice in a call; all prompt action within the call will inherit the same voice defined here @option params [optional, String] :callbackUrl Configures a URL for a webhook for CDRs to be sent at the completion of the call. @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. @option params [optional, String] :label Set by you, an arbitrary label for this call. The label you set will appear in your CDR, allowing you to track a CDR by a string you define.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 207 def call(params={}, &block) if block_given? create_nested_hash('call', params) instance_exec(&block) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('call', params) @response[:tropo] << hash end render_response if @building.nil? end
Choices to give the user on input
@param [Hash] params the options used to construct the grammar for the user @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] :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
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 230 def choices(params={}) hash = build_action('choices', params) if @ask_hash @ask_hash[:ask].merge!(hash) elsif @nested_hash @nested_hash[@nested_name.to_sym].merge!(hash) else @response[:tropo] << hash render_response if @building.nil? end end
Creates a conference or pushes a user to an existing conference
@overload conference(params)
@param [Hash] params the options to create a conference with. @option params [required, 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] :id the number to assign to the conference room @option params [optional, Float] :interdigitTimeout (5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, Boolean or Hash] :joinPrompt (false) determines a prompt that plays to all participants of a conference when someone joins the conference @option params [optional, Boolean or Hash] :leavePrompt (false) determines a prompt that plays to all participants of a conference when someone leaves the conference @option params [optional, Boolean] :mute (false) whether to mute this caller in the conference @option params [optional, Boolean] :playTones (false) 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] :allowSignals allows you to assign a signal to conference which can be used with REST to interrupt the function @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method.
@overload conference(params, &block)
@param [Hash] params the options to create a conference with. @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event @option params [required, 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] :id the number to assign to the conference room @option params [optional, Float] :interdigitTimeout (5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, Boolean or Hash] :joinPrompt (false) determines a prompt that plays to all participants of a conference when someone joins the conference @option params [optional, Boolean or Hash] :leavePrompt (false) determines a prompt that plays to all participants of a conference when someone leaves the conference @option params [optional, Boolean] :mute (false) whether to mute this caller in the conference @option params [optional, Boolean] :playTones (false) 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] :allowSignals allows you to assign a signal to conference which can be used with REST to interrupt the function @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 275 def conference(params={}, &block) if block_given? create_nested_hash('conference', params) instance_exec(&block) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('conference', params) @response[:tropo] << hash end render_response if @building.nil? end
that can turn off all logging on the Tropo
platform
@overload generalLogSecurity(params)
@param [Hash] params the options to create a message with. @option params [required, String] :state Set to "suppress" to disable all logging in Tropo. Set to "none" to turn off log suppression and begin logging again.
@overload generalLogSecurity(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 [required, String] :state Set to "suppress" to disable all logging in Tropo. Set to "none" to turn off log suppression and begin logging again.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 891 def generalLogSecurity(params={}, &block) if block_given? create_nested_hash('generalLogSecurity', params) instance_exec(&block) @response[:tropo] << @nested_hash else hash = build_action('generalLogSecurity', params) @response[:tropo] << hash end render_response if @building.nil? end
@param [resultactions]: result object actions @param [actionName]: action name @return [String] a String representing the value field 'concept' of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 488 def getConceptByActionName(resultactions, actionName) resultactions[actionName]['concept'] end
@param [resultactions]: result object actions @param [actionName]: action name @return [String] a String representing the value field 'disposition' of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 461 def getDispositionByActionName(resultactions, actionName) resultactions[actionName]['disposition'] end
@param [resultactions]: result object actions @param [actionName]: action name @param [fieldName]: field name @return [String] a String representing the value field of fieldName of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 498 def getFieldValueByActionNameFieldName(resultactions, actionName, fieldName) resultactions[actionName][fieldName] end
@param [resultactions]: result object actions @param [actionName]: action name @return [String] a String representing the value field 'interpretation' of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 470 def getInterpretationByActionName(resultactions, actionName) resultactions[actionName]['interpretation'] end
@param [resultactions]: result object actions @param [actionName]: action name @return [String] a String representing the value field 'uploadStatus' of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 452 def getUploadStatusByActionName(resultactions, actionName) resultactions[actionName]['uploadStatus'] end
@param [resultactions]: result object actions @param [actionName]: action name @return [String] a String representing the value field 'utterance' of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 479 def getUtteranceByActionName(resultactions, actionName) resultactions[actionName]['utterance'] end
@param [resultactions]: result object actions @param [actionName]: action name @return [String] a String representing the value field 'value' of action named actionName
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 443 def getValueByActionName(resultactions, actionName) resultactions[actionName]['value'] end
This function instructs Tropo
to “hang-up” or disconnect the current session.
May trigger these events:
- hangup - error
@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
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 297 def hangup @response[:tropo] << { :hangup => nil } render_response if @building.nil? end
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.
@overload message(params)
@param [Hash] params the options to create a message action request with. @option params [required, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results @option params [required, Object] :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 or Array] :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 (VOICE) the channel the call will be initiated over, may be TEXT or VOICE @option params [optional, Float] :timeout (30) the amount of time, in seconds, to wait for a response before moving on @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] :answerOnMedia (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc) @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method.
@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 [required, String] :name this is the key used to identify the result of an operation, so you can differentiate between multiple results @option params [required, Object] :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 or Array] :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 (VOICE) the channel the call will be initiated over, may be TEXT or VOICE @option params [optional, Float] :timeout (30) the amount of time, in seconds, to wait for a response before moving on @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] :answerOnMedia (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc) @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 336 def message(params={}, &block) if block_given? @nested_hash = {:message => build_elements(params)} @nested_name = 'message' instance_exec(&block) has_params?(@nested_hash[:message], 'message', ['say', 'to', 'name']) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('message', params) @response[:tropo] << hash end render_response if @building.nil? end
Sets event handlers to call a REST resource when a particular event occurs
@overload initialize(params)
@param [Hash] params the options to create a message with. @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 params [optional, String] :post This parameter is only available in the 'connect' event of transfer.
@overload initialize(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 [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 params [optional, String] :post This parameter is only available in the 'connect' event of transfer.
@option [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 370 def on(params={}, &block) if block_given? if @nested_hash create_nested_on_hash(params) instance_exec(&block) if @nested_hash[@nested_name.to_sym][:on].nil? @nested_hash[@nested_name.to_sym][:on] = Array.new end @nested_on_hash[:on].each do |hash| @nested_hash[@nested_name.to_sym][:on] << hash end @nested_on_hash = nil @nested_on_hash_cnt = nil else @on_hash = { :on => build_action('on', params)} instance_exec(&block) @response[:tropo] << @on_hash @on_hash = nil end else create_on_hash hash = build_action('on', params) # @on_hash[:on] << hash if @nested_hash if @nested_hash[@nested_name.to_sym][:on].nil? @nested_hash[@nested_name.to_sym][:on] = Array.new end @nested_hash[@nested_name.to_sym][:on] << hash else @on_hash = nil @response[:tropo] << { :on => hash } render_response if @building.nil? end end end
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
@param [String or Hash] a JSON string or a Ruby Hash @return [Hash] a Hash representing the formatted response from Tropo
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 413 def parse(response) response = JSON.parse(response) if response.class == String # 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' => { } } response['result'].each_pair do |key, value| value = transform_hash value if value.kind_of? Hash value = transform_array value if value.kind_of? Array transformed_response['result'].merge!(transform_pair(key, value)) end end transformed_response = Hashie::Mash.new(transformed_response) end
Sets the default recognizer for the object
@param [String] recognizer the value to set the default voice to
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 506 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. 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)
@param [Hash] params the options to create a message with. @option params [optional, Integer] :attempts (1) the number of times to prompt the user for input @option params [optional, Boolean] :asyncUpload (false) instruct Tropo to upload the recording file in the background as soon as the recording is completed @option params [optional, String or Array] :allowSignals 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, Object] :choices when used with record, this defines the terminator @option params [optional, Object] :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] :maxSilence (5.0) the max amount of time in seconds to wait for silence before considering the user finished speaking @option params [optional, Float] :maxTime (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 [required, 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, Array or Object] :transcription allows you to submit a recording to be transcribed - takes parameters id, url and emailFormat @option params [required, 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, Float] :timeout (30.0) 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, Float] :interdigitTimeout (5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method.
@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 [optional, Integer] :attempts (1) the number of times to prompt the user for input @option params [optional, Boolean] :asyncUpload (false) instruct Tropo to upload the recording file in the background as soon as the recording is completed @option params [optional, String or Array] :allowSignals 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, Object] :choices when used with record, this defines the terminator @option params [optional, Object] :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] :maxSilence (5.0) the max amount of time in seconds to wait for silence before considering the user finished speaking @option params [optional, Float] :maxTime (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 [required, 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, Array or Object] :transcription allows you to submit a recording to be transcribed - takes parameters id, url and emailFormat @option params [required, 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, Float] :timeout (30.0) 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, Float] :interdigitTimeout (5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method.
@option [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 566 def record(params={}, &block) if block_given? @nested_hash = {:record => build_elements(params)} @nested_name = 'record' instance_exec(&block) has_params?(@nested_hash[:record], 'record', ['url']) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('record', params) @response[:tropo] << hash end render_response if @building.nil? end
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.
@param [Hash] params the options to create a message with.
@option params [required, 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
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 594 def redirect(params={}) hash = build_action('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, and then use the reject call accordingly.
@return [String, nil] the JSON string to reject the current session or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 607 def reject @response[:tropo] << { :reject => nil } render_response if @building.nil? end
Resets the action hash if one desires to reuse the same Generator
object
@return [nil]
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 624 def reset @response = { :tropo => Array.new } @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:
Wav 8bit 8khz Ulaw MP3
@overload say(params)
@param [Hash] params the options to create a message with. @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 [required, 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, String] :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] :allowSignals allows you to assign a signal to say which can be used with REST to interrupt the function @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method.
@overload say(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 [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 [required, 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, String] :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] :allowSignals allows you to assign a signal to say which can be used with REST to interrupt the function @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 657 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 params[:value] = value elsif value.kind_of? Hash params = value elsif value.kind_of? Array params = value else raise ArgumentError, "An invalid paramater type #{value.class} has been passed" end response = { :say => Array.new } if params.kind_of? Array params.each do |param| param = set_language(param) hash = build_action('nestedSay', param) response[:say] << hash end else params = set_language(params) if @on_hash || @ask_hash || @nested_hash hash = build_action('nestedSay', params) else hash = build_action('say', params) end response = { :say => hash } end if @ask_hash if @ask_hash[:ask][:say].nil? @ask_hash[:ask][:say] = response[:say] elsif @ask_hash[:ask][:say].is_a? Array @ask_hash[:ask][:say] << response[:say] else say = @ask_hash[:ask][:say] @ask_hash[:ask][:say] = Array.new @ask_hash[:ask][:say] << say @ask_hash[:ask][:say] << response[:say] end elsif @on_hash && @nested_on_hash.nil? @on_hash[:on].merge!(response) elsif @nested_hash && @nested_on_hash.nil? @nested_hash[@nested_name.to_sym].merge!(response) elsif @nested_on_hash if @nested_on_hash[:on][0][:say].nil? @nested_on_hash[:on][0][:say] = response[:say] elsif @nested_on_hash[:on][0][:say].is_a? Array @nested_on_hash[:on][0][:say] << response[:say] else say = @nested_on_hash[:on][0][:say] @nested_on_hash[:on][0][:say] = Array.new @nested_on_hash[:on][0][:say] << say @nested_on_hash[:on][0][:say] << response[:say] end # @nested_on_hash[:on][@nested_on_hash_cnt].merge!(response) # @nested_on_hash_cnt += 1 else @response[:tropo] << response render_response if @building.nil? end end
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. @option params [optional, Boolean] :asyncUpload (false) instruct Tropo
to upload the recording file in the background as soon as the recording is completed @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] :transcriptionEmailFormat specifies the encoding used when delivering transcriptions via e-mail @option params [optional, String] :transcriptionID determines user definable ID that can be included when the transcription is posted to transcriptionOutURI @option params [optional, String] :transcriptionOutURI determines to anything enables transcription on this recording @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
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 739 def start_recording(params={}) if block_given? create_nested_hash('start_recording', params) instance_exec(&block) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('start_recording', params) @response[:tropo] << hash end render_response if @building.nil? end
Stops the recording of the current session after startCallRecording has been called
@return [String, nil] returns the JSON string to stop the recording of a session or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 759 def stop_recording @response[:tropo] << { :stopRecording => nil } render_response if @building.nil? end
Returns the current hash object of the response, as opposed to JSON
@return [Hash] the current hash of the response
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 841 def to_hash @response end
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
When this method is called the following occurs:
The audio file specified in playvalue is played to the existing call. This could be "hold music", a ring-back sound, etc. The audio file is played up to playrepeat times. While audio is playing, a new call is initiated to the specified "to" address using the callerID specified. If answerOnMedia is true, the audio from the new call is connected to the existing call immediately. The system waits for an answer or other event from the new call up to the timeout. If the call successfully completes within the timeout, the existing call and new call will be connected, onSuccess will be called, and the transfer call will return a success event. If the call fails before the timeout, onCallFailure will be called and the method will return an onCallFailure event. If the call fails due to the timeout elapsing, onTimeout will be called and the method will return a timeout event
@overload transfer(params)
@param [Hash] params the options to create a transfer action request with @option params [required, String or Array] :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] :ringRepeat (1) This specifies the number of times the audio file specified in the ring event will repeat itself. @option params [required, 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 (30) amount of time Tropo will wait--in seconds--for the other party to answer the call @option params [optional, Float] :interdigitTimeout (5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, String or Array] :allowSignals allows you to assign a signal to record which can be used with REST to interrupt the function @option params [optional, Boolean or Hash] :machineDetection (false) determines if a call is coming from machine or human @option params [optional, Object] :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] :answerOnMedia (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc) @option params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call @option params [optional, Object] :choices when used with transfer, this defines the terminator @option params [optional, Boolean] :playTones (true) Controls whether or not each party can hear the tone generated when a key on the phone is pressed by the other party. @option params [optional, String] :voice (allison) Specifies the default voice to be used when speaking text back to a user. @option params [optional, String] :callbackUrl Configures a URL for a webhook for CDRs to be sent at the completion of the call. @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method @option params [optional, String] :label Set by you, an arbitrary label for this call. The label you set will appear in your CDR, allowing you to track a CDR by a string you define
@overload transfer(params, &block)
@param [Hash] params the options to create a transfer action request with @param [Block] takes a block so that you may trigger actions, such as a say, on a specific event @option params [required, String or Array] :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] :ringRepeat (1) This specifies the number of times the audio file specified in the ring event will repeat itself. @option params [required, 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 (30) amount of time Tropo will wait--in seconds--for the other party to answer the call @option params [optional, Float] :interdigitTimeout (5.0) defines how long to wait between key presses to determine the user has stopped entering input @option params [optional, String or Array] :allowSignals allows you to assign a signal to record which can be used with REST to interrupt the function @option params [optional, Boolean or Hash] :machineDetection (false) determines if a call is coming from machine or human @option params [optional, Object] :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] :answerOnMedia (false) if true, the call will be concisdered answered and audio will being playing as soon as media is received (ringing, busy, etc) @option params [optional, Hash] :headers A set of key/values to apply as customer SIP headers to the outgoing call @option params [optional, Object] :choices when used with transfer, this defines the terminator @option params [optional, Boolean] :playTones (true) Controls whether or not each party can hear the tone generated when a key on the phone is pressed by the other party. @option params [optional, String] :voice (allison) Specifies the default voice to be used when speaking text back to a user. @option params [optional, String] :callbackUrl Configures a URL for a webhook for CDRs to be sent at the completion of the call. @option params [optional, String] :promptLogSecurity Controls whether Tropo logs the text to speech string used by the method. Possible values are "none" (the default) and "suppress", which disables output logging for this method @option params [optional, String] :label Set by you, an arbitrary label for this call. The label you set will appear in your CDR, allowing you to track a CDR by a string you define
@return [nil, String]
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 823 def transfer(params={}, &block) if block_given? create_nested_hash('transfer', params) instance_exec(&block) @response[:tropo] << @nested_hash @nested_hash = nil @nested_name = nil else hash = build_action('transfer', params) @response[:tropo] << hash end render_response if @building.nil? end
Sets the default voice for the object
@param [String] voice the value to set the default voice to
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 849 def voice=(voice) @voice = voice end
The wait function suspends the script's current thread of execution for the specified length of time, or until the active session changes state (such as a user hanging up), whichever occurs first.
@overload wait(params)
@param [Hash] params the options to create a message with. @option params [optional, String or Array] :allowSignals This parameter allows you to assign a signal to this function. @option params [required, Integer] :milliseconds This defines the time to wait for a state change. Defaults to 0ms if the parameter is skipped.
@overload wait(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 [optional, String or Array] :allowSignals This parameter allows you to assign a signal to this function. @option params [required, Integer] :milliseconds This defines the time to wait for a state change. Defaults to 0ms if the parameter is skipped.
@return [String, nil] the JSON string to be passed back to Tropo
or nil
if the method has been called from inside a block
# File lib/tropo-webapi-ruby/tropo-webapi-ruby.rb, line 867 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