TwiML™ Voice: <Record>

The <Record> verb supports the following attributes that modify its behavior:

Use one or more of these attributes in a <Record> verb like so:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.record({
6
    timeout: 10,
7
    transcribe: true
8
});
9

10
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Record timeout="10" transcribe="true" />
4
</Response>

The action attribute takes a relative or absolute URL as a value. When recording is finished, Twilio will make a GET or POST request to this URL including the parameters below. If no action is provided, <Record> will request the current document's URL.

After making this request, Twilio will continue the current call using the TwiML received in your response. Keep in mind that by default Twilio will re-request the current document's URL. This can lead to unwanted looping behavior if you're not careful. Any TwiML verbs occurring after a <Record> are unreachable.

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the action URL:

A request to the RecordingUrl will return a recording in binary WAV audio format by default. To request the recording in MP3 format, append ".mp3" to the RecordingUrl value.

The method attribute takes the value GET or POST. This tells Twilio whether to request the action URL via HTTP GET or POST. This attribute is modeled after the HTML form method attribute. POST is the default value.

The timeout attribute tells Twilio to end the recording after a number of seconds of silence has passed. To disable this feature, set timeout to 0. The default is 5 seconds.

The finishOnKey attribute lets you choose a set of digits that, when entered, end the recording. For example, if you set finishOnKey to # and the caller presses the # key, Twilio will immediately stop recording and submit RecordingUrl, RecordingDuration, and # as parameters in a request to the action URL. The allowed values are the digits 0-9, # and *. The default is 1234567890*# — ie. any key will end the recording. Unlike <Gather>, you may specify more than one character as a finishOnKey value.

The maxLength attribute lets you set the maximum length for the recording in seconds. If you set maxLength to 30, the recording will automatically end after 30 seconds of recorded time has elapsed. The defaults are 3600 seconds (one hour) for a normal recording, and 120 seconds (two minutes) for a transcribed recording. Twilio Voice SDK calls using <Record> are limited to 600 seconds (ten minutes).

The maximum value of the maxLength attribute is limited by the maximum length set for your Voice Calls. The default maximum Call length is 4 hours (14400 seconds), and the maximum possible length is 24 hours (86400 seconds). You can update the maximum Call length to 24 hours in the Twilio Console in the Voice Settings page under "24-Hour Maximum Call Duration".

The playBeep attribute allows you to toggle between playing a sound before the start of a recording. If you set the value to false, no beep sound will be played.

The trim attribute lets you specify whether to trim leading and trailing silence from your audio files. The default is trim-silence, which removes any silence at the beginning and end of your recording. This may cause the duration of the recording to be slightly less than the duration of the call.

The recordingStatusCallback attribute takes a relative or absolute URL as an argument. If a recordingStatusCallback URL is given, Twilio will make a GET or POST request to the specified URL when the recording is available to access.

Twilio will pass the following parameters with its request to the recordingStatusCallback URL:

This attribute indicates which HTTP method to use when requesting recordingStatusCallback. It defaults to POST.

The recordingStatusCallbackEvent allows you to specify which recording status changes should generate a webhook to the URL specified in the recordingStatusCallback attribute. The available values are:

• in-progress: the recording has started.
• completed: the recording is complete and available.
• absent: the recording is absent and inaccessible.

To specify more than one value, separate each with a space. The default value is completed.

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 not enabled by default. If you do not wish to perform transcription, do not include the transcribe attribute.

The transcribeCallback attribute is used in conjunction with the transcribe attribute. It allows you to specify a URL to which Twilio will make an asynchronous POST request when the transcription is complete. This is not a request for TwiML and the response will not change call flow, but the request will contain the standard TwiML request parameters as well as transcription specific ones.

If transcribeCallback is specified, then you will also need to specify transcribe=true; it is no longer implicit. If you specify transcribe=true without a transcribeCallback, the completed transcription will be stored for you to retrieve later (see the REST API Transcriptions section), but Twilio will not asynchronously notify your application.

Twilio will not make a request to the provided transcribeCallback URL if the voice recording is missing or absent.

Twilio will pass the following parameters with its request to the transcribeCallback URL:

You can't nest any verbs within <Record> and you can't nest <Record> within any other verbs.

• Twilio REST API Recording resource
• Twilio REST API Transcription resource

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 five seconds, hits the # key, or the recording maxlength time is hit, Twilio will make an HTTP POST request to the default action URL (ie. the current document URL) with the parameters RecordingUrl and RecordingDuration.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.record();
6

7
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/simple_record.xml -->
3
<Response>  
4
    <Record/>  
5
</Response>

This example shows a 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.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.say('Please leave a message at the beep.\nPress the star key when finished.');
6
response.record({
7
    action: 'http://foo.edu/handleRecording.php',
8
    method: 'GET',
9
    maxLength: 20,
10
    finishOnKey: '*'
11
});
12
response.say('I did not receive a recording');
13

14
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/voicemail_record.xml -->
3
<Response>
4
    <Say>
5
        Please leave a message at the beep. 
6
        Press the star key when finished. 
7
    </Say>
8
    <Record 
9
        action="http://foo.edu/handleRecording.php"
10
        method="GET" 
11
        maxLength="20"
12
        finishOnKey="*"
13
        />
14
    <Say>I did not receive a recording</Say>
15
</Response>

• If the caller speaks for less than 20 seconds and is then silent for five 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.

Twilio will record the caller. When the recording is complete, Twilio will transcribe the recording and make an HTTP POST request to the transcribeCallback URL with a parameter containing a transcription of the recording.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.record({
6
    transcribe: true,
7
    transcribeCallback: '/handle_transcribe.php'
8
});
9

10
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!-- page located at http://example.com/record_and_transcribe.xml -->
3
<Response>
4
    <Record transcribe="true" transcribeCallback="/handle_transcribe.php"/>
5
</Response>

The recording duration may be shorter than the time a caller spends recording. The duration difference can be due to:

• Twilio trimming leading and trailing silence from your audio files
• No RTP (Real-time Transport Protocol) audio data being received during recording