CallXML Grammar Basics

The CallXML markup allows developers several options to choose from when developing recognition grammars for voice and dtmf input. During the prototyping stage of application development, it is important to know which grammar development methods will be best suited for your application needs. For grammars that require just a few options to be recognized, it is probably best to simply specify an inline grammar contruct within a "choice" attribute, but for a more complex grammar that requires a sizable amount of recognizable user utterances, it's probably best to work out an external JSGF grammar construct. And in cases where you need to recognize a digit string of varying length, it's typically best to leverage built-in digit grammars: Below, we will detail all these options and how to implement them.

Using grammar "choices"

The "choices" attribute is the attribute that you will typically leverage to define utterance or dtmf inputs that your CallXML application will recognize: This attribute is available for use within the context of several different CallXML elements, and being knowledgeable about how each element behaves in conjunction with the "choices" attribute is very important during the design stage of application development. Note that while there are some similarities between "choices" and other input-capture elements and attributes (such as the <getdigits>, and <inputdigits> elements, and the "termdigits" attribute) it is important to remember that while "choices" can capture voice and dtmf input, the other input-capture options will only collect dtmf input from the caller. The CallXML elements that support the "choices" attribute are listed below:

<block>, <case>, <do>, <if>, <switch>, <with>
<menu>
<playaudio>
<prompt>
<say>
<wait>

Grammar Scoping

Given the top-down execution model of CallXML, some very important facts about scoping should be taken into account. When choices is defined in a container element, the recognition choices will be inherited by any and all child elements of the container. To illustrate, consider that each of the code samples below are essentially identicalA:

Container Element "choices" scoping: Inherited values



 <block choices="1">

  <playaudio value="Welcome.wav"/>

  <say>press one here</say>

    ...

 </block>

Container Element "choices" scoping: Explicitly-defined values



 <block>

  <playaudio value="Welcome.wav" choices="1"/>

  <say choices="1">press one here</say>

   ...

 </block>

It is also important to remember that when defining a input for a media element, that you will need to define a <wait> element to allow callers enough time to enter their input. Take the following example:

Caller Input Window: Short



 <block choices="1">

  <say>press one here</say>

  <on event="choice">

 <!-- do stuff -->

  </on>

 </block>

In this case, once the initial TTS defined in the <say> element has rendered to the caller, the "window of opportunity" for user input is effectively over, which doesn't leave a lot of room for caller error. Generally speaking, best practices indicates that you should also define a <wait> of anywhere between 3-8 seconds in length to allow the caller a bit more time to provide input:

Caller Input Window: Best Practices



 <block choices="1">

  <say>press one here</say>

 <wait value="5s"/>

  <on event="choice">

 <!-- do stuff -->

  </on>

 </block>

It is also very important to mention that developers should use caution when nesting container elements that are expected to accept input, as this can cause unexpected problems for the event handling: Our CallXML Best Practices Guide contains more information on this specific topic.

CallXML Built-in Grammar Syntax



 <block choices="[5 DIGITS]">

 <block choices="[2-5 DIGITS]">

Grammar Entry	Explanation
`choices`	The primary attribute that is used to specify a simple grammar construct in the CallXML markup language. Note that multiple utterance entries in this attribute are comma-delimited.
`[5 DIGITS]`	Developers can specify a static range that defines the string length that is to be collected from the caller via dtmf or via voice: In this case, a digit string length of "5" (i.e., "22334") would be considered a valid grammar match.
`[2-5 DIGITS]`	Developers can specify a wider range in terms of spoken or dtmf digit entry, where the first number defines the minimum length, and the second number defines the max length: In this instance, a caller could enter a string that was at least two digits (i.e., "47"), and as many as five (i.e., "88754") or anything in-between. Note: You must add `<assign var="settings.choices.completetimeout" value="10000ms"/>` to set the wait time for variable digits. 10000ms=10s wait

Simple "choice" Grammar Syntax



 <block choices="1, one">

Grammar Entry	Explanation
`choices`	The primary attribute that is used to specify a simple grammar construct in the CallXML markup language. Note that multiple utterance entries in this attribute are comma-delimited.
`1`	Any numeric value specified as a value of a "choices" attribute denotes a dtmf grammar entry that corresponds to the number specified. i.e.; in this case, pressing "dtmf-1" on the telephone keypad will result in a valid grammar match, which would result in the dialog variable being populated with a value of "1".
`one`	Any plain-text value specified within a "choices" attribute denotes a spoken-word grammar entry, where the dialog variable will be populated with the exact text specified in the "choice" entry: In this case, the user utterance of "one" would result in the dialog variable being set to "one".

Complex "choice" Grammar Syntax



 <block choices="ONE (one, uno, 1)">

Grammar Entry	Explanation
`choices`	The primary attribute that is used to specify a simple grammar construct in the CallXML markup language. Note that multiple utterance entries in this attribute are comma-delimited.
`(1)`	Any numeric value specified as a value of a "choices" attribute denotes a dtmf grammar entry that corresponds to the number specified. i.e.; in this case, pressing "dtmf-1" on the telephone keypad will result in a valid grammar match, which would result in the dialog variable being populated with a value of "ONE".
`(one, uno)`	Any plain-text value specified within a "choices" attribute denotes a spoken-word grammar entry, but in this case, the dialog variable is not set to the utterance value (see next table row).
`ONE`	Values that precede the utterances specified in the parenthesis in a complex inline "choices" grammar specify the value that the dialog variable will be populated with upon a match: In this instance, the dialog variable will equate to "ONE" on a valid grammar match.

Note: As with simple inline constructs, developers can specify multiple entries for a complex inline grammar by comma-delimiting the values:

<block choices="ONE (one, uno, 1), TWO (two, deux, dos, 2)">

Simple JSGF Grammar Syntax



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

<callxml version="3.0">



 <assign var="myGram">

     <![CDATA[

                    #JSGF 1.0;

                    grammar MYRULENAME;

                    public <MYRULENAME> = (yes|dtmf-1);

      ]]>

  </assign>



 <block label="B1" choices="jsgf:$myGram;">



  <say >say yes or no here for fun and profit</say>

  <wait value="5s"/>

  <on event="choice">

   <log>*** $session.lastchoice; ***</log>

  </on>



</block>

</callxml>

Grammar Entry	Explanation
`<assign>` element	When specifying complex JSGF constructs, it must be defined as a value of a CallXML variable. This variable name is then populated into the "choices" element.
`<![CDATA[ .... ]]>`	Any JSGF grammar content must be enclosed within a CDATA tag to prevent the grammar content from being parsed as XML data: Without a CDATA tag, any grammars defined would cause a failure to parse, and a subsequent fatal application error.
`#JSGF 1.0;`	Header that is used to declare the construct as a JSGF grammar, which is absolutely required when coding complex CallXML grammar structures using JSGF syntax.
`grammar MYRULENAME;`	Specifies the Top-Level-Rulename that is used for JSGF grammar execution. See the JSGF specification for additional details.
`public <MYRULENAME>`	Defines a single sub-rule in the JSGF grammar, which contains the actual utterance entries that can be defined within a grammar. See the JSGF specification for additional details.
`(yes\|dtmf-1)`	Specifies the voice utterance ("yes") or the dtmf inpit (dtmf-1) that can be recognized. Note that multiple entries are pipe-delimited (\|)
`choices`	The primary attribute that is used to specify a simple grammar construct in the CallXML markup language. In this case, the value of this attribute is that of the previously-defined CallXML variable that the grammar is defined in, and must be preceded by a "jsgf:" declaration.

ANNOTATIONS: EXISTING POSTS

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

XPath Functions

| TOC