Motorola_IP_Phone

An Introduction to VoxML 1.0

Overview

1. An Introduction to VoxML 1.0

Overview

Part of the reason that the World Wide Web has been so popular is the relative ease with which authors can create content using HTML. For all its faults, HTML has served its purpose as a vehicle for the presentation of rich text as well as images, hypertext links, and simple GUI input controls.

VoxML offers the same ease of production to voice applications. In one sense, VoxML offers the same building blocks as HTML: text (which is read via text- to-speech), recorded sound samples (analogous to images), navigational controls, and input controls.

However, writing a voice application is very different from writing a GUI application, and thus the structure of VoxML is very different from HTML. Here are some examples of the differences:

???HTML specifies a two-dimensional layout, whereas VoxML specifies a ???layout??? in the time dimension only.

???HTML is designed and displayed in whole-page units, while VoxML is designed and delivered in whole-dialog units, but presented in much smaller units, called steps.

???A single HTML page often presents the user with dozens of options, which would overwhelm the user of a voice application. In general, voice applications should limit the number of options available at a given step in the dialog to ease the burden on the user???s short-term memory and to improve the performance of the speech recognition.

What is VoxML

VoxML is based on XML. As such, VoxML follows all of the syntactic rules of XML, with semantics that support the creation of interactive speech applications. For more information on the exact structure of the language with respect to XML, see the VoxML 1.0 DTD (Document Type Definition) which is available in Appendix A.

Purpose of this Document

This document serves as the official language reference for VoxML 1.0. It contains information on the syntax of the elements and their attributes, example usage, the structure of VoxML documents (or DIALOGs), and pointers to other reference documentation that may be helpful when developing applications using VoxML.

This document is intended for VoxML application developers.

An Introduction to VoxML 1.0

Structure of a VoxML Document

VoxML documents have a hierarchical structure, in which every element (except the DIALOG element) is contained by another element. In contrast to HTML, there is a strict containment relationship enforced by the language, so there can be no ambiguity as to which element contains which.

DIALOGs and STEPs

The two most fundamental elements in VoxML are the DIALOG element and the STEP element. These elements provide the basic structure of a VoxML application.

The DIALOG element defines the scope of a VoxML document. All other VoxML elements are contained by the DIALOG element. In normal cases, one can equate a DIALOG to a file, in much the same way that there is one HTML element per file when developing HTML-based applications.

The STEP element defines a state within a DIALOG, or to say it another way, the STEP element defines an application state.

Together the DIALOG element and the associated STEP elements define a state machine that represents an interactive dialogue between the application and a user. When the VoxML voice browser interprets the VoxML document, it will navigate through the DIALOG to different STEPs as a result of the user???s responses.

Here is a simple VoxML example, which has 1 DIALOG and 2 STEPs.

1<?xml version="1.0"?>

2<DIALOG>

3<STEP NAME="init">

4<PROMPT> Please select a soft drink. </PROMPT>

5<HELP> Your choices are coke, pepsi, 7 up,

6or root beer. </HELP>

7<INPUT TYPE="optionlist" NAME="drink">

8<OPTION NEXT="#confirm"> coke </OPTION>

9<OPTION NEXT="#confirm"> pepsi </OPTION>

10<OPTION NEXT="#confirm"> 7 up </OPTION>

11<OPTION NEXT="#confirm"> root beer </OPTION>

12</INPUT>

13</STEP>

14<STEP NAME="confirm">

15<PROMPT> You ordered a <VALUE NAME="drink"/>.

16</PROMPT>

17</STEP>

18</DIALOG>

When this VoxML document is interpreted, the voice browser will begin by executing the STEP called ???init???. The user will hear the text contained by the PROMPT element. If the user were to ask for ???help??? before making a selection, the user would hear the text contained with the HELP element. After the user makes a selection, the voice browser will execute the STEP named ???confirm???, which will simply read back the user???s selection and then exit the application.

An Introduction to VoxML 1.0

Structure of a VoxML Document

There are a few important points to be made after looking at this first code example. First, you will notice that line 1 of the source code contains the XML declaration string, which is required to be the first line of all VoxML documents.

Also, STEPs in a VoxML application are executed based on the user???s responses not on the order of the STEPs within the source file. Although the definition of the ???init??? STEP appears on line 3 and the definition of the ???confirm??? STEP appears on line 14, the order in which they are defined has no impact on the order in which the voice browser navigates through them.

Lastly, the line numbers shown in the example listing are not part of the source code. They are shown only to make referencing the code simpler.

The Basic Elements

VoxML contains a lot of elements, which provides the application developer with a lot of flexibility and power in the language. Section 2 of this document describes these elements in detail.

There are, however, a few elements that are used in almost every DIALOG that you will write. These basic elements are found in the example on the previous page. They are DIALOG, STEP, PROMPT, HELP, and INPUT. If you are new to VoxML, you should familiarize yourself with these basic elements before progressing to the other, less frequently used elements.

An Introduction to VoxML 1.0

Other Reference Documentation

The following resources provide more information that may be helpful when developing interactive speech applications using VoxML.

VoxML 1.0 Application Development Guide

This document contains design guidelines and examples for VoxML application developers. It presents a description of the VoxML development environment including system requirements, installation procedures, development tools and a methodology for the development process. The main goal of the document is to provide developers with explicit guidelines for developing successful VoxML applications.

VoxML 1.0 Element Reference

ACK Element

2. VoxML 1.0 Element Reference

This section describes the VoxML elements, their attributes, and their syntax.

Examples are provided to help show common usage of each element.

ACK Element

The ACK element is used to acknowledge the transition between STEPs, usually as a result of a user response. While an application developer could create additional STEPs that were used to acknowledge the user???s response, the ACK element provides an easier way to specify the common sorts of acknowledgements.

An ACK element can be contained within a STEP or a CLASS element.

Syntax

Attributes

VoxML 1.0 Element Reference

ACK Element

Examples

1<STEP NAME="card_type">

2<PROMPT>

3What type of credit card do you have?

4</PROMPT>

5<INPUT NAME="type" TYPE="optionlist">

6<OPTION NEXT="#exp"> visa </OPTION>

