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.

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

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:

Type: absolute URL

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

For the complete set of parameters included in the POST request, see getDigits.

reason Valid Values

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.

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.

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 ("").

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.

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.

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.

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.

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.