callxml elements - getdigits

CallXML 2.0 Development Guide

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

<getdigits> element

The getDigits element reads input touch-tone digits from the call and places them into a variable by the var attribute. This element is typically used for such tasks as gathering PIN codes, pager numbers, and anything else that involves multiple digits coming from the user. Handling any digits gathered requires an associated <onTermDigit> event element within the scope of the <getdigits> element.

usage

cleardigits	Data Type: (true\|false)	Default: none - attribute is optional
	This attribute's value is a Boolean, indicating whether the queued digits buffer should be cleared when this action starts. "true" clears the digits buffer; "false" leaves the contents of the digit buffer alone.
includetermdigit	Data Type: (true\|false)	Default: none - attribute is optional
	This attribute defines whether the terminating digit should be included with the collected digit string. A value of 'true' indicates that the terminating digit will be appended to the string, and 'false' will ensure that the terminating digit pressed by the caller will not be included in the string.
maxdigits	Data Type: (numeric value)	Default: none - attribute is optional
	This attribute denoted the maximum number of digits to collect from the caller. When the maximum amount of digits has been reached, application execution will resume from within the <onmaxdigits> handler, if present.
maxsilence	Data Type: (m\|s\|ms)	Default: 5s
	This attribute specifies the maximum time to wait between keypresses before a executing any repeat actions, if specified. The time string format is: <numeric value>[<optional qualifier>] \| nolimit The string begins with a required numeric value. The valid qualifiers are: m: minutes s: seconds (default) ms: milliseconds Example: "45m 33s 117ms" Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
maxtime	Data Type: (m\|s\|ms)	Default: 30s
	The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
termdigits	Data Type: (123456789*#\|ABCD)	Default: none - attribute is optional
	This attribute holds the list of touch-tone digits which can terminate the current caller action. Note that for each termdigit specified, there should be an <ontermdigit> handler in the code to catch the event. Allowable values are any one of "012356789*#", the ordinary DTMF (Touch-Tone) keypad possibilities, plus the special keypad tones found on some telephones "ABCD".
var	Data Type: (variable name)	Default: none - attribute is required
	This defines the variable name in which to store the digits collected. Not specifying a value for this attribute will cause a fatal application error.

possible events

onerror type="document"	Document was unable to be fetched for all the reasons web servers are unavailable
onerror type="linenotactive"	Trying to issue a telephony event such as <getdigits> or <playaudio> on a non-active line
onerror type="telephony"	Unable to issue a telephony event such as <call> or <playaudio> or <ftp>
ontermdigit	Used for catching and handling term digit events as they occur in the call flow. See the ontermdigit element description for further details.
onmaxdigits	This event occurs during user input if the length of the string of digits entered by the user exceeds the number indicated by a maxDigits attribute and a terminating digit has not yet been pressed. See the onmaxdigits element description for further details.
onmaxsilence	This event occurs when the application has waited too long between digit entries or detects too much silence at the end of a recording session. See the onmaxsilence element description for further details.
onmaxtime	This event occurs during user input if the user takes more time than is allowed by a maxTime attribute to input their entire response. See the onmaxtime element description for further details.

code samples

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="2.0">
<block label="B1">
<text>
Press any number, followed by the pound key.
</text>
<getdigits var="Var_1" termdigits="#"
includetermdigit="true"/>

<ontermdigit value="#">
<text>
say, you must have pressed $Var_1;
</text>
</ontermdigit>
</block>
</callxml>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="2.0">
<block label="B1">
<text>
start pressing digits until max time is reached
</text>
<getdigits var="Var_1" maxtime="3s"/>

<onmaxtime>
<text>
You managed to press $Var_1; in the 3 seconds we allowed you
to input keypresses.
</text>
</onmaxtime>

</block>
</callxml>

<?xml version="1.0" encoding="UTF-8"?>

<callxml version="2.0">
<block label="B1">
<text>
Start pressing digits until we hit max digits.
Or, dont press any digits, and we will hit a max silence event.
</text>
<getdigits var="Var_1" maxsilence="2s" maxdigits="5"/>

<onmaxdigits>
<text>
You must have pressed a total of five digits, which were $Var_1;
</text>
</onmaxdigits>

<onmaxsilence>
<text>
You must have stopped pressing keys for at least two seconds.
</text>
</onmaxsilence>

</block>
</callxml>

additional links

none

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page