7<OPTION NEXT="#exp"> mastercard </OPTION>

8<OPTION NEXT="#exp"> discover </OPTION>

9</INPUT>

10<ACK CONFIRM="YORN" REPROMPT="Y">

11I thought you said <VALUE NAME="type"/>

12<BREAK/> Is that correct?

13</ACK>

14</STEP>

In this rather complex example, the ACK element is used to confirm the user's choice of credit card. When this code is interpreted by the VoxML voice browser, it will speak the text of the PROMPT element using text-to-speech technology, wait until the user responds with ???visa???, ???mastercard???, or ???discover???, and then ask the user to confirm the type of card was recognized correctly.

If the user answers ???yes??? to the ACK, the browser will proceed to the STEP named ???exp???. If the user answers ???no??? to the ACK, the text of the PROMPT will be read again, and the user will be allowed to make his or her choice again

??? the browser re-enters the STEP as if for the first time.

VoxML 1.0 Element Reference

AUDIO Element

The AUDIO element specifies an audio file that should be played. AUDIO elements can be used as an alternative anywhere that you would read text to the user.

An AUDIO element can be contained within a PROMPT, EMP, PROS, HELP,

ERROR, CANCEL, or ACK element.

Syntax

Attributes

Examples

1<PROMPT>

2At the tone, the time will be 11:59 p m

3<AUDIO SRC="http://localhost/sounds/beep.wav"/>

4</PROMPT>

The above code is a simple example of an audio sample included in a PROMPT element. When interpreted by the VoxML Voice Browser, this code will speak the text from line 2 using text-to-speech technology, and then play the WAV file ???beep.wav??? as specified by the AUDIO element on line 3.

For a description of the audio formats supported by the voice browser, see the release notes for the VoxML SDK.

VoxML 1.0 Element Reference

BREAK Element

The BREAK element is used to insert a pause into content to be presented to the user. BREAK elements can be used anywhere that you would read text to or play audio samples for the user.

The BREAK element can be contained within a PROMPT, EMP, PROS, HELP,

ERROR, CANCEL, or ACK element.

Syntax

Attributes

Examples

1<PROMPT>

2Welcome to Earth. <BREAK MSECS="250"/>

3How may I help you?

4</PROMPT>

The code shown above illustrates the use of the BREAK element with the MSECS attribute, inside a PROMPT. When interpreted by the VoxML voice browser, this code would speak the text ???Welcome to Myosphere.???, pause for 250 milliseconds, and then speak the text ???How may I help you????.

1<PROMPT>

2Welcome to Earth. <BREAK SIZE="medium"/>

3How may I help you?

4</PROMPT>

As an alternative to specifying an exact number of milliseconds, an application developer can use the SIZE attribute of the BREAK element to control the duration of the pause.

The actual duration of ???small???, ???medium???, and ???large??? are system defined, and may change. Use the MSECS attribute if a specific duration is required.

VoxML 1.0 Element Reference

CANCEL Element

The CANCEL element enables the application developer to define the behavior of the VoxML application in response to a user???s request to cancel the current PROMPT. If the application developer does not define the behavior of CANCEL for a given STEP, the system default behavior will be used.

The default behavior for the CANCEL element is to stop the PROMPT, and then process any interactive INPUTs.

The CANCEL element, like the HELP element, can be invoked through a variety of phrases. The user may say only the word ???cancel???, or the user may say ???I would like to cancel, please.??? In either case, the CANCEL element will be interpreted.

The CANCEL element can be contained within a STEP or a CLASS element.

Syntax

Attributes

VoxML 1.0 Element Reference

CANCEL Element

Examples

1<STEP NAME="report">

2<CANCEL NEXT="#traffic_menu"/>

3<PROMPT> Traffic conditions for Chicago,

4Illinois, Monday, May 18. Heavy

5congestion on ... </PROMPT>

7<INPUT TYPE="optionlist">

8<OPTION NEXT="#report"> repeat </OPTION>

9<OPTION NEXT="#choose"> new city </OPTION>

10</INPUT>

11</STEP>

The code on line 2 illustrates the use of the CANCEL element to specify that when the user says ???cancel???, the browser should proceed to the STEP named ???traffic_menu???, instead of the default behavior, which would be to simply stop the PROMPT from playing and wait for a user response. Users can also interrupt the PROMPT by speaking valid OPTION. In this example, the user could interrupt the PROMPT and get the traffic conditions for a different city by saying ???new city???.

VoxML 1.0 Element Reference

CASE Element

The CASE element is used to define the flow of control of the application, based on the values of internal VoxML variables.

The CASE element can be contained by a SWITCH element, or by an INPUT element, when using an INPUT type that collects a single value (i.e. DATE, DIGITS, MONEY, PHONE, TIME, YORN).

Syntax

Attributes

Examples

1 <SWITCH FIELD="pizza">

2<CASE VALUE="pepperoni" NEXT="#p_pizza"/>

3<CASE VALUE="sausage" NEXT="#s_pizza"/>

4<CASE VALUE="veggie" NEXT="#v_pizza"/>

5</SWITCH>

The code on lines 2-4 shows the use of the CASE element within the SWITCH element. In this example, the CASE elements are used to direct the browser to different URLs based on the value of the VoxML variable ???pizza???.

VoxML 1.0 Element Reference

CLASS Element

The CLASS element defines a set of elements that are to be reused within the context of a DIALOG. The definitions of a given CLASS may be inherited by STEPs or other CLASSs. The CLASS element allows the application developer to define a set of elements once, and then use them several times. The CLASS element is often used to define the default behavior of ERROR, HELP, and CANCEL, within a given DIALOG.

The CLASS element can be contained by a DIALOG element only.

Syntax

<CLASS NAME="value" [PARENT="value"] [BARGEIN="value"] [COST="value"] > VoxML </CLASS>

Attributes

* The COST attribute is a platform-dependent feature. A given browser implementation may or may not support each platform-dependent feature.

VoxML 1.0 Element Reference

CLASS Element

Examples

1<CLASS NAME="simple">

2<HELP> Your choices are <OPTIONS/> </HELP>

