VoiceXML 2.1 Development Guide

Element Summary

Elements	Attributes	Parents	Children
assign	expr, name	parents	none
audio	expr, fetchhint, fetchtimeout, maxage, maxstale, src	parents	children
block	cond, expr, name	parents	children
break	size, strength, time	parents	none
catch	cond, count, event	parents	children
choice	accept, dtmf, event, eventexpr, expr, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, message, messageexpr, next	parents	children
clear	namelist	parents	none
data	enctype, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, method, name, namelist, src, srcexpr	parents	none
disconnect	none	parents	none
else	none	parents	none
elseif	cond	parents	none
emphasis	level	parents	children
enumerate	none	parents	children
error	cond, count	parents	children
example	none	parents	none
exit	expr, namelist	parents	none
field	cond, expr, modal, name, slot, type	parents	children
filled	mode, namelist	parents	children
foreach	array, item	parents	children
form	id, scope	parents	children
goto	expr, expritem, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, next, nextitem	parents	none
grammar	fetchhint, fetchtimeout, mode, root, scope, src, srcexpr, tag-format, type, version, weight, xml:base, xml:lang, xmlns	parents	children
help	cond, count	parents	children
if	cond	parents	children
initial	cond, expr, name	parents	children
item	repeat, repeat-prob, weight	parents	children
link	dtmf, event, eventexpr, expr, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, message, messageexpr, next	parents	children
log	expr, label	parents	children
mark	name	parents	none
menu	accept, dtmf, id, scope	parents	children
meta	content, http-equiv, name	parents	none
noinput	cond, count	parents	children
nomatch	cond, count	parents	children
one-of	none	parents	children
option	accept, dtmf, value	parents	none
paragraph	xml:lang	none	none
param	expr, index, name, type, value	parents	children
phoneme	alphabet, ph	none	none
prompt	bargein, bargeintype, cond, count, timeout, xml:lang	parents	children
property	name, value	parents	none
prosody	contour, duration, pitch, range, rate, volume	parents	none
record	beep, cond, dtmfterm, expr, finalsilence, maxtime, modal, name, type	parents	children
reprompt	none	parents	none
return	event, eventexpr, message, messageexpr, namelist	parents	none
rule	id, scope	parents	children
ruleref	special, uri	parents	none
say-as	format, interpret-as	parents	children
script	charset, fetchhint, fetchtimeout, maxage, maxstale, src, srcexpr	parents	none
send	fetchaudio, fetchtimeout, maxage, maxstale, method, namelist, uri, uriexpr	parents	none
sentence	xml:lang	none	none
sub	alias	none	none
subdialog	cond, enctype, expr, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, method, name, namelist, src, srcexpr	parents	children
submit	enctype, expr, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, method, namelist, next	parents	none
tag	none	parents	none
throw	event, eventexpr, message, messageexpr	parents	none
token	lang-list	parents	none
transfer	aai, aaiexpr, bridge, cond, connecttimeout, dest, destexpr, expr, maxtime, name, transferaudio	parents	children
value	expr	parents	none
var	expr, name	parents	none
voxeo:recordcall	info, value	parents	none
vxml	application, version, xml:base, xml:lang, xmlns, xmlns:voxeo	none	children

The expr defines the new value of the variable in question. Any valid ECMAscript value is considered to be a suitable value.

The name attribute specifies any currently available variable name within the current scope.

block, catch, error, filled, help, if, noinput, nomatch

The assign element is used to explicitly assign a value to an existing variable, which has been declared, by using the <var> element.

The expr attribute is used when we want to use a generated value rather than an explicit URI for our audio file’s destination. The value for this variable must equate to a valid audio URI, else the content will not be executed.

Fetchhint is used to specify when the resource should be fetched during application execution. The possible values and their descriptions are:

prefetch : Begin the resource fetch upon initial document execution

safe: Only fetch the resource when it is specifically called in the application

Note that the Voxeo platform will always prefetch content, regardless of what this attribute value is set to. As such, specifying a value is somewhat redundant.

The ‘fetchtimeout’ attribute is used to indicate how long, (in seconds or milliseconds), the interpreter should attempt to fetch the file in question before reverting to any backup TTS, (if present), or before the application execution skips over the contents of the <audio> tag, (if no backup TTS is present). Also note the strict formatting of this value; if specified, the time value must have the ‘s’ denomination appended to it, else an error.badfetch is thrown.

The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable age, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.

The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.

