{"ask":} object

Ask is essentially a say that requires input; it requests information from the caller and waits for a response.

For voice calls:

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).

For SMS:

Prompts the user via text and the user can respond back by replying to the SMS message. This is NOT recommended - 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. 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.

Fields

choices
Data Type: 
Object
Default: (none) Required

The choices object tells Tropo how to handle user input. It indicates the structure of the expected data, if any, and the various acceptable modes of input - some applications require just keypad input (dtmf), others are speech driven and some can accept both.

These are the properties for the choices object:

  • value -- This is the grammar which determines the type of expected data. See the examples below for more detail.
  • mode -- Only applies to the voice channel and can be either 'speech', 'dtmf', or 'any'.
  • terminator -- 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, eg: "Please enter your five digit zip code, then press the pound key."

If you use a text channel, where voice recognition is not required, you can use the grammar [ANY] to return a successful match for any input. Using the [ANY] grammar on voice channels will fail, so don't do that.

Examples

Simple grammar that will return 'sales' or 'support' if recognized:

"choices": { "value": "sales, support" }

Simple grammar that will return 'sales' or 'support' if spoken or selected with keypad input:

"choices": { "value": "sales(1, sales), support(2, support)" }

Simple grammar for entering in digits only:

"choices": { "value": "[5 DIGITS]", "mode": "dtmf" }

This object also supports advanced grammars like GRXML and JSGF.

allowSignals
Data Type: 
String or Array
Default: 
* (any signal)
Optional

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 "", 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
Data Type: 
Integer
Default: 
1
Optional

This defines the total amount of times the user will hear the prompt before the ask ends in an "incomplete" event (i.e. the user provided incorrect input or no input at all).

bargein
Data Type: 
Boolean
Default: 
true
Optional

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.

interdigitTimeout
Data Type: 
Integer
Default: (none) Optional

For conference, record and transfer, interdigitTimeout defines how long the user needs to wait - in seconds - before Tropo will recognize another key press. Essentially, this means if a user presses the wrong key to terminate the session (say * instead of #), how long do you want Tropo to wait before letting them try again.

minConfidence
Data Type: 
Integer
Default: 
30
Optional

This is the minimum amount of confidence that the 'recognize' 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 as an Integer between 0-100.

name
Data Type: 
String
Default: (none) Required

This is the key used to identify the result of an operation, so you can differentiate between multiple results. As an example, if you asked the user for their favorite color, you could set the name value as 'color' while the returned value might be 'blue'. Not particularly useful if there's only one result returned, but if there are multiple results it helps to determine which result belonged to which operation.

recognizer
Data Type: 
String
Default: 
en-us
Optional

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

required
Data Type: 
Boolean
Default: 
true
Optional

This determines whether Tropo should move on to the next verb; if required is set to 'true', Tropo will only move on to the next verb if the current operation completely successfully.

say
Data Type: 
Object
Default: (none) Optional

This determines what is played or sent to the caller. This can be a single object or an array of objects. When say is a part of an ask, it takes an event key. This determines if the prompt will be played based on a particular event; the possible events are:

  • nomatch -- Returned if the user did not say or input a valid response.
  • timeout -- Returned if there was no user input in the allotted time.

Each of these event descriptors can also take an attempt value, based on the number of attempted input requests. For example, if you want to define a different say depending on the attempt, you would specify one say with the event 'nomatch:1' and a different say for the event 'nomatch:2'.

sensitivity
Data Type: 
Float
Default: 
0.5
Optional

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 decimal between 0.01 and 1; higher the value, the more sensitive the application will be to audio (meaning 1 will detect pretty much any sound as an attempt to answer the question - try not to cough!)

speechCompleteTimeout
Data Type: 
Float
Default: 
0.5
Optional

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
Data Type: 
Float
Default: 
0.5
Optional

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.

timeout
Data Type: 
Float
Default: 
10.0
Optional

The amount of time - in seconds - that Tropo will wait for input. If the timeout is reached and the caller has not begun input, the URL specified in the incomplete handler will be called. The maximum value for this parameter is 2 hours.

voice
Data Type: 
String
Default: 
allison
Optional

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

A full list of all voices can be found here (there are many, many options).

Examples

Example including defined voice

{
    "tropo": [
        {
            "ask": {
                "say": [
                    {
                        "value": "Please say your account number"
  
                    }
                ],
                "voice":"simon",
                "required": true,
                "bargein": true,
                "timeout": 30,
                "name": "foo",
                "choices": {
                    "value": "[5 DIGITS]"
                } 
            } 
        }
    ] 
}

Example showing inclusion of sensitivity

{
    "tropo": [
        {
            "on": {
                "event": "continue",
                "next": "continue.json",
                "say": [
                    {
                        "value": "Nice answer!",
                        "voice": "Victor"
                    }
                ]
            }
        },
        {
            "ask": {
                "say": [
                    {
                        "value":"Please say a digit"                        
                    }
                ],
                "voice":"Victor",
                "sensitivity": 80,
                "name": "foo",
                "choices": {
                    "value": "[1 DIGIT]"
                }
            }
        }
    ]
}

Example including events, multiple say values & interdigitTimeout

{
   "tropo":[
      {
         "ask":{
            "attempts":3,
            "say":[
               {
                  "value":"Sorry, I did not hear anything.",
                  "event":"timeout"
               },
               {
                  "value":"Don't think that was a year. ",
                  "event":"nomatch:1"
               },
               {
                  "value":"Nope, still not a year.",
                  "event":"nomatch:2"
               },
               {
                  "value":"What is your birth year?"
               }
            ],
            "choices":{
               "value":"[4 DIGITS]"
            },
            "bargein":true,
            "timeout":60,
            "interdigitTimeout": 1,
            "name":"year",
            "required":true
         }
      },
      {
         "on":{
            "next":"/your_age.json",
            "event":"continue"
         }
      },
      {
         "on":{
            "next":"/age_fail.json",
            "event":"incomplete"
         }
      }
   ]
}