CallXML 3.0 Development Guide Home  |  Frameset Home

<inputdigits>  element


<inputdigits> is an element that combines the functionality and attributes of a <block> element, <playAudio> element, and a <getDigits> element. The intent of this element is to foster easy creation of scripts which prompt the user to enter variable DTMF digits such as pin codes, pager messages, and numeric values. Only event handler tags for the possible events listed below can exist inside this tag. Any other tags found will result in an error.


usage

<inputdigits cache="(yes|no)" cleardigits="(true|false)" format="string - URI" id="(element id)" includetermdigit="(true|false)" label="(navigation identifier)" maxdigits="(numeric value)" maxsilence="(m|s|ms)" maxtime="(m|s|ms)" next="(navigation identifier)" repeat="(numeric value)" say="STRING" termdigits="(123456789*#|ABCD)" test="CDATA" value="string - URI" value-is="STRING" value-is-not="STRING" var="(variable name)">


attributes

cache Data Type: (yes|no) Default: none - attribute is optional
Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
cleardigits Data Type: (true|false) Default: false
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.
format Data Type: string - URI Default: none - attribute is optional
The 'format' attribute defines the string  formatting to use for the element.  If the value is undefined, the audio file format should be determined from the file name extension, if possible, and, if necessary, override the default format.
id Data Type: (element id) Default: none - attribute is optional
The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the <on> element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur.
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.
label Data Type: (navigation identifier) Default: none - attribute is optional
This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references
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.
next Data Type: (navigation identifier) Default: none - attribute is optional
The 'next' attribute sets the URL the CallXML platform will go to when the container ends.
repeat Data Type: (numeric value) Default: 1
The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result.  Also note that if the value is zero the content will be skipped.
say Data Type: STRING Default: none - attribute is optional
The 'say' attribute allows the developer to specify backup TTS to be output in the event that the .wav file cannot be found.
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".
test Data Type: CDATA Default: Optional
The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document.
value Data Type: string - URI Default: none - attribute is required
The 'value' attribute defines the audio file to play to the caller when the parent element is first entered.
value-is Data Type: STRING Default: none - attribute is optional
Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not Data Type: STRING Default: none - attribute is optional
Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.
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.



code samples

<3.0 inputdigits label-value-var-maxdigits>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
  <do label="B1">
    <prompt>
      Here, we can input digits until our heart is content.
      Or until we press a total of three, whichever come first.
    </prompt>
    <goto value="#Dig_1"/>
  </do>

  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var" maxdigits="3"/>


  <on event="maxdigits">
    <prompt>
      You must have pressed three digits, which equates to $Dig_Var; .
    </prompt>
  </on>

</callxml>



<3.0 inputdigits repeat-cache-maxsilence>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
<do label="B1">
    <prompt>
      Here, we can input digits until our heart is content.
      However, if we input nothing, then the audio file will be repeated.
    </prompt>
    <goto value="#Dig_1"/>
  </do>

  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var" repeat="5" maxsilence="5s" cache="yes" maxdigits="3">


  <on event="maxsilence">
    <prompt>
      you didnt enter any digits, home boy.
    </prompt>
  </on>

  <on event="maxdigits">
    <prompt>
      However, your digit input was $Dig_Var;
    </prompt>
  </on>

</inputdigits>

</callxml>



<3.0 inputdigits maxtime-termdigits-includetermdigit>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
  <do label="B1">
    <prompt>
      Here, we can input digits until our heart is content.
      Or until max time elapses, whichever come first.
    </prompt>
    <goto value="#Dig_1"/>
  </do>

  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var" maxtime="8s" termdigits="#" includetermdigit="true" maxsilence="12s"/>


  <on event="maxtime">
    <prompt>
      You must have reached max time.
    </prompt>
  </on>

  <on event="termdigit:#">
    <prompt>
      Hey, you must have hit the pound key.
      The digit values pressed are $Dig_Var;
    </prompt>
  </on>

</callxml>



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

<callxml version="3.0">

  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_3">

    <on event="maxdigits">
      <prompt>
        You must have pressed three digits.
      </prompt>
    </on>

  </inputdigits>


  <do label="B_2">
    <prompt>
      This block will be skipped!
    </prompt>
  </do>

  <do label="B_3">
    <prompt>
      We are now in the last target, designated by the
      input digits next attribute.   
    </prompt>
  </do>

</callxml>



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

<callxml version="3.0">

  <do value="moe">

  <say>
  lets see about illustrating the value is attribute of input digits.
  you can press three digits here.
  </say>

<!-- this will not be executed, as 'moe' is not equal to 'larry' -->
  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_2" value-is="larry">

    <on event="maxdigits">
      <say>
        You must have pressed three digits.
      </say>
    </on>

  </inputdigits>

<!-- this will not be executed, as 'moe' is equal to 'moe' -->
  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_3" value-is-not="moe">

    <on event="maxdigits">
      <say>
        You must have pressed three digits.
      </say>
    </on>

  </inputdigits>


<!-- this will be executed, as 'moe' is not equal to 'curley' -->
  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_4" value-is-not="curley">

    <on event="maxdigits">
      <say>
        You must have pressed three digits.
      </say>
    </on>

  </inputdigits>
  </do>

  <do label="B_2">
    <say>
      This block will be skipped!
    </say>
  </do>

  <do label="B_3">
    <say>
      This block will be skipped!
    </say>
  </do>

  <do label="B_4">
    <say>
      We are now in the last target, designated by the
      input digits next attribute.   
    </say>
  </do>

</callxml>



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

