The <GetDigits/> Element

This element collects digits that a caller inputs using the keypad. When the caller is done entering data, Basix submits that data to the provided 'action' URL in an HTTP POST request. The action can also be a XML file in your domain storage.

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

You may optionally nest <Play/>, <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.

Nested elements with purpose="prompt" (default) are used to compose the GetDigits prompt.

Nested elements with purpose="alert" are used to compose the "invalid input" prompt.

There is a limit up to 125 child elements: if you provide more than 125 nested <Play/>, <Say/>, <Speak/> or <Wait/> elements, the elements over 125 will be ignored.

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. See XML Fetch Fallback This attribute is optional: if absent the processing will proceed to the next XML element.
timeout Timeout for reception of the first digit positive integer 5 seconds
interdigitTimeout Timeout for reception of a subsequent digit when one is received positive integer 5 seconds
finishOnKey Collection terminator 1234567890*# #
numDigits Maximum number of digits to collect integer >= 1 99
validDigits Set of digits the user is allowed to enter 1234567890*# 1234567890*#
maxTries Maximum number of attempts in case no digits are detected integer >= 1 1
playBeep Play beep after all nested audio elements complete true, false false
retries DEPRECATED (use maxTries instead). Maximum number of retries in case no digits are received integer >= 1 1
invalidDigitsSound DEPRECATED (use Speak/Play/Wait with purpose="alert" instead). File to play if user enters invalid digit path to wav file none

Digit Collection Notification Parameters

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

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

If action is not set, processing will continue with the next element (so Digits can be inspected using element Switch for example).

Examples

Example 1: Nested <Speak/> element

1
2
3
4
5
6

<IVR>
  <GetDigits action="http://www.foo.com/process_gather.php">
    <Speak voice="en-US-Standard-C">Please enter your 6-digit account number, followed by the hash key</Speak>
  </GetDigits>
  <Speak voice="en-US-Standard-C">Input not received. Bye bye!</Speak>
</IVR>
  • If the caller enters a digit during audio playback, the audio will stop and Basix 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. Basix 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, Basix will submit the digits as POST request to the Action URL.

Example 2: passing processing to another IVR defined in a XML file

1
2
3
4
5
6

<IVR>
  <GetDigits action="file://ivrs/main/menu1.xml">
    <Speak voice="en-US-Standard-C">Please enter your 6-digit account number, followed by the hash key</Speak>
  </GetDigits>
  <Speak voice="en-US-Standard-C">Input not received. Bye bye!</Speak>
</IVR>

Example 3: specifying 'input error' prompt (nested elements with purpose="alert")

1
2
3
4
5
6
7
8
9

<IVR>
  <GetDigits action="http://www.foo.com/process_gather.php" maxTries="5" validDigits="0123456789" numDigits="6">
    <Speak voice="en-US-Standard-C">Please enter your 6-digit account number, followed by the hash key</Speak>
    <Play purpose="alert">wrong_input_buzzer.wav</Play>
    <Wait purpose="alert" length="1"/>
    <Speak purpose="alert" voice="en-US-Standard-C">Invalid input</Speak>
  </GetDigits>
  <Speak voice="en-US-Standard-C">Input not received. Bye bye!</Speak>
</IVR>