Voice

Record

View as Markdown

The <Record> verb creates an audio file with the caller’s voice and returns the URL to you. Text transcriptions of these recorded calls can also be produced.

Recordings remain stored indefinitely. To delete a recording, use the appropriate API call from the Compatibility API.

Any instructions placed after the <Record> verb will not be executed. To ensure additional instructions are processed, use the action attribute to specify a URL that SignalWire will request once the recording is complete.

Verb attributes

action
string

The action attribute takes in an absolute or relative URL. SignalWire will make a GET or POST request to this URL when recording is completed. The current document’s URL will be requested if no action is provided which can lead to unwanted looping behavior if you’re not careful. See below for specified request parameters.

finishOnKey
string

The set of digits, (0-9, *, #), that can end a recording.

maxLength
integer

The maximum length, in seconds, of the recording. A value of zero means 3600 seconds.

method
stringDefaults to POST

The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST.

playBeep
booleanDefaults to true

Whether or not a sound is played before the start of a recording.

recordingStatusCallback
string

The recordingStatusCallback attribute takes in an absolute or relative URL. SignalWire will make a GET or POST request to this URL when recording is accessible. See below for specified request parameters.

recordingStatusCallbackEvent
stringDefaults to completed

The different recording statuses. Possible values are completed, in-progress, and absent. To specify multiple events, separate with a space.

recordingStatusCallbackMethod
stringDefaults to POST

The type of HTTP request to use when requesting a recordingStatusCallback.

storageUrl
string

The storageUrl attribute accepts an absolute URL as the destination to send a recording to, if you prefer to host your own recordings and bypass SignalWire storage.

storageUrlMethod
stringDefaults to POST

Specifies which HTTP verb to use when sending the recording to the storageUrl. Available values are: POST and PUT.

timeout
integer

The timeout attribute specifies the number of seconds of silence that ends a recording.

transcribe
booleanDefaults to false

The transcribe attribute identifies whether to produce a text transcription of the recording. There is an additional charge for this service, so is turned off by default.

transcribeCallback
string

The ability to define a URL to which SignalWire will make a POST request to once the transcription is complete. See below for specified request parameters.

trim
stringDefaults to trim-silence

Whether or not silence in the beginning and end of recordings are removed. Allowed values are trim-silence and do-not-trim.

the sound of silence

If no audio data is received, including when a caller is silent and trim-silence is enabled, SignalWire will not save a recording. If you wish to save silence, be sure to set trim="do-not-trim".

Note also that SignalWire will trim leading and trailing silence from your audio files, causing the duration of calls to be less than the time spent recording.

avoid looping

When recording finishes, including when no audio data is received, <Record> will always request its action URL and process the cXML instructions that are returned. If no action URL is set, SignalWire will re-request the current cXML document’s URL by default. This can lead to unwanted looping behavior, so make sure to end the call using action as seen in the Recording a Voicemail example.

Request parameters for action URL

The action request contains the Standard Request Parameters as well as:

Digits
string

The buttons pressed to end a recording.

RecordingDuration
integer

The duration, in seconds, of the audio recording.

RecordingUrl
string

The URL of the recorded audio file.

Request parameters for recordingStatusCallback

Payload
1{
2  "AccountSid": "b3877c40-da60-4998-90ad-b792e98472af",
3  "CallSid": "b3877c40-da60-4998-90ad-b792e98472ca",
4  "RecordingSid": "b3877c40-da60-4998-90ad-b792e984re01",
5  "RecordingUrl": "https://example.signalwire.com/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Recordings/b3877c40-da60-4998-90ad-b792e984re01",
6  "RecordingStatus": "completed",
7  "RecordingDuration": 94,
8  "RecordingChannels": 1,
9  "RecordingSource": "RecordVerb"
10}

Request parameters for transcribeCallback

Payload
1{
2  "TranscriptionSid": "b3877c40-da60-4998-90ad-b792e984tr01",
3  "TranscriptionText": "Hello, I'd like to schedule an appointment for next Tuesday.",
4  "TranscriptionStatus": "completed",
5  "TranscriptionUrl": "https://example.signalwire.com/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Transcriptions/b3877c40-da60-4998-90ad-b792e984tr01",
6  "RecordingSid": "b3877c40-da60-4998-90ad-b792e984re01",
7  "RecordingUrl": "https://example.signalwire.com/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Recordings/b3877c40-da60-4998-90ad-b792e984re01"
8}

Nesting

No other verbs can be nested within <Record> and you cannot nest <Record> within any other verbs.

Examples

Recording a voicemail

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>
4        Please leave a message at the beep.
5        Press the pound key when finished.
6    </Say>
7    <Record
8        action="http://your-application.com/handleRecording.php"
9        method="GET"
10        maxLength="15"
11        finishOnKey="#"
12        />
13</Response>

This prompt will play before the ‘beep’, asking the caller to leave a message. The caller can only leave a message that is 15s long.

Transcribing a recording

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Record
4        transcribe="true"
5        transcribeCallback="http://your-application.com/handle_transcribe.php" />
6</Response>

SignalWire will record the caller and transcribe the recording once it is complete. Then, SignalWire will make a POST request to the transcribeCallback URL with the transcription as a parameter.