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, next	Parents	Children
clear	namelist	Parents	none
data	ecmaxmltype, enctype, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, method, name, namelist, src, srcexpr	Parents	none
disconnect	namelist	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, voxeo:useuri, 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, next	Parents	Children
log	expr, label	Parents	Children
mark	name, nameexpr	Parents	none
media	soundLevel, speed	Parents	none
menu	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, volume	Parents	none
record	beep, cond, dtmfterm, expr, finalsilence, maxtime, modal, name, type, voxeo:trimcondition, voxeo:trimms	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
sentence	xml:lang	none	none
sub	alias	none	none
subdialog	cond, enctype, expr, fetchaudio, fetchhint, fetchtimeout, maxage, maxstale, method, name, namelist, src	Parents	Children
submit	enctype, expr, fetchaudio, fetchhint, fetchtimeout, method, namelist, next	Parents	none
tag	none	Parents	none
throw	event, eventexpr, message, messageexpr	Parents	none
token	lang-list	Parents	none
transfer	aaiexpr, bridge, cond, connecttimeout, dest, destexpr, expr, maxtime, name, transferaudio, type, voxeo:callerid	Parents	Children
value	expr	Parents	none
var	expr, name	Parents	none
voxeo:logcontrol	mode	Parents	none
voxeo:recordcall	info, infoexpr, 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 a variable. The Prophecy implementation ignores the requirement where a variable must be pre-declared in order to assign a value to it, for ease of development. See the documentation on ‘variables’ for detailed information on scooping, assignment, and session variables.

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 *not* prefetch content by default. As such, a developer should specify a value of ''prefetch" if resources are to be made available prior to execution of application content.

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”/>;You can also use dtmf:1234 to send out-of-band dtmf tones in your applications: <audio src="dtmf:1234"/>

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. Value can be specified in seconds or milliseconds. A value of '5s' or ‘5000ms’ would indicate a 5 second pause within the TTS output. Default (no suffix) is milliseconds.

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

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 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 ecmaxmltype attribute specifies if E4X is enabled in the data element instead of DOM. E4X is an acronym for "ECMAScript for XML" which is a language extension that adds native XML support to ECMAScript. The result is a simpler means of accessing data contained in an external XML document. For more information, see ECMAScript for XML (E4X) Specification.

Note: To use E4X, specify this attribute value as "e4x" with lowercasing.

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

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.

The namelist attribute allows developers to send the browser variable information upon an exit condition. Currently, the VXML browser does not do anything with the namelist value, but it does allow you to pass the values to any originating CCXML application.

Here is an example of the catch of a hangup event in VXML:



<catch event="connection.disconnect.hangup">

    <exit namelist="SomeVar"/>

</catch>

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’.

The cond attribute specifies any valid expression, which equates to the value to be evaluated.

The elseif element is used to specify additional content when all other else or if statements equate to ‘false’. When a series of if-elseif-else statements are encountered, the application will execute the first one which evaluates to ‘true’.

The level attribute defines the amount of emphasis or de-emphasis that is assigned to the nested TTS. This

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

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

The emphasis element allows the developer to specify the level, or stress, of any specified TTS enclosed within the emphasis element. Do note that SSML tags are ignored by some of the available TTS engines, while some engines use their own non-compliant markup. Check the Text-To-Speech appendices for additional details.

audio, block, catch, choice, error, field, filled, help, if, initial, menu, prompt, record

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

The enumerate element is used to read the list of menu choices to the caller, using either TTS or a user-defined audio file.

The <enumerate> element may be used within the <prompt> and the <catch> elements associated with <menu> elements and with <field> elements that contain <option> elements. An error.semantic event is thrown if the <enumerate> is used elsewhere.

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 error element is the shorthand for the <catch event=”error”> handler, and will catch all events whose value begins with ‘error’. See the documentation for 'exceptions' to learn more.

rule

The example element is part of the Speech Recognition Grammar Specification, and is only usable within XML grammar constructs. This element defines an 'example' phrase, useful to the developer, which can be used to create a successful recognition result for the grammar in question.

The expr attribute lets the developer send an ECMAScript expression back to the interpreter when this condition executes. Like the namelist attribute, the VXML browser ignores values in this attribute, but any originating CCXML application can receive the values contained in the expr attribute.



<catch event="connection.disconnect.hangup">

    <exit namelist="SomeVar"/>

</catch>

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

The exit element is similar to the disconnect tag, in that it will terminate the current dialog and return control to the interpreter; i.e., the browser will release the call. The difference is, that the exit element allows the developer to specify both a namelist and an expression that can be sent back to the browser

The modal attribute is a Boolean value that allows fine grained control of active grammars within the field. When the modal attribute is set to false (default), then all higher scoped grammars are enabled, (i.e., form-level document/dialog scoped grammars) while a user is within the field. If the modal attribute is set to true, then only field grammars are enabled and all other grammars are temporarily disabled.

The name attribute defines the ECMAScript variable name that declares the field-item variable for the dialog. A successful grammar recognition will hold the resultant value in this namespace when executing any filled elements. Each field name within a document must be unique, else a fatal error.badfetch will be thrown.

The slot attribute specifies the name of a grammar slot which is used to populate the field item variable. If no value is specified, then the interpreter will assume it to be the same as the field name. The slot attribute allows the developer to reuse slot/value grammar constructs in multiple fields whose names differ from one another. See the grammar documentation for further information.

