Twilio

Record Verb

The <Record> verb records the caller's voice and returns a URL that links to a file containing the audio recording.

Nouns

The <Record> verb has no "noun". It does not accept any nested input.

Form Parameters

When the <Record> verb finishes recording audio from a caller, it submits the following parameter to the action URL.

See Also

Twilio REST Recording object

Verb Attributes

action

The action attribute takes an absolute or relative URL as an argument. When a caller completes entering data, Twilio will make a GET or POST request to this URL with the form parameters "RecordingUrl" and "Duration". RecordingUrl contains URL that links to the audio recording. The "Duration" parameter indicates the time duration of the recorded audio. If no action is provided, Record will submit back to the same URL.

method

The method attribute takes the value GET or POST. This tells Twilio whether to submit the action URL as a GET or POST method. This attribute is modeled after the HTML form method attribute. POST is the default value.

timeout

The timeout attribute tells Twilio to end the recording after this many seconds of silence have passed. The default is 5 seconds.

finishOnKey

The finishOnKey attribute lets you choose a set of digits that end the recording. For example, if you set finishOnKey="#", and the user presses #, Twilio will immediately stop recording and submit the RecordingUrl, Duration, and the '#' to the action URL. The allowed values are the numbers 0-9, # and *. The default is '1234567890*#' (any key will end the recording). Unlike <Gather>, you may specify more than one character as a finishOnKey value.

maxLength

The maxLength attribute lets you set the maximum length of the recording in seconds. If you set maxLength="30", the recording will automatically end and submit after 30 seconds of recording. Defaults to 3600 seconds (1 hour) for a normal recording and 120 seconds (2 minutes) for a transcribed recording.

transcribe

The transcribe attribute tells Twilio that you would like a text representation of the audio of the recording. Twilio will pass this recording to our speech-to-text engine and attempt to convert the audio to human readable text. The transcribe option is off by default. If you do not wish to perform transcription, do not include the transcribe attribute.

transcribeCallback

The transcribeCallback attribute is used alongside the "transcribe" attribute. It allows you to specify a URL you wish Twilio to make a POST request to, when a transcription is complete and is available. The callback will contain the standard Twilio parameters (AccountSid, CallSid, Caller,etc) as well as "TranscriptionStatus", "TranscriptionText", "TranscriptionUrl" and "RecordingUrl". If transcribeCallback is not specified, the completed transcription will be written to a transcription record associated with your account but no notification will be sent to your application.

Nesting Rules

The Record verb can be nested in the following elements

• <Response>

The following verbs can be nested within Record

• none

Examples

Example 1: default behaviour

<?xml version="1.0" encoding="UTF-8"?>  
<Response>  
    <Record/>  
</Response>     

Twilio will execute the <Record> verb causing the caller to hear a beep and the recording to start. If the caller is silent for more than 5 seconds, hits the # key, or the recording maxlength time is hit, Twilio will make an HTTP POST request to the default action (the current document URL) with the parameters RecordingUrl and Duration.

Example 2: simple recording prompt

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>
        Please leave a message at the beep. 
        Press the star key when finished. 
    </Say>
    <Record 
        action="http://foo.edu/handleRecording.php"
        method="GET" 
        maxLength="20"
        finishOnKey="*"
        />
    <Say>I did not receive a recording</Say>
</Response>

This is example shows a simple voicemail prompt. The caller is asked to leave a message at the beep. The <Record> verb beeps and begins recording up to 20 seconds of audio.

• If the caller does not speak at all, the Record verb exits after 5 seconds of silence, falling through to the next verb in the document. In this case, it would fall through to the <Say> verb.
• If the caller speaks for less that 20 seconds and is then silent for 5 seconds, Twilio makes a GET request to the action URL. The Say verb is never reached.
• If the caller speaks for the full 20 seconds, Twilio makes a GET request to the action URL. The Say verb is never reached.

Example 3: transcription

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Record transcribe="true" transcribeCallback="/handle_transcribe.php"/>
</Response> 

Twilio will record the caller. When the recording is complete, twilio will process the recording, and make an HTTP POST, containing a transcription of what the caller said, to /handle_transcribe.php

Hints and Advanced Uses

• Twilio will trim leading and trailing silence from your audio files. This may cause the duration of the files to be slightly smaller than the time a caller spends recording them.
• If Twilio receives an empty recording, it will not submit, but will instead fall through to the next verb in the document. If there are no more verbs, the call ends.