RecordUtterance

The RecordUtterance command records the caller's voice and returns the URL of a file containing the audio recording.

RecordUtterance is blocking and is a terminal command. As such, the actionUrl property is required, and control of the Call picks up using the PerCL returned in response to the actionUrl. Recording information is returned in the actionUrl request. If the reason this command ended was due to the call hanging up (see reason below), any PerCL returned will not execute.

Nesting Rules

No actions can be nested within RecordUtterance and RecordUtterance cannot be nested within any other actions.

Example

This example shows a simple voicemail setup where a caller can leave a message after the beep.

[
   {
      "Say" : {
         "text" : "Please leave a message after the beep."
      }
   },
   {
      "RecordUtterance" : {
         "actionUrl" : "http://foo.edu/handleRecording",
         "silenceTimeoutMs" : 2500,
         "maxLengthSec" : 60,
         "finishOnKey" : "#"
      }
   }
]

Command Attributes

RecordUtterance supports the following attributes that modify its behavior:

AttributeDescription
actionUrlURL to which information on the completed recording is submitted.
silenceTimeoutMsInterval of silence that should elapse before ending the recording.
finishOnKeyKey that triggers the end of the recording.
maxLengthSecMaximum length for the command execution in seconds.
playBeepIndicates whether to play a beep sound before the start of the recording.
autoStartIndicates if recording should start automatically.
privacyModeIndicates if privacyMode should apply to this recording and therefore only be available for download 2 minutes after the recording is completed.

actionUrl

REQUIRED

Type: absolute URL

URL to which information on the completed recording is submitted. The PerCL received in response is then used to continue with Call processing.

Additional Request Parameters

Request ParameterDescription
recordingId
ID of the recording.
recordingUrl
URL of the recorded audio file. This URL can be used as is in a Play command to play the recording (no authentication needed). It can also be used to download the recording file via the REST API.
recordingSize
Size of the recording in bytes.
recordingFormat
Media type of the recording.
recordingDurationSec
Duration of the recorded audio, rounded up to the nearest second (in seconds).
termReason
Reason for recording stop. Valid values are: finishKey, timeout, hangup, or maxLength. Note that for hangup, any returned PerCL will not be executed.

silenceTimeoutMs

OPTIONAL

Type: integer > 0
Default: 4000 (ms)

Interval of silence that should elapse before ending the recording.


finishOnKey

OPTIONAL

Type: string (any digit, #, *)
Default: #

Key that triggers the end of the recording. If any buffered key presses from before this command starts executing, the buffer will be flushed. This is analagous to the flushBuffer parameter from the GetDigits command.


maxLengthSec

OPTIONAL

Type: integer > 1
Default: 60 (seconds)

Maximum length for the command execution in seconds.


playBeep

OPTIONAL

Type: boolean
Default: true

Indicates whether to play a beep sound before the start of the recording. If set to false, no beep is played.


autoStart

OPTIONAL

Type: boolean
Default: false

If false, recording begins immediately after the RecordUtterance command is processed. If true, recording begins when audio is present and if audio begins before the maxLengthSec timeout. If no audio begins before maxLengthSec, no recording is generated.


privacyMode

OPTIONAL

Type: boolean
Default: false

Recordings made with privacyMode set to true will only be available for download for 2 minutes. This is to minimize risk of bad actors accessing the recording.

🚧

Recordings made with privacyMode set to true can't be used as a parameter for a Play command.