The <GetDigits> element collects digits that a caller enters into their phone keypad. When the caller is done entering data, Plivo submits that data to the provided 'action' URL in an HTTP POST request.

If no input is received before timeout, <GetDigits> falls through to the next element.

You may optionally nest <Play>, <Say>, <Speak> and <Wait> elements within a <GetDigits> element while waiting for input. This allows you to read menu options to the caller while letting them enter a menu selection at any time. After the first digit is received the audio will stop playing.

Element Attributes

Attribute Name Description Allowed values Default Value
action URL to be called when digit collection finishes. It can be a list of URLs separated by commas (to permit fallback in case the main URL fails to reply)
timeout Timeout for reception of the first digit positive integer 5 seconds
finishOnKey Collection terminator any digit, #, * #
numDigits Maximum number of digits to collect integer >= 1 99
retries Maximum number of retries in case of no digits received integer >= 1 1
playBeep Play beep after all nested audio elements complete true, false false
validDigits Set of digits the user is allowed to enter any digit, #, * 1234567890*#
invalidDigitsSound File to play if user enters invalid digit wav or mp3 file none

After digit collection completes, Plivo will call the 'action' URL with the following parameters:

Parameter Description
Digits The digits the caller pressed, excluding the finishOnKey digit if used

Examples

Example 1: Nested <Speak> element

<Response>
    <GetDigits action="http://www.foo.com/process_gather.php">
        <Speak voice="rms">Please enter your 6-digit account number, followed by the hash key</Speak>
    </GetDigits>
    <Speak voice="rms">Input not received. Bye bye!</Speak>
</Response>
  • If the caller enters a digit during audio playback, the audio will stop and Plivo will wait for digits or a timeout.
  • If <GetDigits> tag times out without input, the <Speak> element will complete and the <GetDigits> element will exit without calling the action URL. 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.
  • If the caller enters 123456 and then hits # or allows five seconds to pass, Plivo will submit the digits as POST request to the Action URL.