The type attribute can specify any of the platform-defined built-in grammars. The Nuance browser offers support for all built-in grammars defined in the w3c specification. Note that no additional grammar constructs are needed within the field when a built-in type is specified, although any document or dialog scoped grammars will still be considered active. See the documentation for the built in grammars for further information.

form

audio, catch, enumerate, error, filled, foreach, grammar, help, link, noinput, nomatch, option, prompt, property, value

The field element facilitates a dialog which allows the interpreter to collect information from the user. Caller utterances are matched against any active grammars, until the element’s filled condition is executed.

The mode attribute allows the developer to have control of when the filled element executes. If set to ‘any’, then the filled element will execute as soon as one valid grammar match, specified by the namelist, has occurred. If set to ‘all’, then every variable namespace defined within the namelist must be filled in order to execute any vxml code contained within the filled element.

The namelist attribute specifies the input namespace that must equate to ‘true’ for the filled element to execute. If a filled element is contained within a form, the namelist attribute will default to the names of the form's field items. If a namelist is specified within a filled element that is contained by an input item, (such as a field), then the interpreter will throw a fatal error.badfetch condition.

field, form, record, subdialog, transfer

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

The filled element allows the developer to specify actions to take when a grammar match has occurred. Once the interpreter has recognized a valid match specified by the filled elements namelist attribute, the filled element will then execute any code contained within it, (such as a conditional if/else statement).

The 'array' attribute defines the name of the array referenced by the <foreach> element,; failure to specify this attribute will result in an error.semantic event being thrown.

The 'item' attribute denotes the name of the variable that stores a particular array value as it is being iterated within the loop. If this variable is not already defined, then it will be declared upon invocation of the <foreach> element.

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

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

The VoiceXML 2.1 specification introduces the new <foreach> element, which allows the developer an inherent browser method for looping through items in an array, and outputting them via TTS, or via <audio>. This element must specify both the 'array', as well as the 'item' attributes, else an error.semantic will be thrown.

Keep in mind, when the <foreach> element is used within a <prompt> element, it can only contain the same elements that are valid within the <enumerate> element. This means the same elements allowed within the <prompt> except for <meta>, <metadata>, and <lexicon>.

The id attribute specifies the navigational identifier of the form element. Once specified, the developer can assign the id as a destination of any goto statement.

The scope attribute denotes the scope of any grammars contained within the form. If set to ‘dialog’, (default), then all form grammars will only be active within the current form. If set to ‘document’, then the grammars will be considered active throughout the current page of VoiceXML code. If, however, the scope is set to ‘document’ in the application root document, then the grammar will be active throughout the entire application.

vxml

block, catch, data, error, field, filled, grammar, help, initial, link, noinput, nomatch, property, record, script, subdialog, transfer, var

The form element acts as a container for all field-items, (such as a field or a subdialog), and for all control items, (such as a block or an initial element). The form element is considered the basic component of any VoiceXML dialog, and is part of a balanced breakfast.

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

The expritem attribute denotes an ECMAScript value that equates to the value of the next form item, (such as a field name) to visit. Either expritem or nextitem may be specified, but not both.

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

The fetchtimeout attribute allows the developer to specify how much time to allow on a fetch before throwing an error.badfetch event. This can be specified globally by using the fetchtimeout property in the application root document. If not specified, it will default to 5 seconds. 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:

<goto next="MyPage.vxml” fetchtimeout=”5s”/>

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 next attribute specifies the literal URI, or URI fragment of where to transition the caller. The value can be a full URI:

<goto next=”http://MyServer.com/MyFile.vxml”/>

or a relative URI:

<goto next=”MyFile.vxml”/>

In addition, it can also indicate a particular form within the current document, where the pound sign precedes the form item name:

<goto next=”#AnotherForm”/>

Or lastly, it can indicate a specific form in another document:

<goto next=”AnotherDocument.vxml#AnotherForm”/>

The nextitem attribute works much like the next attribute, except that it allows the developer to transition the caller to a specific form item within the current document, for example:

<goto nextitem="fieldName"/>

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

The goto tag is used to transition application execution to a specific form within the current document, or to an entirely separate document. Additionally, it can transition execution to a a specific form within an entirely separate document.

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

(Ignored attribute)
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.

The mode attribute specifies the mode of the grammar in question. The two values allowed for this attribute are 'voice' and 'dtmf'.

XML Grammars only
The root attribute defines the root rulename of the XML grammar, and is required for any inline XML grammar construct.

The scope attribute allows the developer to specify whether the grammar will be given dialog scope or document scope. Document scoped grammars must have slotnames and return values explicitly defined in order to function properly. See the grammar documentation for additional information. If a value for this attribute is not specified, then the grammar inherits the scope of its parent element. Note that specifying a grammar 'scope' within a form-item, (such as the <field> element), will cause a fatal error.

The src attribute specifies the target URI of the grammar file. External grXML grammars referenced with the src attribute must be referenced as follows:

<grammar src = "MyGrammar.xml" type="application/grammar-xml"/>

Inline grammars are not subject to this syntax, nor do they need an explicit src declared:



<grammar xml:lang="en-us" root="TOPLEVEL" xmlns="http://www.w3.org/2001/06/vxml">

     <rule id="TOPLEVEL">

           <item> testing </item>

    </rule>

</grammar>

