Tropo WebAPI Development Guide

{"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.

usage

{ "record": {
    "attempts": Integer,
    "allowSignals": String or Array,
    "bargein": Boolean,
    "beep": Boolean,
    "choices": Object,
    "say": Object,
    "format": String,
    "maxSilence": Float,
    "maxTime": Float,
    "method": String,
    "minConfidence": Integer,
    "name": String,
    "required": Boolean,
    "transcription": Array or Object,
    "url": String,
    "password": String,
    "username": String,
    "timeout": Float,
    "interdigitTimeout": Integer,
    "voice": String } }

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: "" (undefined)	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: "" (undefined)	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) allowed for a recording. Defaults to 30 seconds, but may be set up to 2 hours in length (Tropo disconnects any session that exceeds 2 hours long, effectively reducing the recording to 2 hours as well).
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".
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: "" (undefined)	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: "" (undefined)	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.
password	Data Type: String	Default: "" (undefined)	Optional
	This identifies the FTP account password.
username	Data Type: String	Default: "" (undefined)	Optional
	This identifies the FTP account username.
timeout	Data Type: Float	Default: 30.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: "" (undefined)	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's many, many options).

code samples

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":"#"
            }
         }
      }
   ]
}

additional links

none

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page