Tropo Scripting Development Guide

record() method

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 or an HTTP POST/Multipart Form. If specified, the audio file can also be transcribed by a pre-defined transcription service and the text returned to you via an email address or HTTP POST/Multipart Form - currently, transcription only support English. Record only applies to voice calls.

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.

Check out any of these examples for more information: Record Audio, Recording Caller Input, Transcribing Caller Input

usage

record( text: String, {
    allowSignals: String or Array,
    attempts: Integer,
    bargein: Boolean,
    beep: Boolean,
    interdigitTimeout: Integer,
    maxTime: Integer,
    onError: Function,
    onEvent: Function,
    onHangup: Function,
    onRecord: Function,
    onSignal: Function,
    onTimeout: Function,
    recordFormat: String,
    recordMethod: String,
    recordPassword: String,
    recordURI: String,
    recordUser: String,
    silenceTimeout: Float,
    terminator: String,
    timeout: Float,
    transcriptionID: String,
    transcriptionOutFormat: String,
    transcriptionOutURI: String,
    voice: String } )

parameters

text	Data Type: String	Default: "" (undefined)	Required
	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	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 record ends in either a nomatch or noinput.
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. If using Python, make sure to use True and False instead of true and false.
beep	Data Type: Boolean	Default: false	Optional
	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.
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.
maxTime	Data Type: Integer	Default: 30	Optional
	The maximum amount of time (in seconds) allowed for a recording. Defaults to 30 seconds, but may be set much higher. How high? 68 years. Seriously. 2,147,483,647 seconds, to be precise. So if you want to record your entire life, you'd better plan on dying a little early.
onError	Data Type: Function	Default: "" (undefined)	Optional
	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	Data Type: Function	Default: "" (undefined)	Optional
	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	Data Type: Function	Default: "" (undefined)	Optional
	This registers an event handler that fires when the user disconnects or hangs up.
onRecord	Data Type: Function	Default: "" (undefined)	Optional
	This registers an event handler that fires when a recording of the input is complete.
onSignal	Data Type: Function	Default: (none)	Optional
	This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.
onTimeout	Data Type: Function	Default: "" (undefined)	Optional
	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.
recordFormat	Data Type: String	Default: audio/wav	Optional
	The audio format used for the recording; values can be 'audio/wav', 'audio/mp3' or 'audio/au'.
recordMethod	Data Type: String	Default: POST	Optional
	When submitting recordings via HTTP, this parameter determines the method used. This can currently only be 'POST', which is the default; 'PUT' will be available in a future release. When sending via POST, the name of the form field is "filename".
recordPassword	Data Type: String	Default: (none)	Optional
	When using FTP, this indicates the FTP password.
recordURI	Data Type: String	Default: (none)	Optional
	The FTP or HTTP URL to send the recorded audio file. When sending via POST, the name of the form field is "filename".
recordUser	Data Type: String	Default: (none)	Optional
	When using FTP, this is the FTP account username Note: If the user and password field in the URL contains one of these characters : or @ or /, the character must be encoded.
silenceTimeout	Data Type: Float	Default: 5.0	Optional
	The amount of time, after the caller is done speaking, before the user's response is considered done. Applies only to voice input.
terminator	Data Type: String	Default: (none)	Optional
	This is the touch-tone key (also known as "DTMF digit") that stops the recording.
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. The maximum value for this parameter is 2 hours.
transcriptionID	Data Type: String	Default: (none)	Optional
	User definable ID that can be included when the transcription is posted to transcriptionOutURI.
transcriptionOutFormat	Data Type: String	Default: json	Optional
	The formatting for the transcription that will be sent to your transcription URI - either 'xml' or 'json'.
transcriptionOutURI	Data Type: String	Default: "" (undefined)	Optional
	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. Note: Email addresses must be prefaced with mailto: if used (mailto:you@example.com)
voice	Data Type: String	Default: allison	Optional
	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).

events

error event hangup record timeout

return values

event

code samples

JavaScript example

var callerID = currentCall.callerID;

say("Welcome to speed therapy!");
record("Tell us how you feel in fifteen minutes or less!", {
    beep:true,
    maxTime:900,
    recordURI:"http://example.com/recording.js",
    transcriptionOutURI: "mailto:you@example.com",
    transcriptionID:callerID
    }
);

Ruby example

callerID = $currentCall.callerID

say "Welcome to speed therapy!"
record "Tell us how you feel in fifteen minutes or less!", {
    :beep => true,
    :maxTime => 900,
    :recordURI => "http://example.com/recording.rb",
    :transcriptionOutURI => "mailto:you@example.com",
    :transcriptionID => callerID
    }

PHP example

<?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,
    "recordURI"=>"http://example.com/recording.php",
    "transcriptionOutURI" => "mailto:you@example.com",
    "transcriptionID" => $callerID
    )
);
?>

Python example

callerID = currentCall.callerID

say("Welcome to speed therapy!")
record("Tell us how you feel in fifteen minutes or less!", {
    "beep":True,
    "maxTime":900,
    "recordURI":"http://example.com/recording.py",
    "transcriptionOutURI": "mailto:you@example.com",
    "transcriptionID": callerID
    }
)

Groovy example

callerID = currentCall.callerID

say("Welcome to speed therapy!")
record("Tell us how you feel in fifteen minutes or less!", [
    beep:true,
    maxTime:900,
    recordURI:"http://example.com/recording.groovy",
    transcriptionOutURI: "mailto:you@example.com",
    transcriptionID: callerID
    ]
)

additional links

none

ANNOTATIONS: EXISTING POSTS

billsimon

2/8/2011 5:30 PM (EST)

Choosing audio/mp3 as the recording format makes smaller files but if you are also using transcription, it adversely affects the transcription accuracy. I found that when I chose audio/wav format the transcription accuracy was far better. So if you need smaller files *and* transcription, choose the audio/wav format and then compress to mp3 at your own site.

VoxeoAndy

2/8/2011 8:51 PM (EST)

Hello:

Thank you kindly for the insight. I'm certain other developers will find it helpful. If you have any questions, please don't hesitate to let us know.

Best regards,
Andrew Hague
Voxeo Customer Support Engineer

Tropo News: [url=http://blog.tropo.com/]http://blog.tropo.com/[/url] | [url=http://twitter.com/Tropo]@Tropo[/url]
Change log: [url=http://changes.tropo.com/]http://changes.tropo.com/[/url] | [url=http://twitter.com/TropoChanges]@TropoChanges[/url]
Service status announcements: [url=http://status.tropo.com/]http://status.tropo.com/[/url]

-powered by [url=http://labs.voxeo.com]Voxeo Labs[/url]