Inline grXML subgrammars do not need to reference anything in the src attribute:



<?xml version= "1.0"?>

  <grammar xml:lang="en-us" root = "TOPLEVEL" xmlns="http://www.w3.org/2001/06/grammar">

    <rule id="TOPLEVEL" scope="public">

        <!-- Initializes both first and middle name in case one of them is not uttered.-->

        <tag>rules.FIRSTNAME="";</tag>

        <tag>rules.MIDDLENAME="";</tag>



        <item repeat="0-1"> <ruleref uri="#FIRSTNAME"/>  </item>

        <item repeat="0-1"> <ruleref uri="#MIDDLENAME"/> </item>

        <ruleref uri="#LASTNAME"/>

        <tag> out = rules.FIRSTNAME  + rules.MIDDLENAME  + rules.LASTNAME;</tag>		

    </rule>



  <rule id="FIRSTNAME" scope="public">

  <one-of>

    <item> matt<tag>out="matthew ";</tag></item>

    <item> jon <tag>out="jon";</tag></item>

  </one-of>

  </rule>



  <rule id="MIDDLENAME" scope="public">

  <one-of>

    <item> bon <tag>out="bon ";</tag></item>

    <item> double ya <tag> out="w ";</tag></item>

  </rule>



  <rule id="LASTNAME" scope="public">

  <one-of>

    <item> henry <tag> out="henry "; </tag></item>

    <item> jovi <tag> out="jovi ";  </tag></item>

  </one-of>

  </rule>



</grammar>

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.

The tag-format attribute allows the developer to specify the grammar tag format of an inline XML grammar construct. The only valid data type for this optional element is 'semantics/1.0'.

The type attribute specifies the MIME type of the grammar file. Acceptable values for this attribute are 'application/grammar-xml' or 'text/gsl'. Note that unlike other voice browsers, this attribute is required in order to effectively implement a voice grammar. If left unspecified, then an error.badfetch will occur.

The version attribute of the grammar element, predictably enough, specifies the version of the grammar itself. This should always be set to '1.0'.

The voxeo:useuri attribute is used to bypass the Prophecy grammar translator and send the URI for a grammar directly to an external recognizer, such as Nuance, or Loquendo. The external recognizer fetches and compiles the grammar itself. To bypass the Prophecy grammar translator, place this attribute directly in the grammar XML element. This attribute is useful for large grammars that can be compiled and cached by an external recognizer.

Note: As this attribute is a Voxeo-specific extension, you must specify the xmlns:voxeo within the vxml element with the value set to the Voxeo namespace, for example, xmlns:voxeo="http://community.voxeo.com/xmlns/vxml".

XML Grammars only
The weight attribute specifies the increased or decreased likelihood for a particular grammar match. For instance, specifying the value as 0.8' would increase the chances that an approximate utterance would be considered a valid grammar match, while a value of '0.2' would make it highly unlikely that a match would ever be considered valid.

The URI value of the xml:base attribute denotes the base URL of the document. All relative URI’s contained in the document are derived from the base attributes value. If unspecified, then the platform assumes that the current URI is the value of the base attribute.

The xml:lang attribute specifies the language and locale information of the grammar If omitted in GSL grammars, it will inherit this value from the document hierarchy, or ultimately from the platform default, which equates to 'en-US'. The language and locale information is not case-sensitive. Note: This attribute is required when using XML grammars.

For VoiceXML language options and mappings, see ASR Languages and TTS Languages.

The xmlns attribute defines the grXML namespace; all tags and attributes belong to this namespace. This attribute is required when using grXML grammars, and should specify the value of "http://www.w3.org/2001/06/grammar"

choice, field, form, link, record, transfer

rule

The grammar element allows the developer to specify a GSL or XML recognition grammar for either voice or DTMF input. Grammars may be defined inline (within the vxml document itself), or as a standalone, external file.

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 help element provides a syntactic shorthand for <catch event=”help”>. This element is used as an error handler for the help event which is contained in the Universal Grammar of any voiceXML application.

The cond attribute specifies any valid expression, which equates to the value to be evaluated.

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

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

The if element, (in conjunction with the else/elseif elements), provides a method to utilize conditional logic expressions which allow the developer to change the control flow within the application based on user utterances, variable values, or events.

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

form

audio, catch, enumerate, error, help, link, noinput, nomatch, prompt, property, value

The initial element is used in mixed-initiative dialogs, (where the caller’s first utterances dictate application flow), allowing the caller to fill in form-wide information, (thus allowing the user to skip over the field prompts), with but one utterance.

The repeat attribute is an SRGS addition to VWS2.0 that allows the developer to specify the number of times, if any, that the utterance is allowed to be repeated by the caller. The allowed formats for this attribute are as follows:

item repeat="3" The utterance must be repeated 3 times
item repeat="2-4" The utterance must be repeated 2 to 4 times
item repeat="2-" The utterance must be repeated 2 or more times
item repeat="0-3" The utterance is not required to be repeated, but can be repeated for up to 3 times

The repeat-prob attribute allows the developer to specify a probability that an utterance will be repeated by the caller. The value should be a number ranging from '0.0', (least likely to be repeated), to '1.0', (most likely to be repeated).

