Tropo is part of CiscoLearn More

ask

Ask is essentially a say that requires input; it requests information from the caller and waits for a response. The ask method audibly prompts the user for input. This can be in the form of synthesized speech or an audio file. Responses can be collected by speech or touch-tone keypad (DTMF).

Note
Using Ask for SMS is NOT recommended. Your app behavior is unpredictable if ask is used, and a future release will block the use of ask in SMS entirely. SMS is not a synchronous medium, users can reply outside of the defined timeout value and your app will have no method to associate the response with the initial sent SMS. To track state on SMS, your best bet is to use a say and work with a database or other method to track state externally.

Since Tropo is synchronous, ask is a blocking method. This means no other method can run until the ask is completed. Callbacks can fire (such as returning to the original ask prompt when a bad choice is made) because the initial ask completes and is subsequently reinitiated.

Parameters

text

String
(Required)

In the case of a voice session, this can either be the text to be rendered by the Text to Speech Engine (may also be SSML), or a URL to an audio file to be played. In the case of a text messaging session, this will be the text to be sent to the user.

Map Parameters

allowSignals

String or Array
Default: 
* (any signal)

This parameter allows you to assign a signal to this function. Events from the Tropo REST API with a matching signal name will "interrupt" the function (i.e., stop it from running). If it already ran and completed, your interrupt request will be ignored. If the function has not run yet, the interrupt will be queued until it does run.

By default, allowSignals will accept any signal as valid; if you define allowSignals as an empty string (""), it defines the function as "uninterruptible". You can also use an array - the function will stop if it receives an interrupt signal matching any of the names in the array.

attempts

Integer
Default: 
1

This defines the total amount of times the user will hear the prompt before the ask ends in either a nomatch or noinput.

bargein

Boolean
Default: 
true

The bargein attribute specifies whether or not the caller will be able to interrupt the TTS/audio output with a touch tone phone keypress or voice utterance. A value of 'true' indicates that the user is allowed to interrupt, while a value of 'false' forces the caller to listen to the entire prompt before being allowed to give input to the application. If using Python, make sure to use True and False instead of true and false.

choices

String
(Required)

The choices field typically defines a simple grammar that will be active for the prompting of the user for input. For more information, review the Asking a Question and Working with Simple Grammar Quickstarts.

It can also be used to point to a URL of an Advanced Grammar, such as GRXML. Review the Advanced Grammars documentation page for more information.

interdigitTimeout

Float
Default: 
5

With ask, interdigitTimeout defines how long to wait - in seconds - between key presses to determine the user has stopped entering input. This is useful to allow to help users restart the process if they mistyped, or to slim down the wait time experienced by the user if you need to get a variable amount of digits (enter you 4 or 5 digit pin code, for example).

If the interdigitTimeout is hit, it will trigger the onBadChoice event.

minConfidence

Float
Default: 
0.3

This is the minimum amount of confidence that the "recognizer" must have before matching a response to a choice. As an example, if your grammar defines the choices as red, blue and green, and someone says "rud", a particular confidence will be set identifying how likely "rud" was meant to be "red". This is expressed in a Float as a rate between 0 and 1.

mode

String
Default: 
any

The type of caller input allowed for voice calls. This can be 'dtmf' (touch-tone input), 'speech' or 'any'. Using any is a convenience function and works only if using US English as your recognizer.

onBadChoice

Function

This registers an event handler that fires when the number of attempts have been exhausted without a valid response from the user.

onChoice

Function

This registers an event handler that fires when a valid response is provided by a user.

onError

Function

This registers an event handler that fires when a system error (a non-user error) occurs during input. See onBadChoice and onTimeout for information on how to handle user errors.

onEvent

Function

This registers an event handler that fires as a catch all for all events. This essentially means onEvent is executed after any other event handler, so if (for example) a timeout occurs, onTimeout is executed, then onEvent is executed and then the verb returns. If no other event handler is defined, onEvent will still fire.

onHangup

Function

This registers an event handler that fires when the user disconnects or hangs up.

onSignal

Function

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

onTimeout

Function

This event fires when the user doesn't respond to the prompt within a specified period of time.

recognizer

String
Default: 
en-us