<callxml version="3.0">

  <do>

  <say>
  lets see about illustrating the value is attribute of input digits.
  you can press three digits here.
  </say>

<!-- this will not be executed, as 'moe' is not equal to 'larry' -->
  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_2" test="'moe' = 'larry'">

    <on event="maxdigits">
      <say>
        You must have pressed three digits.
      </say>
    </on>

  </inputdigits>

<!-- this will not be executed, as 'moe' is equal to 'moe' -->
  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_3" test="'moe' != 'moe'">

    <on event="maxdigits">
      <say>
        You must have pressed three digits.
      </say>
    </on>

  </inputdigits>


<!-- this will be executed, as 'shemp' is not equal to 'curley' -->
  <inputdigits label="Dig_1" value="MyIntro.wav" var="Dig_Var"
                    maxdigits="3" next="#B_4" test="'shemp' = 'curley'">

    <on event="maxdigits">
      <say>
        You must have pressed three digits.
      </say>
    </on>

  </inputdigits>
  </do>

  <do label="B_3">
    <say>
      This block will be skipped!
    </say>
  </do>

  <do label="B_4">
    <say>
      We are now in the last target, designated by the
      input digits next attribute.   
    </say>
  </do>

</callxml>




additional links

none


  ANNOTATIONS: EXISTING POSTS
ssa_VoPorta
9/4/2008 11:31 AM (EDT)
In the above example, where you use termdigits="#"  you show one of your 'events' as:

<on value="termdigit=#">
    <prompt>
      Hey, you must have hit the pound key.
      The digit values pressed are $Dig_Var;
    </prompt>
</on>

This doesn't work. You have to use the event:

<on event="termdigit:#">

We love the Voxeo platform, but it appears to me someone needs to take the time to go through the examples, and make sure they work and are correct. I assume your users often copy and paste code snippets directly from your examples.

CW
voxeo_chris
9/4/2008 11:40 AM (EDT)
Hey CW,

Thanks for notifying us of this and we will look into correcting it.  We are currently undergoing a massive reconstruction of the docs and rewriting all the code for the newer platforms.  You will be seeing older examples being replaced over the next few months.  We test all of our code and work hard to ensure that everything is compatible for many different scenarios. 

Regards,
Chris
tippu.bt
7/17/2009 7:48 AM (EDT)
...
voxeojeremyr
7/17/2009 8:24 AM (EDT)
Hello tippu.bt,

I am not sure if this posting was accidental but I just wanted to check in to see if you had any questions that we could help out with.

Please let us know if you need any assistance.

Regards,
Jeremy Richmond
Voxeo Support
slck
8/19/2011 8:23 AM (EDT)
Hi,

I need to create an <inputdigits> element where the user can either enter 0 or 5 and then has to press "#" which will send that variable to my servlet. ie. # should be the termdigit and maxdigits=2 .How can I do this.
VoxeoDante
8/19/2011 2:08 PM (EDT)
Hello,

I do not think that input digits is the element that you are going to want to use here.  I say this because there is no method in side of input digits that will allow you to specify the list of digits that you want to accept.

I would suggest that you take a look at using a prompt with choices as this will allow you to specify the digits you would like to allow.

Please take a look at the documentation page for Prompt;

http://docs.voxeo.com/callxml/3.0/prompt.htm

and let us know if you are not able to figure this out.

Once you have the choice picked, you can send the data to your backend via <fetch>;

http://docs.voxeo.com/callxml/3.0/fetch.htm


Regards,
Dante Vitulano
Hosted Solutions Engineer

[url=http://www.voxeo.com/summit2011/]
[img=http://evolution.voxeo.com/images/summit2011footer.jpg/]
[/url]
[b][color=blue]Join us October 10-12 in Orlando for Customer Summit 2011[/color][/b]

[b][url=http://www.voxeo.com/summit2011/]REGISTER NOW![/url][/b]
slck
10/18/2011 8:40 AM (EDT)
Hi,
I was previously using prophecy 8.In that the following code used to work


        String maxTime = "3m";
String maxSilence = "5s";
String termDigits="012345*";
String variableName = "menuResponse";
String maxDigits = "1";

<inputdigits cleardigits="true" text="some message" var="<%=variableName %>" maxtime="<%=maxTime %>" maxsilence="<%=maxSilence %>" termdigits="<%=termDigits %>" maxdigits="<%=maxDigits %> " includetermdigit="true"/>

<on event ="termdigit:0">
<goto value="/TestThis" submit="*" method="get"/>
</on>

...


In the page"TestThis" I used to get the value of the variable "menuResponse" correctly using,
request.getParameter("menuResponse").


But recently when I tried this in prophecy11.I can't get the value of the variable in the page TestThis .Instead I am getting a empty string instead of the value.

I also noticed that when i changed maxdigits to 2 and then entered any 2 digits ending with 0,i'm getting the correct 2 digit number in the page "TestThis".
Also If I press only 0(single digit) i'm getting an empty string instead of 0 which I'm expecting.

Why is this.
VoxeoDante
10/21/2011 4:40 PM (EDT)
Hello,

I apologize, but in order for us to be able to pin this down for you definitively, we will need to see the logging from the application.  If you do not wish to share the logging from your application on this public forum, we can move your post into a private account ticket, and we can proceed from there.

Regards,
Danté Vitulano
Hosted Solutions Engineer

[url=http://www.voxeo.com/university/home.jsp]
[img=http://www.voxeo.com/images/logos/VoxeoUnivLogo.png/]
[/url]
[b][color=blue]Interested in Training? Visit the Voxeo University Page to Learn More![/color][/b]

login


© 2012 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site