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:

Attribute	Description
`actionUrl`	URL to which information on the completed recording is submitted.
`silenceTimeoutMs`	Interval of silence that should elapse before ending the recording.
`finishOnKey`	Key that triggers the end of the recording.
`maxLengthSec`	Maximum length for the command execution in seconds.
`playBeep`	Indicates whether to play a beep sound before the start of the recording.
`autoStart`	Indicates if recording should start automatically.
`privacyMode`	Indicates 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 Parameter	Description
`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 (up to 3600)
Default: 60 (seconds)

Maximum length for the command execution in seconds. This value can be no larger than 3600 seconds (1 hour).

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.