Home | API | VoiceXML | Download | About

Supported VoiceXML Elements

Currently, VoiceXML::Client does not support the full Voice Extensible Markup Language specification, but it does enough to allow for some powerful processing and dynamic interaction. The following VoiceXML elements are recognized and supported, at least partially:

assign audio block break clear disconnect else elseif exit field filled form goto grammar if noinput nomatch prompt record reprompt return rule subdialog submit var

A more general discussion of VoiceXML and its use with VoiceXML::Client can be found on the main VoiceXML page.


Assign a specific value to an existing variable.
Name of variable
Expression to evaluate
The expression is evaluated using the interpreter, see that section for details.
Back to list of VoiceXML elements


An audio file to play through the telephony device.
A literal string pointing to an audio file of a format usable by your telephony device.
The name of a variable that contains a string pointing to a valid audio file.
Back to list of VoiceXML elements


A form element, used to group children and set conditions on execution.
In theory, this element supports cond and expr attributes, and it's contents are executed only in the condition or expression is true. Not yet supported, but you can still set those attributes and expect them to function in a future release.
Back to list of VoiceXML elements


A pause in the speech output.
Length of the break. Can be set to none, x-weak, weak, medium, strong or x-strong.
Actual length of break is set by the $VoiceXML::Client::Item::Break::StrengthToSeconds hash.
Back to list of VoiceXML elements


Clears out the contents of one or more form item variables.
Space seperated list of the names of the variables to clear
When called with no namelist attribute, the clear tag should clear all form variables. This is not yet supported, no action is performed in this case.
Back to list of VoiceXML elements


Indicates that the call should be terminated.
Calls the telephony device disconnect() method, causes a return from the user agent's runApplication().
Back to list of VoiceXML elements