3<ERROR> I did not understand what you said.

4Valid responses are <OPTIONS/> </ERROR>

5</CLASS>

7<STEP NAME="beverage" PARENT="simple">

8<PROMPT> Please choose a drink. </PROMPT>

9<INPUT NAME="drink" TYPE="optionlist">

10<OPTION NEXT="#food"> coke </OPTION>

11<OPTION NEXT="#food"> pepsi </OPTION>

12</INPUT>

13</STEP>

15 <STEP NAME="food" PARENT="simple">

16<PROMPT> Please choose a meal. </PROMPT>

17<INPUT NAME="meal" TYPE="optionlist">

18<OPTION NEXT="#deliver"> pizza </OPTION>

19<OPTION NEXT="#deliver"> tacos </OPTION>

20</INPUT>

21</STEP>

The code shown on lines 1-5 illustrates the use of the CLASS element to define a HELP element and an ERROR element that will be used in several STEPs within this DIALOG.

The code on lines 7 and 15 illustrates the use of the PARENT attribute on the STEP element to refer to the CLASS element, and therefore inherit the behaviors defined within it.

When interpreted by the VoxML voice browser, the STEPs defined on lines 7- 13 and lines 15-21 will behave as if the HELP and ERROR elements that are defined in the CLASS were defined explicitly in the STEPs themselves.

VoxML 1.0 Element Reference

DIALOG Element

The DIALOG element is the fundamental element of VoxML. If one were to imagine a VoxML document as a tree, the DIALOG element would be the root of the tree. The DIALOG element defines the basic unit of context within a VoxML application, and in the common case, there is one DIALOG element per URL.

Each VoxML DIALOG must contain exactly one STEP element named ???init???.

The execution of the VoxML application begins with the STEP named ???init???.

A DIALOG element cannot be contained by any VoxML element.

Syntax

<DIALOG [BARGEIN="value"] > VoxML </DIALOG>

Attributes

Examples

1<DIALOG>

2<STEP NAME="init">

3<PROMPT> Welcome to VoxML. </PROMPT>

4</STEP>

5</DIALOG>

The above code shows a simple, yet complete VoxML DIALOG. The DIALOG element is specified on lines 1 and 5 and contains a single STEP element named ???init???. The STEP has a single PROMPT that will be read via text-to-speech.

Since there is no INPUT defined in this STEP, the VoxML application will terminate immediately after the PROMPT is read.

VoxML 1.0 Element Reference

EMP Element

The EMP element is used to identify a context within text that will be read to the user where emphasis is to be applied. The EMP element can be used anywhere that text is read to the user.

The EMP element can be contained within a PROMPT, EMP, PROS, HELP,

ERROR, CANCEL, or ACK element.

Syntax

Attributes

Examples

1<PROMPT>

2This example is

3<EMP LEVEL="strong"> really </EMP>

4simple.

5</PROMPT>

The above code illustrates the use of the EMP element to apply ???strong??? emphasis to the word ???really??? in a simple prompt.

The actual effect on the speech output is determined by the text-to-speech (TTS) software used by the voice browser. Since the desktop simulator uses different TTS software than the voice browser in the highly-scalable network system, the output may vary. To achieve a specific emphatic effect, use the PROS element instead of the EMP element.

VoxML 1.0 Element Reference

ERROR Element

The ERROR element enables the application developer to define the behavior of the VoxML application in response to an error. If the application developer does not define the behavior of ERROR for a given STEP, the default behavior will be used.

The default behavior for the ERROR element is to speak the phrase ???An error has occurred.???, remain in the current STEP, replay the PROMPT, and wait for the user to respond.

The ERROR element can be contained within a STEP or a CLASS element.

Syntax

Attributes

VoxML 1.0 Element Reference

ERROR Element

Examples

1<STEP NAME="errors">

2<ERROR TYPE="nomatch"> First error message.

3I did not understand what you said. </ERROR>

4<ERROR TYPE="nomatch" ORDINAL="2">

5Second error message.

6I did not understand what you said. </ERROR>

7<PROMPT> This step tests error messages.

8Say 'oops' twice. Then say 'done' to

9choose another test. </PROMPT>

10<INPUT TYPE="OPTIONLIST">

11<OPTION NEXT="#end"> done </OPTION>

12</INPUT>

13</STEP>

The code shown above illustrates the use of the ERROR element to define the application's behavior in response to an error. On line 2, we define the error message to be used the first time an error of type ???nomatch??? occurs in this STEP. On line 4, we define the error message to be used the second and all subsequent times an error of type "nomatch" occurs in this STEP.

The ORDINAL attribute determines which message will be used in the case of repeated errors within the same STEP. The VoxML voice browser will choose an error message based on this simple algorithm: If the error has occurred 3 times, the browser will look for an ERROR element with ORDINAL of ???3???. If no such ERROR element has been defined, the voice browser will look for an ERROR with ORDINAL of ???2???, and then ???1???, and then an ERROR with no ORDINAL defined.

So, if we had defined an ERROR element with ORDINAL of ???6??? in the STEP shown above, and the same error occurred 6 times in a row, the user would hear the first error message one time, then the second error message 4 times, and finally the error message with ORDINAL of ???6???.

VoxML 1.0 Element Reference

HELP Element

The HELP enables the application developer to define the behavior of the VoxML application when the user asks for help. If the application developer does not define the behavior of HELP for a given STEP, the system default behavior will be used.

The HELP element, like CANCEL the element, can be invoked through a variety of phrases. The user may say only the word ???help???, or the user may say ???I would like help, please.??? In either case, the HELP element will be interpreted.

The default behavior for the HELP element is to stop the PROMPT (if one is playing), speak the phrase ???No help is available.???, remain in the current STEP, and process any interactive INPUTs.

The HELP element can be contained within a STEP or a CLASS element.

Syntax

Attributes

VoxML 1.0 Element Reference

HELP Element

Examples

1<STEP NAME="helps">

2<HELP REPROMPT="Y"> First help message.

3You should hear the prompt again. </HELP>

4<HELP ORDINAL="2"> Second help message.

5You should not hear the prompt now. </HELP>

6<PROMPT> This step tests help prompts.

