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 a getDigits 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
REQUIREDType: 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
reason
Valid ValuesValue | 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
OPTIONALType: 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
OPTIONALType: 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
OPTIONALType: 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
OPTIONALType: 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
OPTIONALType: 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
OPTIONALType: 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
OPTIONALType: 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
OPTIONALType: 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.