VoiceXML::Client
Home | API | VoiceXML | Download | About
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:
A more general discussion of VoiceXML and its use with VoiceXML::Client can be found on the main VoiceXML page.
assign
Assign a specific value to an existing variable.
- <assign name="mycounter" expr="1" />
- <assign name="myfile" expr="'/path/to/file.rmd'" />
- <assign name="total" expr="somevariable + 5" >
name
Name of variable
expr
Expression to evaluate
The expression is evaluated using the
interpreter, see that section for details.
audio
- <audio src="/path/to/file.rmd" />
- <audio expr="myfilevariable" />
src
A literal string pointing to an audio file of a format usable by your telephony device.
expr
The name of a variable that contains a string pointing to a valid audio file.
block
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.
break
A pause in the speech output.
- <break strength="weak" />
- <break strength="strong" />
strength
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.
clear
Clears out the contents of one or more form item variables.
- <clear />
- <clear namelist="filetoplay invalidcounter othervariable"/>
namelist
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.
disconnect
Indicates that the call should be terminated.
Calls the
telephony device disconnect() method, causes a
return from the user agent's
runApplication().
else
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
/>).
elseif
Optionally used
within (as children of)
if elements.
- <elseif cond="userselection == 3" />
- <elseif cond="invalidcounter > 5" />
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.
exit
Terminate.
End of processing, returns from runApplication().
field
An input item to be gathered from the user.
- <field name="callerselection"> ... </field>
- <field name="rating" type="digits" > ... </field>
- <field name="nextstep" type="digits" numdigits="2" > ... </field>
name
Form item variable that will hold the user input. Name must be unique.
type
The type of field, which is the name of the builtin grammar to use.
numdigits
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.
filled
The filled element specifies a list of children elements that are to be executed when the input item has been filled.
- <filled> ... </filled>
- <filled mode="any" namelist="nextstep callerselection"> ... </filled>
mode
Specifies if all or any of the inputs specified in namelist must be
filled for the action to proceed.
namelist
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.
form
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.
- <form id="mainform"> ...</form>
id
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.
goto
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.
- <goto next="remotescript.cgi" />
- <goto nextitem="anotherformid" />
next
The URI to which to transition using a GET.
nextitem
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.
grammar
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.
mode
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.
if
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.
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:
- elseif
- else
- 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 >).
noinput
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.
- <noinput> ... </noinput>
- <noinput count="3"> ... </noinput>
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" />
</prompt>
<noinput count="1">
<audio src="/path/to/entersomething.rmd" />
<reprompt />
</noinput>
<noinput count="3">
<audio src="/path/to/notworkingout.rmd" />
<disconnect />
</noinput>
<filled>
<assign name="forbox" expr="boxnum" />
<submit next="vxml.cgi" namelist="forbox" />
</filled>
</field>
</form>
</vxml>
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.
count
The minimum number of noinput events to have happened for the field, before the children are executed.
nomatch
The
nomatch element serves to indicate what should be done when user input does not match any of the selections specified in the
grammar.
count
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.
prompt
The prompt controls output of audio to the user.
timeout
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.
record
Record is an input item which collects a voice recording from the caller.
- <record name="myfile.rmd" beep="false" />
- <record name="/path/to/message.rmd" />
name
Name of the recording, in this case the file name to save.
beep
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).
reprompt
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.
return
- <return />
- <return namelist="varone anothervar" />
namelist
List of, space-separated, variable names to return from
the
subdialog.
rule
- <rule id="validinputs" scope="public"> ... </rule>
id
Identification for this rule
scope
Scope, public or private
Only DTMF,
one-of rules are supported for the moment, see the
grammar entry for details.
subdialog
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.
- <subdialog src="#getuserid" />
- <subdialog src="#getpassword" cond="loggedin == 0" />
src
The URI of the subdialog, currently only #internal references are supported, i.e. IDs of forms within the current page.
cond
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?
submit
Submit variables to a document server, retreive and execute the returned vxml.
- <submit next="autoattendant.cgi" />
- <submit next="autoattendant.cgi" namelist="box startidx action" />
- <submit next="autoattendant.cgi" method="post" />
next
The URI to submit data to.
namelist
List of, space-separated, variable names to submit to the server along with the request.
method
Specify whether this should be sent as a get (the default) or post.
var
The var element declares a variable and may optionally assign it a value.
- <var name="invalidcount" expr="0" />
- <var name="filetoplay" />
name
Required name of the variable to instantiate.
expr
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.
Home | API | VoiceXML | Download | About
Copyright (C) 2008, Pat Deegan Psychogenic.com
All Rights Reserved.