7Say 'help' twice. Then say 'done' to

8choose another test. </PROMPT>

9<INPUT TYPE="OPTIONLIST">

10<OPTION NEXT="#end"> done </OPTION>

11</INPUT>

12</STEP>

The code shown above illustrates the use of the HELP element to define the application's behavior in response to the user input ???help???. On line 2, we define the help message to be used the first time the user says ???help???. On line 4, we define the help message to be used the second and all subsequent times the user says ???help???. It should also be noted that through the use of the REPROMPT attribute, the prompt will be repeated after the first help message, but it will not be repeated after the second help message.

The ORDINAL attribute determines which message will be used in the case of repeated utterances of ???help??? within the same STEP element. The VoxML voice browser will choose a help message based on this simple algorithm: If the user has said ???help??? 3 times, the browser will look for a HELP element with ORDINAL of ???3???. If no such HELP element has been defined, the voice browser will look for a HELP with ORDINAL of ???2???, and then ???1???, and then a HELP with no ORDINAL defined.

So, if we had defined a HELP element with ORDINAL of ???6??? in the STEP shown above, and the user said ???help??? 6 times in a row, the user would hear the first help message one time, then the second help message 4 times, and finally the help message with ORDINAL of ???6???.

VoxML 1.0 Element Reference

INPUT Element

The INPUT element is used to define the valid user input within each STEP. The application developer can define the type of input as well as specific values that are to be recognized.

The INPUT element can exist only within a STEP element.

Syntax

Because the syntax of the different types of INPUTs vary widely, each of the types of INPUT elements will be described in its own section.

Attributes

Examples

For examples, please reference the section that describes the type of INPUT that you would like to use.

VoxML 1.0 Element Reference

INPUT Element : Type DATE

The DATE input is used to collect a calendar date from the user.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> What is your date of birth? </PROMPT>

3<INPUT TYPE="date" NAME="dob" NEXT="#soc"/>

4</STEP>

The code on line 3 illustrates the use of the DATE INPUT to gather the user's birthday, store it in the VoxML variable ???dob???, and then go to the STEP named ???soc???.

Data Format

The DATE input makes use of an input grammar to interpret the user???s response and store that response in a standard format. The DATE input grammar can interpret dates expressed in several different formats.

The response ???July 4th???, is stored as ???????????|July|4|||???, ???Tomorrow??? becomes ???????????|||||tomorrow???, ???The 15th??? is stored as ???????????||15|||???, and ???Monday??? becomes ???????????||||Monday|???.

VoxML 1.0 Element Reference

INPUT Element : Type DIGITS

The DIGITS input is used to collect a series of digits from the user.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> Please say your pin now. </PROMPT>

3<INPUT TYPE="digits" NAME="pin" NEXT="#doit"/>

4</STEP>

The code on line 3 illustrates the use of the DIGITS INPUT to collect digits from the user, store the number in the VoxML variable named ???pin???, and then go to the STEP named ???doit???.

If the user were to say, ???four five six???, in response to the PROMPT shown on line 2, the value ???456??? would be stored in the VoxML variable ???pin???. The DIGITS input type will collect the digits 0 (i.e. zero) through 9 (i.e. nine), but not other numbers like 20 (i.e. twenty). To collect numbers like 20 (i.e. twenty) or 400 (i.e. four hundred), use the NUMBER input type.

VoxML 1.0 Element Reference

INPUT Element : Type GRAMMAR

The GRAMMAR input is used to specify an input grammar that is to be used when interpreting the user's responses.

Syntax

<INPUT TYPE="GRAMMAR" SRC="value" NEXT="value" [NEXTMETHOD="value"] [TIMEOUT="value"] > RENAME elements </INPUT>

<INPUT TYPE="GRAMMAR" SRC="value" [TIMEOUT="value"] [NEXT="value" [NEXTMETHOD="value"] ] > RESPONSE elements </INPUT>

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> Say the month and year in which the

3credit card expires. </PROMPT>

4<INPUT TYPE="GRAMMAR"

5SRC="gram://.SomeGrammar/month/year"

6NEXT="#stepNineteen"/>

7</STEP>

The code on lines 4, 5, and 6 illustrates the use of the GRAMMAR INPUT to collect a month and year from the user, store the interpreted values in variables named ???month??? and ???year???, and then go to the step named ???stepNineteen???.

VoxML 1.0 Element Reference

INPUT Element : Type HIDDEN

The HIDDEN input is used to store a value in a VoxML variable.

Syntax

Attributes

Examples

1<STEP NAME="init">

2<PROMPT> Login sequence complete.

3Are you ready to place your order?

4</PROMPT>

5<INPUT TYPE="hidden" NAME="firstname"

6VALUE="Bill"/>

7<INPUT TYPE="hidden" NAME="lastname"

8VALUE="Clinton"/>

9<INPUT TYPE="hidden" NAME="favorite"

10VALUE="fries"/>

11<INPUT TYPE="optionlist">

12<OPTION NEXT="#order"> yes </OPTION>

13<OPTION NEXT="#wait"> not yet </OPTION>

14</INPUT>

15</STEP>

In the example code shown above, the HIDDEN INPUT type is used to create VoxML variables and assign values to those variables. In this particular example, the user has completed the login sequence and the application designer chose to save certain information in VoxML variables as soon as the user's identity has been established. This information could then be used later in the application without requiring another access into the database.

Notice that when using the HIDDEN INPUT that it is permissable to have more than one INPUT element in the same STEP. This is because the HIDDEN INPUT is not an interactive INPUT. Each STEP can contain only one INPUT that accepts a response from the user.

VoxML 1.0 Element Reference

INPUT Element : Type MONEY

The MONEY input is used to collect monetary amounts from the user.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> How much would you like to deposit?

3</PROMPT>

4<INPUT TYPE="money" NAME="dep" NEXT="#deposit"/>

5</STEP>

The above example code illustrates the use of the MONEY input type to collect the amount of money that the user would like to deposit in his account, store that amount in a VoxML variable named ???dep???, and then go to the STEP named ???deposit???.

Data Format