The ‘src’ attribute specifies a URI pointing to a valid audio file for your application to play. Ex: <audio src=”MyServer/MyDir/MyFile.wav”/>;

audio, block, catch, choice, enumerate, error, field, filled, help, if, initial, menu, noinput, nomatch, prompt, record, subdialog, transfer

audio, break, emphasis, enumerate, foreach, mark, phoneme, prosody, say-as, value

The audio element allows you to play an audio sound file in your application, assuming that your file is in the following formats:

16bit, 8Khz, PCM Wave files (Riff Format)
8bit, 8Khz, u-law Sphere files
16bit, 8Khz, PCM Sphere files

In the event that your audio URL cannot be located, you can nest backup text to speech within the audio tags to ensure that a message of some sort will get played. See Appendix F in the Voxeo documentation for further information and helpful hints.

The cond attribute specifies a Boolean expression, which must equate to ‘true’ in order for the content to be visited and executed. (Additionally, the expr attribute must also be set to ‘undefined’, see below).

The expr attribute specifies the initial value of the element; if this value is ‘undefined’, (default), then the element will be visited by the FIA and executed. If this attribute has a value other than ‘undefined’, then the element will not be visited until explicitly set to 'undefined', by use of the clear element.

This contains the value, or ‘ID’ of the block in question, which is used for navigational purposes within the application. In order to goto a specific block in an application, a block name is required.

form

assign, audio, clear, disconnect, enumerate, exit, goto, if, log, prompt, reprompt, return, script, submit, throw, value, var

The block element is simply a form-item container element for executable content, which executes if the condition of the item is equal to ‘true’.

Used to indicate a relative value for the pause length within the TTS output. The equivalent values for this attribute are:

small: 2 second pause
medium: 5 second pause
large: 10 second pause

Note that this attribute has been phased out entirely in favor of the SSML-compliant 'strength' attribute.

The strength attribute is the SSML-compliant replacement of the older size attribute. The value of this attribute specifies the length of silence appanded/prepended to any TTS output. The allowable values, and their time equivalents are:

none -- 0 seconds of silence
x-weak -- .35 seconds of silence
weak -- .35 seconds of silence
medium -- .7 seconds of silence
strong -- 1.0 seconds of silence
x-strong -- 1.0 seconds of silence

The time attribute replaces the non-compliant attribute of 'msecs', used on the VXML 1.0 platform. Any numeric value is valid input within this attribute. A value of ‘5000’ would indicate a 5 second pause within the TTS output.

audio, choice, emphasis, enumerate, paragraph, prompt, prosody, sentence

The break element is used to designate a pause in the TTS output, with the length being a user-specified time value in either milliseconds, or of a predetermined ‘size’ variable.

The cond attribute specifies a Boolean expression, which must equate to ‘true’ in order for the content to be visited and executed. Any standard ECMAScript Boolean value is valid for this attribute.

The count attribute allows the developer fine grained control over event handling upon multiple event occurrences. When an event is thrown for the first time, the catch element with a count of 1 will be executed. Upon the second instance of the same event, the FIA will look for a catch handler with a count value of 2, if one exists, otherwise, it will simply execute the catch handler with the count of 1 again.

The event attribute specifies the event name that must be thrown in order for the catch element to execute, either a platform-defined error such as error.badfetch, or any user-defined error that is designated by the throw element.

field, form, initial, menu, record, subdialog, transfer, vxml

assign, audio, clear, disconnect, enumerate, exit, goto, if, log, prompt, reprompt, return, script, submit, throw, value, var

The catch element is used to intercept application and user-defined errors, conditions, and messages, thereby allowing the developer to assign event handlers on a scoped basis. The content nested within the catch element will only be executed when its particular event is thrown.

accept is a w3c compliant attribute that allows the developer to specify whether an exact or an approximate utterance will be considered a valid grammar match for the phrase contianed within the choice element. If set to 'approximate' then the caller is allowed quite a bit of leeway in regards to how exact the utterance must be, while a setting of 'exact' designates more stringent control of what is considered valid. For example, if the grammar value is the string 'david hasselhoffs self integrity', then an utterance of 'hasselhoff' will be considred a valid match if the accept setting is 'approximate', but not if set to 'exact'.

Do note that the choice accept value will override the menu accept setting; therefore, to ease confusion, it is recommended that you simply use the choice accept setting whenever possible.

The dtmf attribute indicates the dtmf key that is linked to a specific menu choice.

