Tropo is part of CiscoLearn More

record

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. It may also be sent to your Amazon S3 bucket.

If desired, the audio file can also be transcribed and the text returned to you via an email address or HTTP POST/Multipart Form.

Note
Transcription is not available in the tropo.eu environment. See API Differences for details.

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.

Tips and Tricks

  • Recording files are 16 bit, 8KHz files, regardless of the audio type
  • Transcription results will be better if you use WAV as your audio type. The higher-quality audio gives more for the transcription engine to work with.
  • After this action is called, the Result object sent to your server will contain an "uploadStatus" field, indicating if the upload succeeded or not.
  • Silence at the end of a recording will be trimmed before the recording is sent to you.

Fields

attempts

Integer
Default: 
1

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

asyncUpload

Boolean
Default: 
false

Setting to true will instruct Tropo to upload the recording file in the background as soon as the recording is completed. This will cause the on:continue event to run immediately at the end of processing the document, rather than waiting until uploading the recording is complete. Because the continue event fires before the recording has been uploaded, Tropo will not be able to report the uploadStatus in the result object that is sent to your continue URL.

If this is set to false (the default), Tropo will wait until the file is uploaded before running the on:continue event, and will be able to report errors through the uploadStatus field in the result object. The tradeoff is that no other Tropo operations run during upload, so if the recording file is very large or the receiving server is very slow, the caller will hear a large period of silence while the file uploads.

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.

bargein

Boolean
Default: 
true

Indicates whether or not the caller will be able to interrupt the TTS or 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 start recording.

beep

Boolean
Default: 
true

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

choices

Object

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

Object

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

String
Default: 
audio/wav

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

maxSilence

Float
Default: 
5.0

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.

sensitivity

Float
Default: 
0.5

Controls how sensitive Tropo's silence detection is, allowing an application to have more control over how a silence timeout is triggered. Higher values indicate Tropo should detect quieter noises as input, and lower values indicate Tropo should detect louder noises as silence. For example, in an app with this set to 1.0, the slightest background noise will keep the recording running.

Valid values range from 0.0 (hear nothing) to 1.0 (hear everything).

maxTime

Float
Default: 
30.0

The maximum amount of time, in seconds, the user is allotted for input. The maximum value for this is four hours (14400 seconds).

recordingURL

Array or Object

Accepts an object with the following keys, or an array of these objects:

  • url: The URL that Tropo should send the recording to. This should be a full HTTP or HTTPS URL. If your URL includes a file extension, and the recording format parameter is not set, the extension will be used to guess your desired format. Files ending in .wav will be recorded using the format 'audio/wav', .mp3 as 'audio/mp3', and .au as 'audio/au'.
  • username: The username that should be transmitted along with your request. For S3 uploads, this is your S3 Access Key ID.
  • password: The passwor that should be transmitted along with your request. For S3 uploads, this is your S3 Access Key Secret.
  • method: The HTTP Method (PUT or POST) that Tropo should send the file as. POST is the default. When sending via POST, the file is delivered as if you had an HTML form with an upload field named "filename". If the upload is an S3 upload, this is ignored.

Tropo will examine your URL to determine if it is an S3 bucket - there's no need to tell Tropo you're uploading to S3.

You can specify an array of objects and Tropo will attempt each one in order until uploading succeeds to one of them, with a maximum of three attempts. There is no retry mechanism; once Tropo fails to upload to one of your URLs, it will skip to the next one, and continue that until either the recording is uploaded or Tropo has tried all of the URLs you gave. If you give more than three URLs, Tropo will only try the first three.

The file will take a few moments to upload to your server. The exact amount of time depends on many factors, including the network connection of your server and how many of your failover URLs we need to attempt before succeeding.

This parameter is not required, but if you do not include it, Tropo will not send your recording anywhere. This can be useful if you wish to transcribe something, but don't need the audio file.

method

String
Default: 
POST

For HTTP recording upload, this parameter determines the method used. This can be 'POST' (which is the default) or 'PUT'. When sending via POST, the file is sent as if you uploaded in a web form with a form field name of "filename".

name

String
(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

Boolean
Default: 
true

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

Array or Object

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.

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

Transcription is a paid feature and is not included in the per-minute rate for phone calls. Transcription is billed for each minute of transcribed recording. See Tropo Pricing for current rates.

Note
Transcription is not available in the tropo.eu environment. See API Differences for details.

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. If the timeout is reached and the call has not been answered, the URL specified in your incomplete event handler will be called.

interdigitTimeout

Float
Default: 
5.0

How long does Tropo wait between key presses to determine the user is done with their input. This is useful to allow to help users restart the process if they mistyped.

voice

String
Default: 
allison

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

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.

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",
            "recordURL" : {"url":"http://example.com/recording"},
            "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",
            "recordURL" : {"url":"http://example.com/recording"},
            "transcription": {
               "id":"1234",
               "url":"mailto:you@yourmail.com"},
            "choices":{
               "terminator":"#"
            }
         }
      }
   ]
}