Recognizer tells Tropo what language to listen for; the available options can be found here (there's quite a few).

sensitivity

Integer
Default: 
50

This setting defines how loud or soft audio needs to be before detecting as an attempt to answer the question. This is expressed as a percentage value from 1 to 100; higher the value, the more sensitive the application will be to audio (meaning 100 will detect pretty much any sound as an attempt to answer the question - try not to breathe while answering!)

speechCompleteTimeout

Float
Default: 
1.0

This field defines how long the application should wait - in seconds - after input before determining a match. This is most useful for options with variable input - for example, if you ask a caller for their 4 OR 5 digit pin number and use the [4-5 DIGITS] grammar, the user might reply with 4 digits and then stop, even if you define a terminator. This field allows you to define how long you want the app to wait before the application decided the caller is finished responding and has no further input.

speechIncompleteTimeout

Float
Default: 
1.0

This field defines how long the application should wait - in seconds - after partial input before determining a "no match". For example, if you prompt the caller to select three choices from a list of options, and the caller responds with only one then stops talking, this defines how long the app will wait before considering the caller finished and returning a no match.

terminator

String
Default: 
#

This is the touch-tone key (also known as "DTMF digit") that indicates the end of input. A common use of the terminator is the # key, e.g.: "Please enter your five digit zip code, then press the pound key."

timeout

Float
Default: 
30.0

The amount of time Tropo will wait--in seconds and after sending or playing the prompt--for the user to begin a response. The maximum value for this parameter is four hours.

voice

String
Default: 
allison

Specifies the voice to be used when speaking text back to a user.

A full list of possible voices can be found here (there's many, many options).

promptLogSecurity

String
Default: 
none

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. See Log Suppression for complete details and examples.

asrLogSecurity

String
Default: 
none

Control whether Tropo should log the input from the user in response to the ask method. Possible values are "none" (the default), "suppress" (which prevents logging entirely), or "mask" (which replaces selected characters with a *. If set to "mask", then you also must set the maskTemplate parameter to a valid masking pattern. See Log Suppression for complete details.

maskTemplate

String

When asrLogSecurity is set to "mask", this parameter defines the pattern that should be masked. Only digit input can be masked, for any other input Tropo will ignore the maskTemplate and suppress the input logging entirely.

The mask template is a masking pattern constructed of three characters. "D" in any postion indicates that Tropo should log the digit that appears at that position. "X" in a position tells Tropo to suppress the digit appearing at that position, and Tropo will replace it with a "*". A hyphen or dash "-" tells Tropo to replace one or more digits with a star. For example, with a maskTemplate of XXDD- the string 123456789 becomes "**34*****".

See Log Suppression for complete details, several maskTemplate examples, and code samples for the log suppression and masking.

Examples

  ask("What's your four or five digit pin? Press pound when finished", {
    choices:"[4-5 DIGITS]",
    terminator:"#",
    timeout:15.0,
    mode:"dtmf",
    interdigitTimeout: 5,
    onChoice: function(event) {
        say("Choice is " + event.value);
    },
    onBadChoice: function(event) {
        say("On Bad Choice!");
    }
});  
ask "What's your four or five digit pin?  Press pound when finished", {
    :choices => "[4-5 DIGITS]",
    :terminator => '#',
    :timeout => 15.0,
    :mode => "dtmf",
    :interdigitTimeout => 5 ,
    :onChoice => lambda { |event|
        say "Choice: " + event.value
    },
    :onBadChoice => lambda { |event|
        say "On Bad Choice"
    }
}
<?php
    ask("What's your four or five digit pin? Press pound when finished", array(
        "choices"=>"[4-5 DIGITS]",
        "terminator" => "#",
        "timeout" => 15.0,
        "mode" => "dtmf",
        "interdigitTimeout" => 5,
        "onChoice" => "choiceFCN",  
        "onBadChoice" => "badChoiceFCN"
        )
    );
    function choiceFCN($event) {
        say("Choice is " . $event->value);
    }
    function badChoiceFCN($event) {
        say("On Bad Choice");
    }
?>
ask("What's your four or five digit pin? Press pound when finished.", {
    "choices":"[4-5 DIGITS]",
    "terminator":"#",
    "timeout":15.0,
    "mode":"dtmf",
    "interdigitTimeout":5,
    "onChoice": lambda event : say("Choice is " + event.value),
    "onBadChoice": lambda event : say("On Bad Choice!")
})
ask("What's your four or five digit pin?  Press pound when finished.", [
    choices: "[4-5 DIGITS]",
    terminator: '#',
    timeout: 15.0,
    mode: "dtmf",
    interdigitTimeout: 5,
    onBadChoice: { event->
        say("On Bad Choice!")
    },
    onChoice: { event->
        say("Choice is " + event.value)
    }
])