The event attribute specifies the catchable event to be thrown upon a choice match; this essentially functions identically to having a throw event linked to a menu choice.

The eventexpr attribute specifies an ECMAScript expression that evaluates to the event being thrown to the application. As mentioned, either platform defined events, or user-defined events may be indicated in this attribute. Please note that either event or eventexpr may be used within the parent element, but not both.

The expr attribute allows us to use a variable expression rather than a static value to determine the resultant dialog or document URI that the application transitions to upon a user’s selection.

The fetchaudio attribute specifies the URI of the .wav file to play to the caller in the event of an extended document fetch. Essentially, while the fetch is being made, it allows the developer to play some filler music to the caller rather than presenting only silence.

Fetchhint is used to specify when the resource should be fetched during application execution. The possible values and their descriptions are:

prefetch : Begin the resource fetch upon initial document execution

safe: Only fetch the resource when it is specifically called in the application

Note that the Voxeo platform will always prefetch content, regardless of what this attribute value is set to. As such, specifying a value is somewhat redundant.

The ‘fetchtimeout’ attribute is used to indicate how long, (in seconds or milliseconds), the interpreter should attempt to fetch the content before throwing an error.badfetch exception. See Appendix C for further information.

The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.

The message attribute allows the developer to include a descriptive message along with the event that is being thrown. The message being thrown is accessible in the catch elements shadow variable _message.

The messageexpr attribute allows the developer to include an ECMAScript expression resolving to the message being thrown to the application. The messageexpr being thrown is accessible in the catch elements shadow variable _message.

The next attribute identifies the resultant dialog or document URI that the application transitions to upon a user’s selection.

audio, break, emphasis, enumerate, grammar, mark, paragraph, phoneme, prosody, say-as, sentence, value

The choice element is used in conjunction with the menu element to create robust voice menus that allow the caller multiple navigational choices without the need for traditional grammar structures. The menu tag acts as the container element, while the choice element defines the available menu items.

The ‘namelist’ attribute allows you to specify particular variables or guard variables to be cleared upon execution. If none are explicitly set within this attribute, then all form items in the current form are cleared by default.

block, catch, error, filled, help, if, noinput, nomatch

The clear element is used to set any existing VoiceXML variable or element guard variables to an undefined value, such as any user-defined variable set with the var or assign tags. The clear element can also be used to clear any block, subdialog, menu, record, transfer, or field guard variables, thus, programmatically allowing a caller to revisit these form items.

The enctype attribute specifies the MIME type encoding for any data submitted via the namelist attribute. The possible vales for this attribute are ‘x-www-form-urlencoded’, (default), or ‘multipart/form-data’, (for binary data submissions, such as recorded audio).

Fetchhint is used to specify when the resource should be fetched during application execution. The possible values and their descriptions are:

prefetch : Begin the resource fetch upon initial document execution

safe: Only fetch the resource when it is specifically called in the application

Note that the Voxeo platform will always prefetch content, regardless of what this attribute value is set to. As such, specifying a value is somewhat redundant.

The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.

The method attribute specifies the HTTP method to use when sending the request. If unspecified, then the value of ‘GET’, (default) is assumed, unless the submission of multipart/form-data is encountered, in which case the implied method will be ‘POST’.

The name attribute specifies the name of the ECMAScript form item variable. Each name assigned to an data element must be unique, else a fatal error.badfetch will be thrown.

The namelist attribute specifies a space-separated list of variables to send to the URI indicated by the src or srcexpr attributes. Note that if the namelist attribute is left unspecified, then no variables will be submitted to the destination URI.

The src attribute specifies the URI where the external XML <data> content is located. Note that either 'src' or 'srcexpr' may be specified, but not both.

The srcexpr attribute evaluates to an ECMAScript value that defines the target URI. Either srcexpr or src may be specified for the element, but not both.

block, catch, error, filled, form, help, if, noinput, nomatch, vxml

The <data> element is a new addition to the VoiceXML2.1 specification that allows the developer to fetch content from an XML source without having to use any server side logic, and without having to transition to a new dialog.

block, catch, error, filled, help, if, noinput, nomatch

The disconnect element is used to programmatically disconnect the caller from the voice application, which also throws an connection.disconnect event to the interpreter to allow the the developer to submit any existing variables to his webserver.

The else element is used as the final logic constructor in an array of conditional statements. The content nested within the else element will get executed when all other if and elseif cond attributes evaluate to ‘false’.