The <GetDigits> element collects digits that a caller enters into their phone keypad. When the caller is done entering data, Basix 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). It can be a Section name within the current document. 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
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, 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
7

<?xml version="1.0" encoding="UTF-8" ?>
<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 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.