gather@v4

Gather digits (DTMF) from the caller, optionally prompted by a text-to-speech (tts) or an audio file of your library (audioFile).


Version	`gather@v4`
Runs in	`inbound-call` and your own branches

Parameters

Name	Type	Required	Default	Description
`endOnKey`	string		`"#"`	DTMF key that ends the gather accepts `${{ }}`
`maxDigits`	integer		`0`	Maximum number of digits to collect: 0..30 accepts `${{ }}`
`timeout`	number		`10`	Timeout in seconds: 1..60 accepts `${{ }}`
`stopOnTalk`	object			Stop action when talk is detected accepts `${{ }}`
`stopOnTalk.enabled`	boolean	yes	`false`	accepts `${{ }}`
`stopOnTalk.minWords`	integer		`2`	1..30 · accepts `${{ }}`
`tts`	object			Text-to-speech prompt: text (1 to 1024 characters), with an optional voice or language (exclusive). Without them, the defaults of the branch or of the scenario apply. text-to-speech prompt: `text`, and `voice` or `language`
`audioFile`	object			An audio file of your library, by its SID (REST API v2 identifier). audio file of your library: `sid`

Every parameter that accepts ${{ }} can be computed from an expression.

How it works

Same as gather@v3, with the same parameters as play@v3: the prompt is tts (text-to-speech) or audioFile (audio file of your library). Set at most one of them: without any, the gather is silent. The first key pressed stops the prompt, the digits are still collected. The timeout also applies to the prompt: use a timeout longer than your audio file.

If you specify a maxDigits parameter, the gather will stop after the caller has pressed the specified number of digits. Otherwise, the gather will stop after the timeout, or when the caller presses the <endOnKey> key (default: #).

Examples

Short example with a text-to-speech prompt

- action: gather@v4
  params:
    maxDigits: 1
    tts:
      text: Hello! Press 1 to accept the call, press 2 to hangup
  result: $digits

Short example with an audio file prompt

The SID is the audio file identifier of the REST API v2 (8 lowercase characters) see: https://docs.callr.com/reference/audiofilesget

- action: gather@v4
  params:
    maxDigits: 1
    audioFile:
      sid: 'fdsanjkf' # quote it: an all-digit SID would be read as a number
  result: $digits

Full example with defaults

- action: gather@v4
  params:
    maxDigits: 0 # (0..30) 0 = disabled
    endOnKey: '#' # (string) key to stop the gather
    timeout: 10 # seconds (1..60)
    tts: # or audioFile: { sid: 'fdsanjkf' }, or none: silent
      text: Please enter your code # (1..1024 characters)
      # voice: en-US-AvaMultilingual # or language: en-US (default: the scenario defaults)
    stopOnTalk:
      enabled: false
      minWords: 2
  result: $digits

Result

Set result: $myVariable to keep it. Result of gather@v2, gather@v3 and gather@v4

Field	Type	Description
`ok`	boolean	`true` when digits were entered (or when the caller's speech stopped the prompt)
`timeout`	boolean	`true` when the caller did not finish in time. `input` holds the digits entered so far
`error`	string	Only present on error: `hangup` when the caller hung up, `canceled`, or the error message
`input`	string	Digits entered, never including the `endOnKey`
`stoppedOnKey`	string	The `endOnKey` pressed by the caller, empty otherwise
`stoppedOnTalk`	boolean	`true` when the caller's speech stopped the gathering (`stopOnTalk`)
`recognized`	string	Text said by the caller when `stoppedOnTalk` is `true`, empty otherwise

{
  "ok": true,
  "timeout": false,
  "input": "1234",
  "stoppedOnKey": "#",
  "stoppedOnTalk": false,
  "recognized": ""
}

Older versions

Older versions keep working in existing scenarios. Use the version above in new scenarios.

gather@v3: Gather digits (DTMF) from the caller, prompted by an audio file (sid) or a text-to-speech (prompt)
gather@v2: Gather digits (DTMF) from the caller
gather@v1: Use gather@v2 instead gather@v1 is deprecated, use gather@v4