{"record":} object

Plays a prompt (audio file or text to speech) then optionally waits for a response from the caller and records it. If collected, responses may be in the form of DTMF or speech recognition using a simple grammar format defined below. The record function 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 can also be transcribed by a predefined transcription service and the text returned to you via an email address or HTTP POST/Multipart Form.

Although the record function will allow extremely long recordings, transcription is limited to three hours. If you attempt to transcribe something longer than that, you will not receive a transcription.

Fields

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

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.

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.

beep
Data Type: 
Boolean
Default: 
true
Optional

When set to true, callers will hear a tone indicating the recording has begun.

choices
Data Type: 
Object
Default: (none) Optional

When used with record, choices allows you to define a terminator. The terminator is the touch-tone key (also known as "DTMF digit") that will allow the caller to indicate their recording is complete. A common terminator would be the pound key (#).

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 a record action, it can also take an event key. This determines if the prompt will be played based on a particular event; for record, the only possible event is 'timeout'.

format
Data Type: 
String
Default: 
audio/wav
Optional

This specifies the format for the audio recording; it can be 'audio/wav', 'audio/mp3' or 'audio/au'.

maxSilence
Data Type: 
Float
Default: 
5.0
Optional

The maximum amount of time, in seconds, to wait for silence after a user stops speaking, to ensure they are not just pausing as they speak.

maxTime
Data Type: 
Float
Default: 
30.0
Optional

The maximum amount of time, in seconds, the user is allotted for input.

method
Data Type: 
String
Default: 
POST
Optional

When submitting recordings via HTTP, this parameter determines the method used. This can be 'POST' (which is the default) or 'PUT' . When sending via POST, the name of the form field is "filename".

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.

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.

transcription
Data Type: 
Array or Object
Default: (none) Optional

This allows you to submit a recording to be transcribed and specifies where to send the transcription. This field is a hash containing other fields.

  • id - the value that's included with your transcription when it's sent to your URL. This allows you to keep track of transcriptions; accepts a string.
  • url - The address this transcription will be POSTed to; use a mailto: url to have the transcription emailed.
  • emailFormat - the format of the email. Setting it as "encoded" will include a chunk of JSON in the email body or you can set it as "omit" to send as a human-readable message. It defaults to "omit", so unless you want JSON, this can be left out.

Note that the transcription arrives as the content of the HTTP POST, as opposed to a header, named field or variable.

url
Data Type: 
String
Default: (none) Required

This is the destination URL to send the recording. This can be an FTP destination, like so:

ftp://ftp.myServer.com/files/myRecording.wav

You can build your username and password directly inline with the URL, or you can define them with the individual "username" and "password" fields.

Please note this needs to be a fully realized URL, i.e. "http://website.com/folder/subfolder" vs "/folder/subfolder". If you don't have a complete URL, the file won't send at all or at the very least won't send correctly (0 byte file and similar unusable content).

password
Data Type: 
String
Default: (none) Optional

Defines the password for either HTTP Basic Auth or an FTP login.

Note: If the user and password field in the URL contains one of these characters : or @ or /, the character must be encoded.

username
Data Type: 
String
Default: (none) Optional

Defines the username for either HTTP Basic Auth or an FTP login.

Note: If the user and password field in the URL contains one of these characters : or @ or /, the character must be encoded.

timeout
Data Type: 
Float
Default: 
10.0
Optional

The amount of time Tropo will wait--in seconds and after sending or playing the prompt--for the user to begin a response. If the timeout is reached and the call has not been answered, the URL specified in your incomplete event handler will be called.

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.

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 with timeout

{
   "tropo":[
      {
         "record":{
            "say":[
               {
                  "value":"Please leave a message"
               },
               {
                  "value":"Sorry, I did not hear anything. Please call back.",
                  "event":"timeout"
               }
            ],
            "name":"foo",
            "url":"http://sendme.com/tropo",
            "choices":{
               "terminator":"#"
            }
         }
      }
   ]
}

Example with transcription

{
   "tropo":[
      {
         "record":{
            "say":[
               {
                  "value":"Please leave a message"
               },
               {
                  "value":"Sorry, I did not hear anything. Please call back.",
                  "event":"timeout"
               }
            ],
            "name":"foo",
            "url":"http://example.com/tropo.php",
            "transcription": {
               "id":"1234",
               "url":"mailto:you@yourmail.com"},
            "choices":{
               "terminator":"#"
            }
         }
      }
   ]
}