The MONEY input makes use of an input grammar to interpret the user???s response and store that response in a standard format. The input grammar is able to interpret several ways to express monetary amounts.

The data is stored in integer format, in terms of cents.

???five cents??? is stored as ???5???, ???five dollars??? is stored as ???500???, and ???a thousand??? is stored as ???100000???. Note that no punctuation is added to the digits. Also note that in the case where the units are ambiguous, the grammar assumes dollars, as in the example above in which ???a thousand??? was stored as if the user had said ???a thousand dollars???.

VoxML 1.0 Element Reference

INPUT Element : Type NONE

Input type NONE is used to specify the next location for the voice browser to go to continue execution when no response is collected from the user.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> Welcome to the system. </PROMPT>

3<INPUT TYPE="none" NEXT="#mainmenu"/>

4</STEP>

The code shown above illustrates the use of the NONE input type to jump to another STEP in this dialog without waiting for any user response. In this example, the user would here the phrase ???Welcome to the system??? followed immediately by the prompt of the main menu.

VoxML 1.0 Element Reference

INPUT Element : Type NUMBER

The NUMBER input is used to collect numbers from the user.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> Please say your age now. </PROMPT>

3<INPUT TYPE="number" NAME="age" NEXT="#doit"/>

4</STEP>

The code on line 3 illustrates the use of the NUMBER INPUT to collect numbers from the user, store the number in the VoxML variable named ???age???, and then go to the STEP named ???doit???.

If the user were to say, ???eighteen???, in response to the PROMPT shown on line 2, the value ???18??? would be stored in the VoxML variable ???age???. The NUMBER input type will collect numbers like 20 (i.e. twenty), only one number per input. To collect a series of digits like ???four five six??? (i.e. ???456???), use the DIGITS input type.

VoxML 1.0 Element Reference

INPUT Element : Type OPTIONLIST

The OPTIONLIST input is used to specify a list of options from which the user can select. This input type is used in conjunction with the OPTION element, which defines the specific user responses and the behavior associated with each.

Syntax

<INPUT TYPE="OPTIONLIST" [NAME="value"] [TIMEOUT="value"] [NEXT="value" [NEXTMETHOD="value"] ] > OPTION elements </INPUT>

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> What would you like to drink? </PROMPT>

3<INPUT TYPE="optionlist">

4<OPTION NEXT="#coke"> coke </OPTION>

5<OPTION NEXT="#coke"> coca-cola </OPTION>

6<OPTION NEXT="#pepsi"> pepsi </OPTION>

7<OPTION NEXT="#rc"> r c </OPTION

8</INPUT>

9</STEP>

In this simple example, the VoxML voice browser will go to a different STEP depending on which cola the user selects. As defined on lines 4 and 5, if the user said ???coke??? or ???coca-cola???, the voice browser would go to the STEP named ???coke???.

VoxML 1.0 Element Reference

INPUT Element : Type PHONE

The PHONE input is used to collect telephone numbers from the user.

Syntax

Attributes

Examples

1 <STEP NAME="phone">

2<PROMPT> What is your phone number? </PROMPT>

3<INPUT TYPE="phone" NAME="ph" NEXT="#fax"/>

4</STEP>

In this simple example, the code on line 3 illustrates the use of the PHONE input type to collect a telephone number from the user, store the number in the VoxML variable named ???ph???, and go to the STEP named ???fax???.

Data Format

The PHONE input makes use of an input grammar to interpret the user???s response and store that response in a standard format. The phone number is interpreted as a string of digits, and stored in the VoxML variable as such.

If a user said ???One, eight zero zero, seven five nine, eight eight eight eight???, the response would be stored as ???18007598888???. Note that there is no punctuation added to the digits.

VoxML 1.0 Element Reference

INPUT Element : Type PROFILE???

The PROFILE input is used to collect the user's profile information (e.g. home address) from the voice browser directly. This INPUT type is different from the others in that the input does not come from the interactive user, but instead is provided by the voice browser itself, using information from the system???s subscriber database. (The user???s information is provided by each subscriber when the account is activated.)

Syntax

Attributes

* For information on valid profile names and subtypes, see Appendix B.

Examples

1 <STEP NAME="getinfo">

2<INPUT TYPE="profile" NAME="firstname"

3PROFNAME="N" SUBTYPE="first"/>

4<PROMPT> Hello, <VALUE NAME="firstname"/>.

5Please say your pin. </PROMPT>

6<INPUT TYPE="digits" NAME="pin" NEXT="#verify"/>

7</STEP>

In the code on lines 2 and 3, the PROFILE input is used to retrieve the user's first name and store the string in the VoxML variable named ???firstname???. The string containing the name is then inserted into the PROMPT on line 4 using the VALUE element.

Notice that when using the PROFILE INPUT that it is permissable to have more than one INPUT element in the same STEP. This is because the PROFILE INPUT is not an interactive INPUT. Each STEP can contain only one INPUT that accepts a response from the user.

??? The PROFILE input type is a platform-dependent feature.

October 1998VoxML 1.0 Language Reference 30

VoxML 1.0 Element Reference

INPUT Element : Type RECORD

The RECORD input type is used to record an audio sample and to store that sample in a location specified by the application developer.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> Please say your first and last name.

3</PROMPT>

4<INPUT TYPE="record" TIMEOUT="7000"

5NAME="theName" STORAGE="REQUEST"

6NEXT="http://wavhost/acceptwav.asp"

7NEXTMETHOD="POST"/>

8</STEP>

In this example, the RECORD input type is used to record a 7 second audio sample, and then ???POST??? that sample to the remote machine named ???wavhost???. The response to the ???POST??? must be a VoxML DIALOG which continues the execution of the application.

Note that nothing is stored in the VoxML variable named ???theName???; the recorded audio is sent to the remote machine instead.

VoxML 1.0 Element Reference

INPUT Element : Type RECORD

1 <STEP NAME="init">

2<PROMPT> Please say your first and last name.

3</PROMPT>

4<INPUT TYPE="record" TIMEOUT="7000"

5NAME="theName" STORAGE="FILE"

6NEXT="#reccomplete" NEXTMETHOD="GET"/>

7</STEP>

