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.