The weight attribute specifies the increased or decreased likelihood for a particular grammar match. For instance, specifying the value as '0.8' would increase the chances that an approximate utterance would be considered a valid grammar match, while a value of '0.2' would make it highly unlikely that a match would ever be considered valid. Note that the parent Item element must be enclosed by the One-Of element, else the grammar weighting is ignored.

item, one-of, rule

item, one-of, ruleref, tag, token

The item element defines a valid utterance match within an XML grammar. This element also allows repeats and probability weighting to be added to the utterance in question.

The dtmf attribute indicates the dtmf key which can be used in conjunction with any other voice grammar specified within the link itself to validate a successful grammar match.

The event attribute allows the developer to specify an event to be thrown to the application. If both the event and next attributes are specified for the link, then the event will take precedence, although this behavior is deprecated in the VXML 2.0 implementation. Therefore, it is recommended that you use one or the other for future compatibility.

The expr attribute evaluates to an ECMAScript value that defines the target URI. Either expr or next may be specified, but not both.

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

The fetchtimeout attribute allows the developer to specify how much time to allow on a fetch before throwing an error.badfetch event. This can be specified globally by using the fetchtimeout property in the application root document. If not specified, it will default to 5 seconds. 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:

<link next="MyPage.vxml” fetchtimeout=”5s”/>

See Appendix C exceptions 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 next attribute denotes the destination URI or form item to transition the caller to when the link grammar is matched. The value can be a full URI:

<link next=”http://MyServer.com/MyFile.vxml”>

or a relative URI:

<link next=”MyFile.vxml”>

In addition, it can also indicate a particular form within the current document, where the pound sign precedes the form item name:

<link next=”#AnotherForm”>

Or lastly, it can indicate a specific form in another document:

<link next=”AnotherDocument.vxml#AnotherForm”>

field, form, initial, vxml

grammar

The link tag allows the developer to easily implement a document or application scoped grammar and transition/event handler for a caller’s input. This element is usually placed in the application root document at the vxml level in order to implement global grammars/event handlers.

The expr attribute contains the JavaScript message to be output to the logger. Keep in mind that all non-parsable characters need to be escaped.

The 'label' attribute is used to define a user-defined string which can be specified for informational purposes (such as a reason for the log statement itself).

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

value

The log element allows the developer to output debug messages to the Voxeo Logger. Generous use of log statements placed within code can greatly assist when tracking variable values, and errors that occur in the application.

The name attribute specifies the name of the marker in question.

Note: Either the name or nameexpr attribute is required for the mark element.

An ECMAScript expression which evaluates to the name of the mark when the prompt is queued. If nameexpr cannot be evaluated, an error.semantic event is thrown.

Note: Either the name or nameexpr attribute is required for the mark element.

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

Inserts markers into output streams for asynchronous notification.

The soundLevel attribute controls audio gain defined in terms of decibles, or dB levels. Setting this attribute to a large negative number will mute the media. To reduce the media amplitude by 50% of its current level, you can specify a setting of "-6.0db" and similarly, to double the current media amplitude, specify "+6.0dB". The maximum gain value is +12.0db.

For example, soundLevel="+1.0dB"

Note: You must specify a "+" or "-" for this attribute.

The speed attribute controls the percentage of the playback speed of media in relation to the original playback speed. Pitch is affected. Valid values range from 25% to 400%.

prompt

The media element extends the VoiceXML audio element by providing additional attributes. This implementation by Voxeo adds attributes for soundlevel and speed based on the W3C VoiceXML 3.0 draft.

The dtmf attribute, when set to 'true', will assign the first 9 menu choices implicit dtmf grammar values, unless the choices already have them explicitly assigned. Unless specified, the default value for the dtmf attribute is false, thus disallowing implicit dtmf grammar assignation.

The id attribute specifies the navigational identifier of the form element. Once specified, the developer can assign the id as a destination of any goto statement.

The scope attribute denotes the scope of any grammars contained within the menu. If set to ‘dialog’, (default), then all grammars contained will only be active within the current form. If set to ‘document’, then the grammars will be considered active throughout the current page of Voicexml code. If, however, the scope is set to ‘document’ in the application root document, then the menu grammar will be active throughout the entire application.

vxml

audio, catch, choice, enumerate, error, help, noinput, nomatch, prompt, property, script, value

The menu tag is another ‘shortcut element’ that emulates the field, grammar, and goto elements. In addition, it also allows for both implied DTMF and Voice grammars.

The content attribute specifies the value of the metadata property.

The http-equiv attribute specifies the name of the HTTP response header that should be honored for a specified VoiceXML document. Note that this will not affect the caching of vxml documents on the Voxeo platform; caching should be controlled at the server level, as detailed in the caching tutorial.

The name attribute specifies the name of the meta-data property. The Prophecy browser allows us some serious error handling notification with the following values:

maintainer: sends an error log to the email address specified upon application error
debug_flags: sets the debugging flags to a custom level, (see the property guide for more information
speak_exceptions: allows the platform to convert any error messages to a TTS string that will be read out to the caller

vxml

The meta element functions in VoiceXML as it does in HTML. It denotes meta information about the document, and its http headers. Do note that when <meta> is used in a root document, all leaf documents will inherit the actions of <meta>.

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

assign, audio, clear, exit, goto, if, reprompt, return, script

The noinput tag acts as a syntactic shorthand for the expression <catch event=”noinput”>. It allows the developer to assign event handlers when the application expects voice or DTMF input, but has received none from the caller.

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 nomatch element is a syntactic shorthand for the expression <catch event=”nomatch”>. This attribute allows the developer to assign handlers when the caller inputs a value that is not recognized by any of the active grammars.

item, rule

item

The one-of element allows the grammar to be constructed with a series of alternate phrases or rule expansions, each of which is contained within an Item element. This element is the basic building block of any XML grammar that defines more than one valid utterance.

The value of the dtmf attribute specifies a DTMF key press, or a sequence of key presses, a caller may input to choose the listed option. Using this attribute allows the developer to permit both DTMF and voice as valid input for a particular field option. Please note that when listing a sequence of key presses, whitespace is optional (i.e. dtmf="123" is equivalent to dtmf="1 2 3"). Also, be aware that if you would like to use the '#' key, you must first change the 'termchar' property, as '#' is the default terminating character.

The value attribute specifies the string to use for the field item return when a user selects a particular option. If not specified, then the dtmf value is returned.

field

The option element is a convenient grammar shortcut, which allows the developer to list simple choices to the caller rather than constructing a complete grammar with return slots.

The xml:lang attribute specifies the language and locale information of the VoiceXML document. If omitted, it will inherit this value from the document hierarchy, or ultimately from the platform default, which equates to 'en-US'. The language and locale information is not case-sensitive.

For VoiceXML language options and mappings, see ASR Languages and TTS Languages.

Nesting TTS within the paragraph element, (or simply, the p element), specifies that the particular block of TTS should br read out in paragraph structure.

The expr attribute equates to an ECMAScript value that defines the value for the parameter. Of note is the fact that expr and value are mutually exclusive attributes.

The index attribute, used when invoking an object, is used by the developer to specify a particular index reference in an array of parameters.

The name attribute specifies the name of the parameter to be passed to the destination URI.

The type attribute is only relevant when used in conjunction with the object element, and specifies the MIME type of the destination object.

The value attribute specifies the literal string value of the parameter getting passed to the destination URI.

param, subdialog

param

The param element is used when submitting data to a subdialog or an object. Note that any params sent to an external subdialog file must have the param set as a form-level variable within the target page

The alphabet attribute denotes the phoenetic alphabet to be used. The possible choices are:

ipa -- International Phoenetic Alphabet
worldbet -- Worldbet (Postscript) phonetic alphabet
xsampa -- X-SAMPA phoenetic alphabet

The ph attribute specifies the phoneme string to be used.

The phoneme element essentially allows the developer to specify a phoenetic pronounciation for any TTS nested within.Do note that SSML tags are ignored by some of the available TTS engines, while some engines use their own non-compliant markup. Check the Text-To-Speech appendices for additional details.

The bargein attribute specifies whether or not the caller will be able to interrupt the TTS/audio output with a dtmf keypress or voice utterance. A value of 'true' indicates that the user is allowed to interrupt, while a value of 'false' forces the caller to listen to the entire prompt before being allowed to give input to the application.

The bargeintype attribute allows the developer to denote whether speech, (including dtmf) input or a user-defined 'hotword' will be considered a valid bargein. For instance, when set to 'speech', any user utterance or dtmf input will interrupt the prompt. But, when set to 'hotword', then the prompt will only be interrupted when a user enters a hotword grammar match.

The count attribute allows the developer to specify different content should a caller repeat certain actions. For instance, a prompt count=2 could play more detailed instructions to the caller should his first utterance prove to be invalid. If unspecified, this attribute defaults to 1. The FIA counter, which governs how many times a particular state is reached, is reset to 1 each time the enclosing form element is reached or a clear element (for that state) is encountered within the application.

The timeout attribute specifies the amount of the time the interpreter should wait for a user response before throwing a noinput event. This attribute is subject to the strict timing policy where ‘s’, or ‘ms’ must be appended to the time value. This attribute will override the timeout property, if set within the application. If left unspecified, then this will default to 5s, (5 seconds).

block, catch, error, field, filled, help, if, initial, menu, nomatch, record, transfer

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

The prompt element allows the developer to output synthesized text-to-speech content to the caller.

The name attribute defines the property name, which should match up with the listing in the property documentation.

The value attribute defines the value for the property in question. Note that all time designations must have the ‘s’ or ‘ms’ suffix appended to the value:

<property name=”timeout” value=”10s”/>

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

The property element defines any platform-defined setting which impacts the behavior of the application. A property can be set to encompass the entire application, (when set at the vxml level of an application root document), or a property can be defined for a specific form item.

The contour attribute denotes the pitch contour for the text nested within the parent element. This attribute is non-functional on all TTS platforms, (Speechify and Rhetorical).

The duration element specifies the time , (in seconds or milliseconds) in which to read the enclosed text.

The volume attribute specifies the volume of speech output.

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

The prosody element replaces the non-compliant pros element from VXML 1.0, and allows the developer to change several aspects of the TTS output to allow for custom tailoring of prompts to sound more naturalistic to the caller. Do note that SSML tags are ignored by some of the available TTS engines, while some engines use their own non-compliant markup. Check the Text-To-Speech appendices for additional details.

The beep attribute, when set to true, allows the developer to insert a ‘beep tone’ to indicate to the caller that the application has begun recording. If set to 'false', (default), the caller will not hear the beep indicating that the recording has started.

The dtmfterm attribute specifies whether the caller will be allowed to terminate the recording in progress with the press of a dtmf key. When set to 'true', (default), any dtmf keypress can end the recording session. If set to 'false', then the recording continues until a maxtime or finalsilence event is reached.

The finalsilence attribute defines the amount of time that a caller can remain silent while the recording is being executed before the interpreter decides that the caller has finished recording the intended message. The value of this attribute is subject to the strict time formatting where ‘s’ or ‘ms’ must be appended to the actual time value, i.e.: In addition the value for this must not exceed '10s', else an error.semantic will be thrown.

<record name=”R1” finalsilence=”3s”>

The maxtime attribute specifies the maximum length of a recording in seconds, (s) or milliseconds, (ms). When a message exceeds the maxtime value, the caller will be prompted to re-record the message, (this behavior changes in VXML 2.0). Note that the maximum length of a recording on Voxeo's Staging network is limited to two minutes, (120s). However, this can be enabled for a production application; contact the support team for details.

This attribute is currently ignored in the voice browser. A modal setting of ‘true’ will disable all non-local speech grammars while executing the record element. When set to 'false', this would activate local grammars while in the record element.

The name attribute specifies the field item variable name used when referencing the recorded audio.

The type attribute is an parameter which designates the MIME type of the recorded file. Allowable values are as follows:

audio/basic
audio/x-alaw-basic
audio/x-wav or audio/wav
audio/mp3

The trimcondition attribute is used to specify the conditions that the trimms attribute should apply. You can use any, or a combination of the following conditions, comma-separated: maxtime, maxsilence, dtmf, or stop. For example, if the conditions are set to dtmf, stop and the recording ends due to maxtime, then the trim would not occur because the conditions were not met. As this attribute is a voxeo-specific extension, it is required that the xmlns:voxeo attribute be specified within the <vxml> element, and its value set to the voxeo namespace.

The trimms attribute specifies the number of milliseconds to trim off of the end of a recording. This attribute can be used in combination with the trimcondition attribute. As this attribute is a voxeo-specific extension, it is required that the xmlns:voxeo attribute be specified within the <vxml> element, and its value set to the voxeo namespace.

Note: This feature is only supported by alaw/ulawl recording formats.

form

audio, catch, enumerate, error, filled, grammar, help, noinput, nomatch, prompt, property, value

The record element is an input item which records audio from the caller, and stores the resultant audio file in it’s namespace variable.

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

The reprompt element, upon execution, will increase the FIA prompt counter by one, and then replay the most recent prompt before listening again for caller input. Note the fact that the reprompt element will have no effect when placed within a filled construct, as the field item variable will have been already filled with a value.

The event attribute specifies the event to be thrown immediately after returning to the invoking application. Either an event or a namelist may be used in the return element, but not both.

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 namelist attribute specifies a space-separated list of variables to send to the subdialog back to the invoking application. Either a namelist or an event may be specified for the return element, but not both.

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

The return element is used to terminate a subdialog and return control to the main dialog.

The id attribute specifies the rulename of the grammar. Rulenames must be unique within the file itself, and may not contain hyphens, colons, or periods.

The scope attribute denotes whether or not the XML grammar is a private (local), rule, or if it is a public rule, which is used for an external rule reference.

grammar

example, item, one-of, ruleref, tag, token

The rule element defines the named rule expansion of an XML grammar.

The special attribute denotes rulenames which are disallowed for redefinition within a grammar. Allowable values are:

NULL -- A rule which is automatically matched
VOID -- A rule that can never be spoken
GARBAGE -- A rule that may match any speech up until the next rule match

Note that either special or uri may be defined for the Ruleref element, but not both. Also be aware that while these special ruleref classes are not accessible when using the Prophecy ASR, they can be used when using Prophecy with the Nuance ASR.

The uri attribute specifies the URI of the external grammar that is to be referenced. Note that existing rules within the same file can be referenced:

<ruleref uri="#MYRULE"/>

or rules from an external file may be referenced:

<ruleref uri="MyGrammar.xml#MYRULE"

item, rule

The ruleref element is an SRGS addition to VXML 2.0 that allows the developer to specify an existing rule for inclusion within the current grammar.

The format attribute is used by some TTS engines to further define how certain types of text get interpreted, such as date and time. Currently, the Prophecy, Rhetorical and Speechify TTS engines do not make use of the format attribute, but a third party TTS engine might. Consult the TTS guide relevant to your deployment for more information.

The interpret-as attribute defines how the TTS engine will interpret the specified text. As an example, if the text value is 1234 and interpret-as is set to number, then the TTS engine will render the value as "one-thousand, two-hundred, thirty-four". If interpret-as is set to digits, the TTS engine will render the value as "one, two, three, four". Consult the TTS guide relevant to your deployment for a complete list of available interpret-as values; documentation for the Voxeo supported TTS engines can be found below:

Prophecy TTS

Rhetorical TTS

Speechify TTS

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

value

Sometimes a developer needs to control how the TTS engine interprets text, especially numbers. The say-as element allows you to potentially define whether the text should be interpreted as time, boolean, date, digits, currency, number, phone, or time. Note that the actual available values may vary, depending on the TTS engine in use.

The charset attribute defines the character encoding of the script contained within the element.

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

The fetchtimeout attribute allows the developer to specify how much time to allow on a fetch before throwing an error.badfetch event. This can be specified globally by using the fetchtimeout property in the application root document. If not specified, it will default to 5 seconds. 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:

<script src="MyScript.js” fetchtimeout=”5s”/>

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 the URI where the external script content is located. Note that either inline script content or an external src may be referenced, 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 script element is used for enclosing ECMAScript code to execute on the client side. Note that unlike the HTML element, the script element in VoiceXML does not specify a type, as it must be ECMAScript only. Also note that either a src or inline content may be specified, but not both.

The sentence element, (or s element, for those into brevity), is used to format a particular region of TTS to be read out in sentence structure, rather than paragraph structure. Do note that SSML tags are ignored by some of the available TTS engines, while some engines use their own non-compliant markup. Check the Text-To-Speech appendices for additional details.

The alias attribute denotes the substitute text to be rendered in place of the content nested within the phoneme element.

The text nested within this element will be replaced by the value specified within the alias attribute. Do note that SSML tags are ignored by some of the available TTS engines, while some engines use their own non-compliant markup. Check the Text-To-Speech appendices for additional details.

The enctype attribute specifies the MIME type encoding for any data submitted via the namelist attribute. The two possible vales for this attribute are ‘x-www-form-urlencoded’, (default), or ‘multipart/form-data’, (for binary data submissions, such as recorded audio). When submitting recorded data, this value must be explicitly set to ‘multipart/form-data’ and the method attribute to 'POST.'

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

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 name attribute specifies the form item ECMAScript variable name for the subdialog in question.

The namelist attribute specifies a space-separated list of variables to send from the invoking application to the subdialog.

The src attribute specifies the URI location of the external subdialog file.

form

audio, catch, error, filled, help, noinput, nomatch, param, property

The subdialog element is a method for reusing common dialogs within an independent application context. The VoiceXML content indicated by the src attribute runs in a new execution context which includes all state information and declarations from the invoking application.

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

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

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

The next attribute specifies the literal URI, or URI fragment of where to transition the caller. The value can be a full URI:

<submit next=”http://MyServer.com/MyFile.vxml”/>

or a relative URI:

<submit next=”MyFile.vxml”/>

In addition, it can also indicate a particular form within the current document, where the pound sign precedes the form item name:

<submit next=”#AnotherForm”/>

Or lastly, it can indicate a specific form in another document:

<submit next=”AnotherDocument.vxml#AnotherForm”>

block, catch, error, filled, help, if

The use of the submit tag will transition control to a new document, either via the GET or POST methods. Dissimilar to the goto element, submit allows the developer to submit a space-delimited list of variables to the destination document.

item, rule

The tag element is another SRGS addition to VWS2.0 that allows the developer to specify an arbitrary string that is used for semantic interpretation. Essentially, what the tag element does is to define the returned value from a valid user utterance.

The event attribute specifies the name of the event to throw 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 throw element, but not both. The event name being thrown is accessible in the catch elements shadow variable _event.

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

The throw element triggers an event which can be caught and handled by using the catch element. Either platform defined events, such as ‘nomatch’, or user-defined events, such as ‘MyCoolEvent’, may be thrown using this tag.

The lang-list attribute specifies the language used in the grammar token, conforming to RFC 1766.

item, rule

The token element defines a word or phrases that may be spoken by the caller in an XML grammar. A token may contain whitespace, (if properly quoted), and may contain uppercase characters as well.

This attribute is currently disabled on the Voxeo network

The aaiexpr specifies an expression that evaluates to the aai data to be sent to the receving application.

The bridge attribute specifies whether or not the outbound call is to be a blind transfer or a bridged transfer. When the value is set to ‘true’, then this indicates that a bridged transfer is intended. A bridged transfer will allow the application to continue to execute when the transfer is completed, whereas a blind transfer will terminate the application once the outbound call has been completed and disconnected. Please note that the usage of blind transfers, or SIP REFER is only available on the hosted network in specific circumstances, and this service requires dedicated telephone resources to be deployed by the customer beforehand. Blind transfers can be used in a local Prophecy deployment in circumstances where the telco provider supports it.

Note: Either the type or the bridge attribute may be specified, but not both.

The connecttimeout attribute specifies the amount of time that the platform will attempt to connect the call, before a ‘noanswer’ event is returned. Note that this element is subject to the strict time syntax, where the time value must be followed by ‘s’ or ‘ms’.

The dest attribute specifies the destination number or URI to transition the caller to. The Voxeo platform supports both the ‘tel’ and the ‘sip’ protocols for outbound dialing:

<transfer dest=”tel:+18002223333”> (absolute syntax)
<transfer dest=”tel:18002223333”> (exact syntax)
<transfer dest=”sip:xxx.xxx.xxx.xxx”> (sip address)

Note that developers who use the non-US datacenters are required to specify an E164-formatted dial string:

tel:+[country code][number]

In addition, the developer can include post dial dtmf input to trigger after the call is connected, by using the following syntax:

<transfer dest=”tel:+18002223333;postd=ppp4444”>

Note that the ‘p’ character indicates a pause between connection and post-dial input from the application; navigation of voicemail systems using the postdial method should be timed carefully using this syntax.

The destexpr attribute allows the developer to specify an ECMAScript expression resolving to the destination of a transfer. Note that either dest or destexpr may be specified, but not both.

The maxtime attribute specifies the duration of the transferred call. By default, this is set to ‘0’, which indicates that the call can last an arbitrary length of time; i.e., until the caller or the callee disconnects.

The name attribute specifies the ECMAScript form item variable name for the transfer. Conditional statements in the filled portion of a transfer are based upon this variable name. See Appendix G for additional information on transferring calls.

The transferaudio attribute is a VXML 2.0 that allows the developer to specify what is played to the caller in place of the default 'ring-tone'. The value of this can be any wav file, assuming that it meets the criteria for a 'playable' file.

The type attribute allows you a method to specify the type of call transfer performed.
On the Voxeo Prophecy hosted platform, if you specify consultation as the value for a transfer, it is not supported, and the transfer is bridged. You can also specify refer as a Voxeo extension that allows a SIP REFER to be performed using telco-dependent support. For more information, see Blind Transfers Sample Application.

Also note that either the type or the bridge attribute may be specified, but not both.

This attribute allows developers to spoof a callerID for an outbound bridged <transfer>. As this attribute is a voxeo-specific extension, it is required that the "xmlns:voxeo" attribute be specified within the <vxml> element, and its value set to the voxeo namespace.

form

audio, catch, error, filled, grammar, help, noinput, nomatch, prompt, property, value

The transfer element is used to transition the caller to another destination. The destination can either be another document, form, or, more commonly, to initiate an outbound call to another phone number.

Note: This tutorial requires the use of outbound dialing priveleges, which must be provisioned by voxeo support. If you have not contacted us to get these permissions, click here to learn how you can get hooked up with this feature.

The expr attribute specifies the ECMAScript expression which evaluates to a string to be rendered by the TTS engine.

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

The value element can be used to insert a variable value for use as a TTS prompt.

The expr attribute denotes the initial ECMAScript expression to be evaluated and assigned to the var name when first invoked.

The name attribute represents the ECMAScript variable name. Valid characters for this value can be letters, numbers, underscores, and dollar signs, but cannot contain any other characters. In addition, the variable name must start with either a dollar sign or a letter, else an error.semantic will be thrown.

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

The var element is used to declare a VoiceXML variable within the scope specified by its parent element. Additionally, variables declared with the var element are accessible from any JavaScript which resides within the script element, providing that they are within the same scope.

The mode attribute specifies the mode of the voxeo:logcontrol element. Acceptable values are either enable, disable, or sensitive.

When the mode attribute is set to:

enable - VoiceXML logging is not limited. This is the default setting, or when the property is not set.
disable - VoiceXML logging is disabled on the MRCP server. In addition, the VSP behavior.calllog.ConfidentialUtterance=true is sent for every set param MRCP message before a recognize MRCP message is sent to Nuance.
sensitive - VoiceXML logging is limited and ALL sensitive data is masked. In addition, the VSP behavior.calllog.ConfidentialUtterance=true is sent for every set param MRCP message before a recognize MRCP message is sent to Nuance.

block

Allows you to control logging, for example turning off logging temporarily when you collect a credit card number. Please remember that you want to use this sparingly, as disabling logging does limit Voxeo Supports ability to troubleshoot any application issues.

The 'info' attribute allows the developer to specify information that is inserted into the resultant recorded wav filename that makes identification easier. Note that ECMA values are NOT supported; (for instance, specifying the 'info' attribute with a value of 'application.MyVar' is not valid). Resultant audio filenames will be in the following format:

AccountID -ApplicationID-SessionID-UserData(Info).wav

As such, a sample file might well look like this:

111-22222-abcdefg1234567abcdefg1234567-MyUserDefinedInformation.wav

The 'infoexpr' attribute allows the developer to specify an ECMAScript expression that is inserted into the resultant recorded audio file name that makes identification easier. Resultant audio filenames will be in the following format:

AccountID -ApplicationID-SessionID-UserData(Info).wav

As such, a sample file might well look like this:

111-22222-abcdefg1234567abcdefg1234567-MyUserDefinedInformation.wav

The 'value' attribute specifies what percentage of calls will be recorded. Setting this value to '100' will record all calls that hit the application, while setting it to '30' will record 3 out of 10 calls that come in. Setting this value to '0' allows the developer to programmatically turn call recording on and off within the application flow

block

The <voxeo:recordcall> element is a proprietary extension to the VoiceXML specification that allows the developer to record both sides of a call, recording the human and the application interaction to a wav file that is stored in the developer's Voxeo File Manager in the 'recordings' subdirectory. On a premise install these recordings will be saved to the voxeo/webapps/www/MRCP/Recordings folder.

The value of the application attribute is a URI used to specify the applications root document. When specified, all event handlers, variables, links, grammars, and scripts contained within the root document are considered active when each document loads. All variables declared within the root document are then considered to have application scope, and are available at any point in the application.

The version attribute represents the VoiceXML version number. Note that specifying the version as '2.1' is required when using the new 2.1 elements, such as the data element.

The xmlns attribute defines the VoiceXML namespace; all tags and attributes belong to this namespace. If specifying the xmlns:nuance attribute in your code, this element will be filled in by default.

The 'xmlns:voxeo' attribute is a required setting that refers to the xml namespace used when a developer includes a voxeo extension element to the VXML specification, (such as <voxeo:recordcall>). This attribute value should always be specified as 'http://community.voxeo.com/xmlns/vxml'

catch, error, form, help, link, menu, meta, noinput, nomatch, property, script, var

The vxml element is the initial declaration that defines a document as a VoiceXML application.