In this example, the RECORD input type is used to record a another 7 second audio sample, but this time the sample is stored in a file, instead of sent in the HTTP request as it was in the earlier example. The name of the file is chosen by the voice browser automatically and is stored in the VoxML variable named ???theName???. After storing the audio sample in the file, the voice browser will continue execution at the URL specified by the NEXT attribute.

Note that in contrast to the earlier example, the value of the VoxML variable ???theName??? will be the name of the audio file. In the earlier example (where the audio sample was transmitted via the HTTP request), the value of the VoxML variable ???theName??? would be null.

VoxML 1.0 Element Reference

INPUT Element : Type TIME

The TIME input type is used to collect a time of day from the user.

Syntax

Attributes

Examples

1 <STEP NAME="init">

2<PROMPT> What time would you like your wakeup

3call? </PROMPT>

4<INPUT TYPE="time" NAME="wakeup" NEXT="#record"/>

6</STEP>

This example makes use of the TIME input type to collect a time of day from the user, store that data in the VoxML variable named ???wakeup???, and then go to the STEP named ???record???.

Data Format

The TIME input makes use of an input grammar to interpret the user???s response and store that response in a standard format. This grammar will interpret responses of various forms, including both 12-hour and 24-hour conventions.

???Four o???clock??? is stored as ???400???. Since the user was not specific as to the morning or evening, no indication is stored in the VoxML variable.

???Four oh three PM??? becomes ???403P???. Note the ???P??? appended to the time. Likewise, ???Ten fifteen in the morning??? becomes ???1015A???. Note the ???A???. ???Noon??? is stored as ???1200P???, and ???Midnight??? is stored as ???1200A???. Military time, such as, ???Thirteen hundred hours??? becomes ???100P???.

VoxML 1.0 Element Reference

INPUT Element : Type YORN

The YORN input is used to collect ???yes or no??? responses from the user. This input maps a variety of affirmative and negative responses to the values ???Y??? and ???N???, simplifying the work of the application developer in interpreting this type of user response.

Syntax

<INPUT TYPE="YORN" [NAME="value"] [TIMEOUT="value"] [NEXT="value" [NEXTMETHOD="value"] ] > CASE elements </INPUT>

Attributes

Examples

1 <STEP NAME="ask">

2<PROMPT> Fire the missles now? </PROMPT>

3<INPUT TYPE="YORN" NAME="fire" NEXT="#confirm"/>

4</STEP>

In this example, we use the YORN input type to collect a ???yes or no??? response from the user, store that response into the VoxML variable named ???fire???, and then go to the STEP named ???confirm???.

The YORN input type stores the value ???Y??? for affirmative responses and the value ???N??? for negative responses. Affirmative and negative responses are determined using an input grammar that maps various user responses to the appropriate result.

VoxML 1.0 Element Reference

OPTION Element

The OPTION element is used to define the application behavior associated with a specific user response.

The OPTION element can exist only within the INPUT element, and then only when using the OPTIONLIST input type.

Syntax

Attributes

Examples

1 <INPUT NAME="choice" TYPE="optionlist">

2<OPTION NEXT="#doit" VALUE="1"> one </OPTION>

3<OPTION NEXT="#doit" VALUE="2"> two </OPTION>

4</INPUT>

The code on lines 2 and 3 illustrate the use of the OPTION element within the INPUT element. In this example, the OPTION on line 2 would be executed when the user responded with ???one???, and the OPTION on line 3 would be executed when the user responded with ???two???. If the user said ???one??? the result would be that the value of the variable named ???choice??? would be ???1???, because of the use of the VALUE attribute. Because the NEXT attributes for both of the OPTIONs in this OPTIONLIST are the same, the VoxML voice browser would proceed to the STEP named ???doit??? when either ???one??? or ???two??? was recognized.

VoxML 1.0 Element Reference

OPTION Element

1 <INPUT TYPE="optionlist">

2<OPTION NEXT="http://localhost/vml/weather.asp">

3weather </OPTION>

4<OPTION NEXT="http://localhost/vml/news.asp">

5news </OPTION>

6<OPTION NEXT="http://localhost/vml/traffic.asp">

7traffic </OPTION>

8</INPUT>

The code shown above illustrates the use of the OPTION element to select one of three VoxML applications. Note that the URLs used in the NEXT attributes are full HTTP URLs, and that unlike the previous example, each OPTION has a unique NEXT attribute.

VoxML 1.0 Element Reference

OPTIONS Element

The OPTIONS element describes the type of input expected within a given STEP element. The OPTIONS element is typically used in HELP elements to present the user with a complete list of valid responses. The OPTIONS element can be used anywhere that text is read to the user.

The OPTIONS element can be contained by a PROMPT, EMP, PROS, HELP,

ERROR, or ACK element.

Syntax

Attributes

The OPTIONS element has no attributes.

Examples

1 <CLASS NAME="helpful">

2<HELP> Your choices are: <OPTIONS/> </HELP>

3</CLASS>

This example illustrates how the OPTIONS element can be used to construct a ???helpful??? CLASS. Any STEPs that directly or indirectly name ???helpful??? as a PARENT respond to ???help??? by speaking the message, in which the OPTIONS element expands to a description of what can be said at this point in the dialog.

VoxML 1.0 Element Reference

OR Element

The OR element is used to define alternate recognition results in an OPTION element. The OR element is interpreted as a logical or, and is used to associate multiple recognition results with a single NEXT attribute.

The OR element can exist only within the OPTION element.

Syntax

<OR/>

Attributes

The OR element has no attributes.

Examples

1<INPUT TYPE="optionlist">

2<OPTION NEXT="#coke_chosen">

3coke <OR/> coca-cola

4</OPTION>

5<OPTION NEXT="#pepsi_chosen"> pepsi </OPTION>

6</INPUT>

The code shown above illustrates the use of the OR element within an OPTION element. As you can see on line 3, the user may respond with either ???coke??? or ???coca-cola???, and the effect is the same ??? the voice browser will proceed to the STEP named ???coke_chosen???.

VoxML 1.0 Element Reference

PROMPT Element

