GetDigits

The GetDigits command collects DTMF inputs from the caller. It is only supported only when there is a single party on the Call.

GetDigits is a terminal command — any actions following it are never executed. When the Caller is done entering the digits, FreeClimb submits that data to the provided actionUrl using an HTTP POST request. Your server will be required to respond to the FreeClimb Webhook with PerCL to continue handling the call. If the reason the command terminated is hangup (see reason below), any PerCL returned will not be executed.

Nesting Rules

The GetDigits command cannot be nested within any other command. You can nest the following actions within the GetDigits command:

  • Say
  • Play
  • Pause

The commands are not directly nested, but rather are contained in the prompts attribute as a list of commands.

The nested commands (Say, Play, and Pause) will have barge-In enabled.

When there are nested Say and Play commands, the timeout begins after either the audio completes, or the first key is pressed. In the second example below, the initialTimeoutMs begins after the second prompt has been completed. If during this time, the Caller enters a digit, the prompts are terminated and the digitTimeoutMs begins.

Examples

In this example, the caller is prompted to enter their PIN. The caller can enter up to 16 digits followed by # key with a maximum delay of up to 3 seconds between digit presses.

[
    {
        "GetDigits": {
            "actionUrl": "http://www.foo.com/userpin.php",
            "prompts": [
                {
                    "Say": {
                        "text": "Please enter your pin followed by the pound key."
                    }
                }
            ]
        }
    }
]

In this example, we specify more detailed requirements for the collection process. Here, the caller is first prompted, and if no input is received after two seconds, the caller is prompted one more time.

[
  {
    "GetDigits": {
      "actionUrl": "http://www.foo.com/userpin.php",
      "initialTimeoutMs": 2000,
      "finishOnKey": "*",
      "maxDigits": 4,
      "prompts": [
        {
          "Say": {
            "text": "Please enter your pin. Press star when done."
          }
        },
        {
          "Pause": {
            "length": 2000
          }
        },
        {
          "Say": {
            "text": "Please enter your pin and press star when done."
          }
        }
      ]
    }
  }
]

Command Attributes

GetDigits supports the following attributes that modify its behavior:

Attribute

Description

actionUrl

When the Caller has finished entering digits, FreeClimb will make an HTTP POST request to this URL.

initialTimeoutMs

Maximum time in milliseconds that FreeClimb will wait for the caller to press the first digit before making a determination that a timeout has occurred and moving on to make the request to the actionUrl to submit the results of the GetDigits command.

digitTimeoutMs

Maximum time in milliseconds that FreeClimb will wait for the caller to press any digit after the last digit entered, before making a determination that a timeout has occurred and moving on to make the request to the actionUrl to submit the results of the GetDigits command.

finishOnKey

Digit that causes the input sequence to be deemed complete.

minDigits

Minimum number of digits expected in the input.

maxDigits

Maximum number of digits expected in the input.

flushBuffer

Enables applications to support look-ahead inputs by users so that they can navigate menus without being prompted.

prompts

JSON array of PerCL commands to nest within the GetDigits command.

privacyMode

Indicates if the response will contain sensitive information which should be hidden.


actionUrl

REQUIRED

Type: absolute URL
Default: null

When the Caller has finished entering digits, FreeClimb will make an HTTP POST request to this URL. A PerCL response is expected to continue handling the Call. Make sure to keep “http://“ in the URL.

Additional Request Parameters

Request Parameters

Description

`digits`

String of digits entered by the Caller, excluding the terminating digit (if used).

`reason`

Indicates why the digits field is empty or not. Can be one of the values below.

reason Valid Values

Value

Description

`finishKey`

The finish key had been entered after minimum number of digits had been reached. Indicates populated digits field.

`timeout`

A digit timeout occurred. Indicates either populated or empty digits field.

`hangup`

The caller hung up. Indicates empty digits field.

`minDigits`

Minimum number of digits not reached. Indicates empty digits field.

`maxDigits`

Maximum number of digits reached. Indicates populated digits field.


initialTimeoutMs

OPTIONAL

Type: integer > 0
Default: 6000 (ms)

Maximum time in milliseconds that FreeClimb will wait for the caller to press the first digit before making a determination that a timeout has occurred and moving on to make the request to the actionUrl to submit the results of the GetDigits command. This timeout interval begins when all nested commands have been fully executed.


digitTimeoutMs

OPTIONAL

Type: integer > 0
Default: 3000 (ms)

Maximum time in milliseconds that FreeClimb will wait for the caller to press any digit after the last digit entered, before making a determination that a timeout has occurred and moving on to make the request to the actionUrl to submit the results of the GetDigits command. This timeout interval begins and resets after each digit entered.


finishOnKey

OPTIONAL

Type: any digit, #, or empty string
Default: #

Digit that causes the input sequence to be deemed complete. This attribute defers to the timeout attribute – so, if a timeout occurs, then the command terminates regardless of the value of finishOnKey.

If all keys on the dialing keypad are needed in the gathered digit string, then finishOnKey must be specified as an empty string ("").


minDigits

OPTIONAL

Type: integer >= 0
Default: 0

Minimum number of digits expected in the input. If specified, FreeClimb will return the collected digits only if the caller has entered at least that many digits. The caller inputs are retained in the FreeClimb DTMF buffer for the Call until they are flushed by a GetDigits invocation and when flushBuffer is set to true.


maxDigits

OPTIONAL

Type: integer > 0
Default: 16

Maximum number of digits expected in the input. If the terminating digit is not entered and the caller has entered the maximum number of digits allowed, the GetDigits command terminates regardless of the value of finishOnKey.


flushBuffer

OPTIONAL

Type: boolean
Default: true

If set to true, the FreeClimb platform starts with an empty DTMF buffer to store the digits entered by the caller. If set to false, FreeClimb will append the user inputs to the end of the existing digits buffer and will return digits from the start of the digits buffer. This enables applications to support look-ahead inputs by users so that they can navigate menus without being prompted.


prompts

OPTIONAL

Type: PerCL command array
Default: null

JSON array of PerCL commands to nest within the GetDigits command. The Say, Play, and Pause commands can be used. 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 enter digits.


privacyMode

OPTIONAL

Type: boolean
Default: false

Indicates if the response will contain sensitive information which should be hidden. When set to true, the contents of the digits attribute will be replaced with the string "xxxxx" in the logs. It's important to note that privacyMode is set at the command level, meaning it will not be inherited by any nested commands.