Tropo is part of CiscoLearn More

record

Used to request input from the caller and records any audible response. At the conclusion of the recording, the audio file can be automatically sent to an external server via FTP, an HTTP POST/Multipart Form or upload to an Amazon S3 bucket.

The audio file can also be transcribed and the text returned to you via an email address or HTTP POST/Multipart Form - currently, transcription only supports US English.

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.

Since Tropo is synchronous, record is a blocking method. This means no other method can run until record is complete. If your recording is long, set the asyncUpload parameter to true and Tropo will upload the file in the background. See the asyncUpload parameter details below for how this works.

Record only applies to voice calls.

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.

Parameters

text

String

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.

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.

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.

If this is set to false (the default behavior), Tropo will wait until the file is uploaded before returning or running the onRecord callback.

attempts

Integer
Default: 
1

This defines the total amount of times the user will hear the prompt before the record 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.

beep

Boolean
Default: 
true

When set to true, callers will hear a tone indicating the recording has begun. If using Python, make sure to use True and False instead of true and false as Boolean values are case sensitive in Python.

interdigitTimeout

Integer

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.

maxTime

Integer
Default: 
30

The maximum amount of time (in seconds) allowed for a recording. Defaults to 30 seconds, but can be set up to four hours, at which point the maximum session time would kick in and disconnect the call.

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.

onRecord

Function

This registers an event handler that fires when a recording of the input is complete.

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 begin speaking within a specific period of time, once the record prompt and/or beep is played.

recordURL

Array

Accepts an array with the following keys:

  • 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 up to three URLs to upload to, and Tropo will attempt them in order until uploading succeeds to one of them. 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 succeeeding. If your application needs to play back the audio immediately after recording is completed, the object returned by the record method has a "value" property that contains a url of a temporary local copy of the file. This temporary copy will be deleted as soon as the call ends.

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, or if you want to record audio for playback in the same application without needing to store a copy of it.

recordFormat

String
Default: 
audio/wav

The audio format used for the recording; values can be 'audio/wav', 'audio/mp3' or 'audio/au'. The default is 'audio/wav', but if the recordURI parameter includes a file extension, Tropo will set the appropriate audio type.

silenceTimeout

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

terminator

Strong

This is the touch-tone key (also known as "DTMF digit") that stops the recording.

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.

transcriptionOutURI

String

Setting this to anything enables transcription on this recording. The e-mail address or HTTP URL to send the transcription results to; the transcription arrives as the content of the HTTP POST, as opposed to a header, named field or variable.

Email addresses must be prefaced with mailto: if used (mailto:you@example.com)

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.

transcriptionID

String

User definable ID that can be included when the transcription is posted to transcriptionOutURI.

transcriptionOutFormat

String
Default: 
json

The formatting for the transcription that will be sent to your transcription URI - either 'xml' or 'json'.

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.

Examples

  var callerID = currentCall.callerID;
 
say("Welcome to speed therapy!");
record("Tell us how you feel in fifteen minutes or less!", {
    beep:true,
    maxTime:900,
    recordURL: {url: "http://example.com/recording.js"},
    recordFormat: "audio/mp3",    
    transcriptionOutURI: "mailto:you@example.com",
    transcriptionID:callerID
    }
);  
callerID = $currentCall.callerID
 
say "Welcome to speed therapy!"
record "Tell us how you feel in fifteen minutes or less!", {
    :beep => true,
    :maxTime => 900,
    :recordURL => {:url => "http://example.com/recording"},
    :recordFormat => "audio/mp3",
    :transcriptionOutURI => "mailto:you@example.com",
    :transcriptionID => callerID
    }
<?php
$callerID = $currentCall->callerID;
 
say("Welcome to speed therapy!");
record("Tell us how you feel in fifteen minutes or less!", array (
    "beep" => true,
    "maxTime" => 900,
    "recordURL"=> array("url"=>"http://example.com/recording.php"),
    "recordFormat"=>"audio/mp3",
    "transcriptionOutURI" => "mailto:you@example.com",
    "transcriptionID" => $callerID
    )
);
?>
callerID = currentCall.callerID
 
say("Welcome to speed therapy!")
record("Tell us how you feel in fifteen minutes or less!", {
    "beep":True,
    "maxTime":900,
     "recordURL": {"url": "http://example.com/recording.py"},
     "recordFormat": "audio/mp3",
    "transcriptionOutURI": "mailto:you@example.com",
    "transcriptionID": callerID
    }
)
callerID = currentCall.callerID
 
say("Welcome to speed therapy!")
record("Tell us how you feel in fifteen minutes or less!", [
    beep:true,
    maxTime:900,
    recordURL: [url: "http://example.com/recording"],
    recordFormat: "audio/mp3",
    transcriptionOutURI: "mailto:you@example.com",
    transcriptionID: callerID
    ]
)