The PROMPT element is used to define content (text or an audio file) that is to be presented to the user. Typically, the PROMPT element will contain text and several markup elements, like the BREAK or EMP element, that are read to the user via text-to-speech technology.

The PROMPT element can be contained within a STEP or a CLASS element.

Syntax

Attributes

The PROMPT element has no attributes.

Examples

1 <STEP NAME="init">

2<PROMPT> How old are you? </PROMPT>

3<INPUT TYPE="number" NAME="age" NEXT="#weight"/>

4</STEP>

In this simple example, the text ???How old are you???? will be spoken via text-to- speech technology, and then the application will wait for the user to say his age. The PROMPT element on line 2 defines what will be presented to the user.

VoxML 1.0 Element Reference

PROS Element

The PROS element is used to control the prosody of the content presented to the user via PROMPT, HELP, ERROR, CANCEL, and ACK elements. Prosody affects certain qualities of the text-to-speech presentation, including rate of speech, pitch, range, and volume.

The PROS element can be contained within a PROMPT, EMP, PROS, HELP,

ERROR, CANCEL, or ACK element.

Syntax

Attributes

Examples

1 <PROMPT> Let me tell you a secret:

2<PROS VOL="0.5"> I ate the apple. </PROS>

3</PROMPT>

In this example, the phrase ???I ate the apple.??? is spoken with one half of the normal volume.

VoxML 1.0 Element Reference

RENAME Element

The RENAME element is used to rename recognition slots in VoxML grammars, such that the resulting VoxML variable name can be different from the name of the recognition slot defined in the grammar.

The RENAME element can exist only within the INPUT element, and then only when using the GRAMMAR input type.

Syntax

Attributes

Examples

1 <INPUT TYPE="GRAMMAR"

2SRC="http://www.foo.com/mygram.grm"

3NEXT="http://www.fancyquotes.com/vmlstocks.asp">

4<RENAME VARNAME="sym" RECNAME="symbol">

5<RENAME VARNAME="detail" RECNAME="quotetype">

6</INPUT>

In this example, the RENAME element is used to account for differences in the variable names collected from a grammar and those expected by another script. In particular, the case imagined here is one where a grammar from foo.com is used to provide input to a VoxML application hosted by fancyquotes.com. Because the grammar and script are imagined to have been developed independently, the RENAME element is used to help connect the grammar and the stock-quoting application.

VoxML 1.0 Element Reference

RESPONSE Element

The RESPONSE element is used to define the behavior of the VoxML application in response to different combinations of recognition slots. The RESPONSE element enables the application developer to define a different NEXT attribute depending on which of the grammar's slots were filled.

The RESPONSE element can exist only within an INPUT element, and then only when using an input type of GRAMMAR.

Syntax

SWITCH elements </RESPONSE>

Attributes

VoxML 1.0 Element Reference

RESPONSE Element

Examples

1 <INPUT TYPE="GRAMMAR"

2SRC="gram://.Banking/action/amt/fromacct/toacct"

3NEXT="#notenoughfields">

4<RESPONSE FIELDS="action,amt,fromacct,toacct"

5NEXT="#doit"/>

6<RESPONSE FIELDS="action,amt,fromacct"

7NEXT="#asktoacct"/>

8<RESPONSE FIELDS="action,amt,toacct"

9NEXT="#askfromacct"/>

10<RESPONSE FIELDS="action,amt" NEXT="#askaccts"/>

11<RESPONSE FIELDS="action" NEXT="#askamtaccts"/>

12</INPUT>

This example illustrates how the RESPONSE element can be used to deal with situations where the user specifies less than all the possible variables available in the grammar. Using the RESPONSE element, the application can arrange to collect only the information not already filled in by prior steps.

In particular this example transfers to the ???askaccts??? STEP if neither the source nor destination account is specified (for example, the user said ???transfer 500 dollars???), but it transfers to the ???askfromacct??? STEP if the user said what account to transfer to, but did not specify a source account (for example, if the user had said ???transfer 100 dollars to savings???).

The NEXT URL on the INPUT element is used when the user???s response does not match any of the defined RESPONSEs.

VoxML 1.0 Element Reference

STEP Element

The STEP element defines a state in a VoxML application. A STEP element typically has an associated PROMPT element and INPUT element that minimally define the application state.

Each VoxML DIALOG must contain exactly one STEP element named ???init???.

The execution of the VoxML application begins with the STEP named ???init???.

The STEP element can be contained by a DIALOG element only.

Syntax

<STEP NAME="value" [PARENT="value"] [BARGEIN="value"] [COST="value"] > VoxML </STEP>

Attributes

Examples

1 <STEP NAME="askpython" PARENT="tvrating">

2<PROMPT> Please rate Monty Python's Flying Circus

3on a scale of 1 to 10. </PROMPT>

4<INPUT NAME="python" TYPE="number" NEXT="#drwho" />

5</STEP>

This example illustrates a simple STEP that collects the user???s opinion on one of several public television shows. The step uses the PARENT attribute to share a common set of help and error elements with other TV-show-rating STEPs. For example, the parent class might contain a help element explaining what a rating of 1, 5, and 10 would mean; a common error message might remind the user that a numeric rating is expected.

??? The COST attribute is a platform-dependent feature.

October 1998VoxML 1.0 Language Reference 44

VoxML 1.0 Element Reference

SWITCH Element

The SWITCH element is used to define the application behavior dependant on the value of a specified recognition slot. The SWITCH element is used only in conjunction with the CASE element.

The SWITCH element can exist only within the INPUT element, and then only when using the GRAMMAR input type.

Syntax

<SWITCH FIELD="value"> VoxML </SWITCH>

Attributes

Examples

1<INPUT TYPE="GRAMMAR"

2SRC="gram://.Banking/action/amount/fromacct/toacct">

3<SWITCH FIELD="action">

4<CASE VALUE="transfer" NEXT="#transfer" />

5<CASE VALUE="balance" NEXT="#balance" />

6<CASE VALUE="activity">

7<SWITCH FIELD="fromacct">

8<CASE VALUE="checking" NEXT="#chxact" />

9<CASE VALUE="savings" NEXT="#savact" />

