The TranscribeUtterance command transcribes the caller’s voice, returns transcription of the audio and, optionally, returns the recording of the audio transcribed.

TranscribeUtterance is a blocking and terminal command. As such, the actionUrl property is required in the command. Control of the Call picks up using the PerCL provided by the user in response to the result posted to the actionUrl. Recording and Transcription information is returned in the actionUrl post. If the reason this command ended was due to the call hanging up, any PerCL provided in response will not execute.

Nesting Rules

The following actions may be within the TranscribeUtterance command.

Say
Play
Pause

The commands are not directly nested but are contained in the prompts attribute as a list of commands. See example below. The nested commands (Say, Play, and Pause) will have Barge-In enabled.

The TranscribeUtterance command cannot be nested within any other command.

Note that nested commands do not inherit the value of privacyMode from the parent command's specified values for privacyForLogging or privacyForRecording. To use privacyMode in any nested command, it must be specified within that command's parameters.

Example

[
    {
        "TranscribeUtterance": {
            "actionUrl": "http://foo.com/handleTranscription",
            "record" : {
                "maxLengthSec" : 15,
                "saveRecording" : true,
                "rcrdTerminationSilenceTimeMs" : 2000
            },
            "playBeep": true,
            "prompts": [
                {
                    "Say": {
                        "text" : "Please leave a message after the beep."
                    }
                }
            ]
        }
    }
]

Command Attributes

TranscribeUtterance supports the following attributes that modify its behavior:

Attribute	Description
`actionUrl`	URL to which information about the completed recording (if record is true) and transcribed text is posted. The PerCL received in response from the user is then used to continue call processing.
`playBeep`	Indicates whether to play a beep sound before the start of the recording. If set to false, no beep is played
`record`	Encapsulates all of the configuration options for recording. Existence of this parameter will turn on recording for the captured audio. All parameters within this block are optional. An empty record object can be specified to turn on recording with defaults for all parameters below. The recording will end once any of the time/voice energy criteria are met (either termination silence time or max length). Any DTMF detected will also terminate recording.
`privacyForLogging`	When set to true, the contents of the transcription attribute will be replaced with the string "xxxxx" in the logs. It's important to note that privacyForLogging is set at the command level, meaning it will not be inherited for privacyMode by any nested commands.
`privacyForRecording`	Recordings made with privacyForRecording set to true will only be available for download for 2 minutes. Any full call recording will be squelched while recording is running.
`prompts`	The JSON array of `Say`, `Play`, and `Pause` PerCL commands to nest within the command. The nested actions are executed while FreeClimb is waiting for input from the caller. This allows for playing menu options to the caller and to prompt for the expected input. These commands stop executing when the caller begins to speak (i.e., `Barge-In` is enabled for these nested prompts).

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.

playBeep

OPTIONAL

Type: boolean
Default: false

record

OPTIONAL

option

type

default

required

details

saveRecording

boolean

false

optional

When set to true, a recording for captured audio will be made available.

rcrdTerminationSilenceTimeMs

integer>0

3000

optional

The time duration for silence in input before the recording is completed due to inactivity.

maxLengthSec

integer

(min:1, max 25)

25

optional

The maximum length of the audio capture. Specified in seconds as this is typically a much larger value than the other timeouts involved in recording which are specified in milliseconds. Value below 1 second will be set to 1 second. Value above 25 seconds will be set to 25 seconds.

privacyForLogging

OPTIONAL

Type: boolean
Default: false

privacyForRecording

OPTIONAL

Type: boolean
Default: false

prompts

OPTIONAL

Type: Array
Default: null

Usage notes

Command Completion

Whenever record/transcribe combinations are specified, whichever action takes the longest will determine when the callback is invoked. There will be only one callback with the results from any/all of the options chosen. Total timeout for this command will be the maximum value of the maxLengthSec parameter (15 sec).

Privacy/PCI Compliance

If a recording is generated, this recording will only be available for download for 2 minutes prior to deletion. It also cannot be used as a parameter for a Play command.

It's important to note that privacy flags are set at the command level, if Play, Say, or Pause specify privacy flags, these will be used instead of the TranscribeUtterance privacy flags.

privacyForLogging	privacyForRecording	logging	utterance recording	full call recording
false	false	full	persistent	full
false	true	full	transient	squelched
true	false	obscured	persistent	full
true	true	obscured	transient	squelched