The GetDigits Element

The GetDigits element is used to collect the digits entered by a caller. Once the caller has finished entering the digits, the API submits the data to the provided action URL using a HTTP GET or POST request.

You could play a message nested inside the GetDigits element while the digits are being received in the background. This is useful for creating a phone tree (IVR).

Nesting Rules

You can nest <Speak> and <Play> elements within the <GetDigits> element.

Attributes

The attributes supported by the <GetDigits> element are listed below. The default behavior of each attribute can be modified using the allowed values.

Attribute Name Description Allowed Values Default Value
action The URL to which the digits are sent. See the action Request Parameters table below for more information absolute URL none
method Submit to action URL using GET or POST. GET, POST POST
timeout Time in seconds to wait to receive the first digit. If the user fails to provide an input within the timeout period, the next element in the response is processed. positive integer 5 seconds
digitTimeout Time in seconds allowed between consecutive digit inputs. If input is not provided within the digitTimeout period, digits entered until then will be processed. positive integer 2 seconds
finishOnKey This can be any number or a special character, such as, an asterisk (*) or a pound (#) that is used to complete the task of capturing digits. If finishOnKey is set to None, the default option is disabled and timeout will occur based on digitTimeout or numDigits parameters. If these parameters are not specified, timeout will occur according to the default value of the digitTimeout parameter. any digit, #, * #
numDigits Maximum number of digits to be processed in the current operation. Only the number of numDigits is captured and any additional digits entered are ignored. integer >= 1 99
retries Indicates the number of retries the user is allowed to input the digits, if digits are not received within the time specified by timeout. integer >= 1 1
redirect Redirect to action URL if true. If false,only request the URL and continue to next element. true,false true
playBeep Plays a beep when all Speak and Play elements finish executing. true,false false
validDigits Set of digits which the user is allowed enter. any digit, #, * 1234567890*#
invalidDigitsSound URL of the sound file to be played when the user enters an invalid digit. Any remote sound file URL (mp3 or wav) none
log If true, Plivo will log digits entered by the caller and you can view the same in debug logs. If false, logging will disabled while processing <GetDigits> Element. true, false true

action Request Parameters

The following parameters are sent to the action URL after a DTMF input has been captured.

Parameter Description
Digits The digits inputted by the caller, excluding the finishOnKey digit if used.

Phone Tree

After the caller enters digits on the keypad, Plivo sends them as a request to the action URL. We also add a nested <Speak> element. This means that input can be gathered at any time during <Speak>.

<Response>
    <GetDigits action="http://www.foo.com/gather_pin/" method="POST">
        <Speak>Enter your 4-digit pin number, followed by the hash key</Speak>
    </GetDigits>
    <Speak> Input not received. Thank you </Speak>
</Response>

If the caller enters a digit during the speaking of the text, the <Speak> element will stop speaking and wait for digits, # sign, or a timeout.

If <GetDigits> tag times out without input, the <Speak> element will complete and the <GetDigits> element will exit without submitting. Plivo will then process the next element in the document, which in this case is a <Speak> element which informs the caller that no input was received.

For a nested phone tree, you should return a GetDigits XML from the action URL. In the above case, when the caller enters the 4 digit pin number, Plivo will POST the Digits to the action URL, your application should return the following XML to play another message and accept inputs.

<Response>
    <GetDigits action="http://www.foo.com/gather_department/" method="POST">
        <Speak>Enter 1 for support and 2 for sales</Speak>
    </GetDigits>
</Response>