10</SWITCH>

11</CASE>

12</SWITCH>

13</INPUT>

This example shows how a SWITCH element might be used to determine the next step to execute in response to a banking request. In this example, the grammar may fill in some or all of the variables ???action???, ???amount???, ???fromacct???, and ???toacct???. If the user asks for a transfer or balance action, the next step to execute is the transfer or balance step. If the user asks for a report of account activity, a second SWITCH element determines the next step based on the account type for which a report is being requested (assumed to be available in the ???fromacct??? variable).

VoxML 1.0 Element Reference

VALUE Element

The VALUE element is used to present the value of a VoxML variable to the user via text-to-speech. The VALUE element can be used anywhere that text is read to the user.

The VALUE element can be contained by a PROMPT, EMP, PROS, HELP,

ERROR, CANCEL, or ACK element.

Syntax

Attributes

Examples

1 <STEP NAME="thanks">

2<PROMPT> Thanks for your responses. I'll record

3that <VALUE NAME="first"/> is your favorite

4and that <VALUE NAME="second"/> is your

5second choice.

6</PROMPT>

7<INPUT TYPE="NONE" NEXT="/recordresults.asp" />

8</STEP>

The VoxML code shown above illustrates the use of the VALUE element to read the user???s selections back to the user. On line 3, the value of the VoxML variable named ???first??? would be inserted into the PROMPT, and on line 4 the value of the VoxML variable named ???second??? would be inserted into the

PROMPT.

Appendices

Appendix A - VoxML 1.0 Document Type Definition

3. Appendices

Appendix A - VoxML 1.0 Document Type Definition

This appendix describes the VoxML 1.0 Document Type Definition. A DTD is used to define the syntax and grammar of a language in a way that can be read and understood by humans as well as machines (i.e. parsers).

<!ELEMENT DIALOG (STEP|CLASS)*> <!ATTLIST DIALOG BARGEIN (Y|N) "Y">

<!ATTLIST STEP NAME ID #REQUIRED

PARENT IDREF #IMPLIED BARGEIN (Y|N) "Y"

COST CDATA #IMPLIED>

<!ELEMENT CLASS (PROMPT|HELP|ERROR|CANCEL|ACK)*>

<!ATTLIST CLASS NAME ID #REQUIRED

PARENT IDREF #IMPLIED BARGEIN (Y|N) "Y"

COST CDATA #IMPLIED>

<!ATTLIST EMP LEVEL (STRONG|MODERATE|NONE|REDUCED) "MODERATE">

<!ATTLIST PROS RATE CDATA #IMPLIED

VOL CDATA #IMPLIED

PITCH CDATA #IMPLIED

RANGE CDATA #IMPLIED>

<!ATTLIST HELP ORDINAL CDATA #IMPLIED REPROMPT (Y|N) "N"

NEXT CDATA #IMPLIED NEXTMETHOD (GET|POST) "GET">

<!ATTLIST ERROR TYPE NMTOKENS "ALL"

ORDINAL CDATA #IMPLIED REPROMPT (Y|N) "N"

NEXT CDATA #IMPLIED NEXTMETHOD (GET|POST) "GET">

<!ATTLIST CANCEL NEXT CDATA #REQUIRED NEXTMETHOD (GET|POST) "GET">

Appendices

Appendix A - VoxML 1.0 Document Type Definition

<!ELEMENT AUDIO EMPTY>

<!ATTLIST AUDIO SRC CDATA #REQUIRED>

<!ATTLIST ACK CONFIRM NMTOKEN "YORN" BACKGROUND (Y|N) "N" REPROMPT (Y|N) "N">

<!ELEMENT INPUT (OPTION|RESPONSE|RENAME|SWITCH|CASE)*>

NAME ID #IMPLIED

NEXT CDATA #IMPLIED NEXTMETHOD (GET|POST) "GET"

TIMEOUT CDATA #IMPLIED

MIN CDATA #IMPLIED

MAX CDATA #IMPLIED

PROFNAME NMTOKEN #IMPLIED

SUBTYPE NMTOKEN #IMPLIED

SRC CDATA #IMPLIED

VALUE CDATA #IMPLIED

MSECS CDATA #IMPLIED

STORAGE (FILE|REQUEST) #REQUIRED

FORMAT CDATA #IMPLIED>

<!ELEMENT SWITCH (CASE|SWITCH)*>

<!ATTLIST SWITCH FIELD NMTOKEN #REQUIRED>

<!ELEMENT RESPONSE (SWITCH)*>

<!ATTLIST RESPONSE NEXT CDATA #IMPLIED NEXTMETHOD (GET|POST) "GET"

FIELDS NMTOKENS #REQUIRED>

<!ELEMENT RENAME EMPTY>

<!ATTLIST RENAME VARNAME NMTOKEN #REQUIRED

RECNAME NMTOKEN #REQUIRED>

<!ELEMENT CASE EMPTY>

<!ATTLIST CASE VALUE CDATA #REQUIRED

NEXT CDATA #REQUIRED NEXTMETHOD (GET|POST) "GET" >

<!ELEMENT VALUE EMPTY>

<!ATTLIST VALUE NAME NMTOKEN #REQUIRED>

<!ELEMENT BREAK EMPTY>

<!ATTLIST BREAK MSECS CDATA #IMPLIED>

SIZE (NONE|SMALL|MEDIUM|LARGE) "MEDIUM">

<!ELEMENT OPTIONS EMPTY>

<!ELEMENT OR EMPTY>

<!ELEMENT OPTION (#PCDATA|VALUE|OR)*>

<!ATTLIST OPTION VALUE CDATA #IMPLIED

NEXT CDATA #IMPLIED NEXTMETHOD (GET|POST) "GET" >

Appendices

Appendix B - Vcard Profile Names and Subtypes

This appendix describes the valid combinations of Vcard profile names and their associated subtypes. For more information regarding the Vcard specification, see ???http://www.imc.org/rfc2426???.

All information described below is provided based on the profile information of the VoxML voice browser's current interactive user. Although not all browser implementations will store the user's profile information, this schema represents a convenient way to access the data when it is available.

Vcard Profile Names and Subtypes