Optionally used within (as children of) if elements.
If none of the if or elseif conditions evaluated to true, tags between the else and closing if will be executed. Note that this is a unary tag (needs it's closing slash, <else />).
Back to list of VoiceXML elements


Optionally used within (as children of) if elements.
Condition to be evaluated by the interpreter.
If the if condition evaluated to false and the elseif condition turns out to be true, the tags between the current elseif and the first of the next elseif or closing if will be executed. Note that this is a unary tag (needs it's closing slash, <elseif cond="..." />) and it must have a cond set.
Back to list of VoiceXML elements


End of processing, returns from runApplication().
Back to list of VoiceXML elements


An input item to be gathered from the user.

Form item variable that will hold the user input. Name must be unique.
The type of field, which is the name of the builtin grammar to use.
Non-standard extension implemented for digits type. Specifies the number of digits to expect from user.

Currently, only digits type fields are supported, though other types are expected to be implemented (e.g. boolean, date, etc.), and only as DTMF input. A variable of the same name as the field is automatically created. Whatever the caller actually enters when the filled item is reached is set as the value of this variable.

In theory, it should be possible to fill field elements with spoken input in which case using the associated field variable in an expr would actually play the recorded sound file. This is not supported in the current release.

Back to list of VoiceXML elements


The filled element specifies a list of children elements that are to be executed when the input item has been filled.
Specifies if all or any of the inputs specified in namelist must be filled for the action to proceed.
Space seperated list of the names of the variables names.
In the current implementation, the field's detection of a child filled item is actually what triggers a readnum() call on the telephony device handle, and for the moment, mode and namelist are ignored.
Back to list of VoiceXML elements


Key components of the VXML page, forms contain items to be filled and actions to perform once those fields have been filled. A VoiceXML page may contain many form items, and they will normally be entered in page order, though the logic within the page can direct the user to hop between form in arbitrary order.
The identification for the form, used to reference the form within the document for instance in <goto next="#mainform" />.

Forms are normally entered only once, in the order they appear in the page, unless explicit jumps are executed (e.g. with a goto). However if, for instance, the caller proceed through form 1, 2 and 3 and is then thrown back to form 1, forms 2 and 3 will be skipped before proceeding to the fourth form on the page since they have already been processed.

This is accomplished by automatically creating and setting a variable with the name formVar_FORMID for each form (replacing FORMID with the actual form id attribute. If you hope to jump back to form 1 and reprocess forms 2 and 3 you'll have to either explicitly jump between the forms using gotos or clear the appropriate formVar_* variables before jumping.

Back to list of VoiceXML elements


Though some have considered goto harmful, VoiceXML specifies that this element can be used to transition between forms on the same page or to another VXML page altogether. It is quite useful in controlling the flow of the call.
The URI to which to transition using a GET.
The name of the next form item to visit in the current page.
Exactly one of next or nextitem must be specified. Interpreted attributes, expr and expritem are similar and should be supported in the near future.
Back to list of VoiceXML elements


VoiceXML grammars are powerful, complex and... not really implemented yet. However, VoiceXML::Client does support limited DTMF grammars that allow for easy use of the nomatch items that can do a lot to alleviate boring vxml coding.
The mode of the grammar following the modes of the W3C Speech Recognition Grammar Specification. Only dtmf currently supported
The above example is the only form of grammar and rule currently supported. It specifies which DTMF entries will be accepted as valid here (1, 2, 3 and 0 in the example). This is useful in conjunction with the nomatch element.
Back to list of VoiceXML elements


The if element is used for conditional logic, to control the caller's flow within the VoiceXML page. It is, along with it's optional children--elseif and else--a powerful tool to use in creating dynamic pages that react to caller input.

Condition to be evaluated by the interpreter.

The cond attribute is required. If the interpreted conditional is true, items that are children of the if will be executed until the first of:

  1. elseif
  2. else
  3. closing if tag, </if>

is encountered. Note that the conditional statement must be encoded, such that you don't wind up with invalid XML (e.g. a > character must be represented as &gt;).

Back to list of VoiceXML elements


The noinput element is used in a form field to describe actions to perform when no user input is received for a field. Multiple noinput items can be present, with different count attributes, to specify different actions to perform after a certain number of timeouts.
Here's a more complete example, to put noinput in context:
<?xml version="1.0" ?>
<vxml version="2.1">
	<form id="restrictedbox">
		<field name="boxnum" type="digits" numdigits="3">
			<prompt timeout="10s">
				<audio src="/path/to/enterboxnum.rmd" />

			<noinput count="1">
				<audio src="/path/to/entersomething.rmd" />
				<reprompt />
			<noinput count="3">
				<audio src="/path/to/notworkingout.rmd" />
				<disconnect />

				<assign name="forbox" expr="boxnum" />
				<submit next="vxml.cgi" namelist="forbox" />
In the example above, the prompt is played and will timeout after 10 seconds if nothing is entered by the caller. The first (and second) time this happens, the entersomething message is played and the caller is reprompted for input. The third time (count = 3), we give up and disconnect.
The minimum number of noinput events to have happened for the field, before the children are executed.
Back to list of VoiceXML elements


The nomatch element serves to indicate what should be done when user input does not match any of the selections specified in the grammar.
The minimum number of nomatch events to have happened for the field, before the children are executed.
Note that for the system to know what the caller input is supposed to match against, the possible entries must be specified using a grammar.
Back to list of VoiceXML elements


The prompt controls output of audio to the user.
Time to wait for user input, may be specified in seconds (using the s suffix, e.g. 10s) or milliseconds (using the ms suffix, e.g. 3400ms).
The VoiceXML specification gives the prompt item a lot more power than is available here at the moment. Attributes such as cond and count are defined to allow you to control when prompts are played and it is meant to specify the output of automatically generated synthesized speech. Neither of these are yet available with VoiceXML::Client, though our own requirements and client demand may encourage us to support both shortly.
Back to list of VoiceXML elements


Record is an input item which collects a voice recording from the caller.
Name of the recording, in this case the file name to save.
Specifies whether an audible beep should be played, using true or false. Defaults to true.

The recording name must be specified. The beep attribute defaults to true. The actual operations of beeping and recording are handled by the telephony device, through calls to its beep() and record() methods.

The tone and length of the beep are set by the $VoiceXML::Client::Item::Record::BeepFrequency (in hertz) and $VoiceXML::Client::Item::Record::BeepMilliseconds variables (defaulting to 400Hz and 1000ms respectively).

Back to list of VoiceXML elements


Reset everything and reprompt the user as if the form hasn't yet been visited.
See the if and noinput tag examples to see reprompt in action. Note that this currently starts over at the top of the current form and not the field as it probably should--workaround if this is what you need is to separate fields into distinct forms.
Back to list of VoiceXML elements


Return control from a subdialog.
List of, space-separated, variable names to return from the subdialog.
See subdialog for details.
Back to list of VoiceXML elements


A grammar rule.
Identification for this rule
Scope, public or private
Only DTMF, one-of rules are supported for the moment, see the grammar entry for details.
Back to list of VoiceXML elements


The subdialog element invokes a 'called' dialog (known as the subdialog) identified by its src, similar to a function call. Consider support for this experimental.
The URI of the subdialog, currently only #internal references are supported, i.e. IDs of forms within the current page.
An optional attribute specifying a condition that must evaluate to true for the subdialog to be called.
If you find yourself typing the same field and validation over and over, you might try using a subdialog. Make sure to include a return element. Also, nesting subdialog calls may be buggy. For the moment, variables manipulated in a subdialog are global in scope, which probably isn't right. Did we mention this was still experimental?
Back to list of VoiceXML elements


Submit variables to a document server, retreive and execute the returned vxml.
The URI to submit data to.
List of, space-separated, variable names to submit to the server along with the request.
Specify whether this should be sent as a get (the default) or post.
Back to list of VoiceXML elements


The var element declares a variable and may optionally assign it a value.
Required name of the variable to instantiate.
Optional expression to interpret and assign to the variable.
Unless expr is specified, the variable remains undefined until explicitly assigned a value using an assign tag.
Back to list of VoiceXML elements

Home | API | VoiceXML | Download | About

Copyright (C) 2008, Pat Deegan Psychogenic.com
All Rights Reserved.