- What is VoiceXML?
VoiceXML is a W3C standard for building interactive voice
applications, and is a vendor-independent technology. VoiceXML
integrates seamless with your existing web technologies. VoiceXML
applications allow you to:
- Play vocal prompts and audio messages to users.
- Accept numeric key tones from users (phone DTMF).
- Accept voice input and recognize the words.
- Record user voice input.
- Send user collected input to an internet server.
- Retrieve data from a server and return it to the user.
- Execute simple call control operations like transfer and
disconnection.
- Integrate multiple speech and telephony related technologies
like:
- Automated Speech Recognition (ASR)
- Text-to-Speech Synthesis (TTS)
- DTMF (telephone key tones)
See also http://www.eloquant.com/en/more01.html
- How does a VoiceXML application work?
VoiceXML pages describe the interaction with a caller. When
the user phones the VoiceXML gateway, the VoiceXML gateway
takes care of the interaction with the user. The VoiceXML gateway
requests the VoiceXML pages and possible audio files from the
Web Server. The VoiceXML gateway offers various services like
Automatic Speech Recognition and Text To Speech. We also use
the name VoiceXML browser to indicate the VoiceXML gateway.
The name VoiceXML browser is used as an analogy to an HTML
browser, except that it interprets VXML code producing audio
feedback to you output device e.g. a telephone, rather than
visual HTML feedback to your Internet browser. VoiceXML applications
can offer an alternative to web browser access, and integrates
seamlessly with your existing web services, without too much
development costs.
- How can I learn about VoiceXML?
There are many websites which teach you about the VoiceXML
syntax. The W3C standard is a precise way to find out about
the correct syntactical use of the VoiceXML tags. See http://www.w3.org/TR/voicexml20/.
Eloquant offers various training courses, both for developers
and for managers. See http://www.eloquant.com/en/prod_formation.html for
more information.
- What proprietary extensions to VoiceXML
are offered by Eloquant?
The Eloquant VoiceXML browser adheres to the standard VoiceXML
2.0. However, Eloquant does offer various useful extensions
and application components which are ready to use in your applications:
- Outcall, to make outgoing calls, see How
can I make outgoing calls?
- Additional ISUP session variables, see: How
can I discover the calling phone number?
- Configuration parameters to personalize your log files,
create your own log files etc. Ask developer-support@eloquant.com for
more information.
Eloquant also offers application components in the form of <subdialog>s,
easy to integrate with your VoiceXML code. Ask developer-support@eloquant.com for
more information.
- Component to manage a phone conference among participants.
- Component to send email.
- Component to send an SMS.
- Component to send a FAX.
- SayNumber, a component which reads out numbers in various
ways.
- SayTime, a component which reads out the time.
- FileAccess, a component which offers file access, to read
from and write to files.
- What is DTMF?
DTMF (Dual Tone Multi Frequency), is a protocol used in
telecommunications to decipher the keys pressed on a phone’s
keypad. This is the traditional way to navigate between options,
e.g. “Type 1 to be connected with the sales department. Type
2 to be connected with technical support.”
- What is ASR?
Automatic Speech Recognition (ASR) is a technology that
recognizes spoken words based upon a predefined set of words.
ASR provides an alternative to keypad input (DTMF), and can
provide more direct navigation in automated menus. Instead
of asking the caller to type an endless range of numbers,
speech recognition can be used. This will provide a more
friendly environment for the user, who is less likely to
hang up before his call is correctly serviced. VoiceXML offers
a seamless integration for applications who offer both keypad
navigation and navigation directed by natural language. An
example would be, “Of which skiing resort in the French Alps
would you like to consult the snow conditions?”. The caller
would reply “Les Deux Alpes”, and the snow conditions can
be read out to him.
- What is TTS?
Text To Speech (TTS) is the vocalisation of text. Any prompts
in your VoiceXML page can use a speech synthesiser, which
reads out the text to the caller. TTS is configurable in
VoiceXML, e.g. you can configure the chosen language. The
same VoiceXML page can use prompts in different languages.
For example:
<prompt xml:lang=”en”>Hello, for English type 1</prompt>
<prompt xml:lang=”fr”>Bonjour, taper 2 pour le français</prompt>
Deployment
- How to integrate VoiceXML with
my existing applications and web server?
VoiceXML pages can be placed on a web server and have a
URL like a plain HTML page. A VoiceXML application is accessed
by phone, the voiceXML pages are served to the caller by
Eloquants VXML Gateway on our Elodia platform. You have to
change your webserver to generate VoiceXML pages. See also
the FAQ How does a VoiceXML application
work?
- How can I set my developer account
to use a particular page?
In the default setup you will find a file vxml.properties
with the line:
interpreter.service.addressList.myapp = *
This line indicates that the system must read the
file vxml-myapp.properties for the default configured phone
number for your service.
In the file vxml-myapp.properties, the following line indicates the first
VoiceXML page which is going to be played:
So if you want the file myNewTestService.vxml to be played,
the only thing you would need to do is to change the line
above to:
# The service's initial URL
service.URL=file:///var/opt/vxml/services/myNewTestService.vxml
If you want to personalize your property pages, for example,
you have more than one telephone number configured for your
service, you could configure your phone number(s), (without
the leading zero) in the file vxml.properties.
interpreter.service.addressList.testservice = 123456789
This line indicates that the system must read the file vxml-testservice.properties
when receiving a call for the phone number 01 23 45 67 89.
In the file vxml-testservice.properties, the following line indicates the
first VoiceXML page which is going to be played:
- What are the differences between
deploying my VoiceXML service during my development and
production phase?
You will configure your VoiceXML environment slightly different
during your development phase than during your stable production
phase. The differences include:
- During the development phase you usually disable caching.
During the production phase you should enable caching and
set the appropriate caching parameters. See What
is caching and how to enable caching?
- During the development phase you can augment the level
of logging to all to be able to troubleshoot your application.
During the production phase you should reduce logging to
error only. See How can I view the log
files of the VoiceXML browser?.
- Notify Eloquant's operational team with an indication
of estimated traffic so that we monitor your service and
ensure necessary resources are available during your production
phase.
- During the development phase it is advised to enable
schema checking. During the production phase you should
disable schema checking, See How can
I enable or disable schema checking?
- How to deploy VoiceXML applications
using TTS?
When you developed your service and you you want to use
TTS, you must ensure that your production environment allows
the use of TTS. If not, get in touch with sales@eloquant.com to
subscribe for this option. Otherwise you must change your
service to use recorded audios instead.
- Why are the changes of my VoiceXML
pages not taken into account?
The first thing to check is your caching configuration,
see What is caching and how to enable
caching? And How to disallow caching
of a specific file?.
- What is caching and how to enable
caching?
Caching is used by the VoiceXML gateway to keep files in
memory, so that they need not to be retrieved from a web
server the next time they are needed. This saves resources,
and makes access to the cached files quicker. For example,
the first time the VoiceXML gateway needs to load a large
audio file, the caller will hear a slight delay before the
audio can be played. The second time when the large audio
file is cached, the caller will not be able to discern any
delay.
Refer to the section Resource Fetching of the VoiceXML standard: http://www.w3.org/TR/2004/PR-voicexml20-20040203/#dml6.1.
To enable caching for your service, set the cache.enabled
property in the vxml.properties file.
Caching can be enabled for individual VoiceXML files by using the properties
documentmaxage, documentmaxstale or the attributes maxage and maxstale. For
audio files you must use the properties audiomaxage, audiomaxstale or the
attributes maxage and maxstale.
For the detailed caching algorithm see http://www.w3.org/TR/2004/PR-voicexml20-20040203/#dml6.1.2.
To summarize the use of the caching properties and attributes:
- Use the properties documentmaxage and documentmaxstale to
cache VoiceXML documents (forms, links, subdialogs, grammar files, etc..).
- Use the properties audiomaxage and audiomaxstale to
cache audio files.
- Use the properties scriptmaxage and scriptmaxstale to
cache script files.
- The maxage/maxstale attribute tells the VoiceXML interpreter
the maximum allowed age of a given resource before a resource is re-fetched.
The use is equivalent to the HTTP1.1 maxage parameter.
For example: if the age of doc.vxml is less than 1800 seconds, a cached version
of doc.vxml can be used. Otherwise the document will be retrieved from the
given URL:
<goto maxage=“1800s“ maxstale="0s" next=“http://srv.com/doc.vxml“/>
The properties in point one to three can be defined at the outer-most scope
within a vxml document. They allow to set document wide caching parameters.
The attributes in point four are to be used for specific VoiceXML elements
(in the tags: goto, link, grammar, script, audio, submit or subdialog). The
scope is applicable to the document referenced by that element.
For example, the audio file currentTime.wav will never be cached in the next
example:
<?xml version=“1.0”?>
<vxml xmlns=“http://www.w3.org/2001/vxml” version=“2.0”>
<property name=”audiomaxage” value=”86400s”/>
<property name=”audiomaxstale” value=”86400s”/>
<form id=”start”>
<block>
<prompt><audio src=”welcome.wav”/></prompt>
<prompt><audio maxage=”0” maxstale=”0” src=”http://srv/currentTime.wav”/></prompt>
</block>
</form>
</vxml>
- How to disallow caching of a specific file?
To disallow caching of a specific VoiceXML file or a specific audio file
you must set the maxage property or attribute to 0.
Example: doc.vxml with maxage and maxstale set to 0 seconds, will not be
retrieved from the cache:
<goto maxage=“0s“ maxstale = "0s" next=“http://srv.com/doc.vxml“/>
- What is prefetching and when to
use it?
The audio tag has an attribute fetchhint which can be set.
See: http://www.w3.org/TR/2004/PR-voicexml20-20040203/#dml6.1.
The attribute fetchhint defines when the interpreter context should retrieve
audio contents from the server. The value "prefetch" indicates
that an audio file may be downloaded at the same time when the vxml page
is loaded. The value "safe" indicates that an audio file should
only be downloaded when actually needed. If no attribute is specified,
a value derived from the innermost relevant fetchhint property is used.
The default value for Eloquant’s VoiceXML gateway is prefetch.
Resource prefetching:
- Allows parallelization of resource fetching: documents
can be loaded before their content is needed.
- Reduces user’s waiting time. However, resource prefetching
should be avoided
- With a submit because the returned result may depend
on the parameters.
- When a URL is computed with an "expr" attribute.
An example:
<form id=”start”>
<var name=“id” expr=“0”/>
<field name=”yourId” type=”digits”>
<prompt><audio src=”welcome.wav”/></prompt>
<prompt><audio fetchhint=”prefetch” src=”tellYourId.wav”/></prompt>
<filled>
<assign name=“id” expr=“yourId”/>
<goto fetchhint=”safe” expr=”id+’.vxml’”/>
</filled>
</field>
</form>
- How do I avoid delays to load large audio files?
There are two options available to ensure that audio files are cached
and accessible by the VoiceXML Gateway, even before a first VXML file has
been played. Using one of these options has the advantage that you do not
need to repeatedly specify the fetchhint and maxage properties.
- If you are dealing with a small amount of data, you can use a well
defined HTTP API to load your files in the cache of the VoiceXML Gateway.
Contact us if you want to learn about the API.
- If you are dealing with a large amount of data (10 MB till 10 GB),
you could use an FTP server which is hosted at Eloquant’s premises. The
FTP server guarantees that your (audio) files can be accessed by the
VoiceXML gateway almost without any delay. You can control the content
of your cache containing your (audio) files by using our well defined
FTP or HTTP interface. If you want to use this facility contact our sales
department (sales@eloquant.com).
- The French speech synthesis (TTS)
does not work, what am I doing wrong?
The most likely reason is that you did not set the xml:lang
attribute in your <vxml> tag:
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" xml:lang="fr">
To achieve a global setting, for all your VoiceXML applications, or for a
specific VoiceXML application, you could also set the property attribute.vxml.locale
in the appropriate .properties file:
# Set default for xml:lang attribute of <vxml> element
attribute.vxml.locale = fr
- How can I make sure that the error messages are
in French instead of in English?
Set the xml:lang attribute in your document:
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" xml:lang="fr">
Alternatively set the property attribute.vxml.locale in the vxml.properties
file or your service specific .properties file:
# Set default for xml:lang attribute of <vxml> element
attribute.vxml.locale = fr
- How can I enable or disable schema
checking?
Schema checking is checking the compliance of the VoiceXML
document before the execution of the document. This is useful
during your development phase. Still better is to use an
XML editor which performs schema validation, see also How
can I troubleshoot my application?
The VoiceXML gateway performs schema checking by default.
The developer’s VXML file is verified against the schema
definition. During development you should always use schema
checking. The log files will contain an error message if
your VoiceXML code is not correct. To improve the performance
of the VoiceXML Gateway you can turn off schema checking
when your service is in production. By then you must be sure
that the VoiceXML is syntactically correct.
To disable schema checking, set in your vxml.properties file:
Logfiles and errors
- How can I view the log files of the
VoiceXML browser?
The VoiceXML browser has various levels of logging. You
can set the level of logging for various parts of the browser,
we will call them blocks. The default settings which can
be found in the file ttl.properties on the OSS should be
appropriate for your development account.
To view the logs, use the OSS webpages. Go to your VoiceXML browser service
subscription, and click on the file system icon. Browse to the directory
/var/tmp/vxml/log, and you can view the various log files of the browser.
There are three different types of log files:
- The application_log_<serviceId> file. This log
file contains all application <log> outputs for the
given serviceId.
To set the level of the traces for this log file, set the following
line in the file ttl.properties, for example:
log.block.traceon.application_log = all
or:
log.block.traceon.application_log = none
- The exec_log_<serviceId>.<date/time> file.
This log file contains the debug traces for one session,
i.e. one phone call. This log file is meant to be the
first log file for vxml developers to look at when
they encounter a problem while developing their application.
This log file contains traces of three different blocks,
application_exec, application_log and resource_req.
The application_exec traces are generated by our platform
and aimed at application developers.
The application_log traces consists of the application's <log> outputs.
The resource_req block contains all traces related to resource requests.
For example you might discover that a certain HTTP request has failed
by reading those traces.
To set the level of the traces for this log file, you have
to set a combination of the following line in the file ttl.properties,
for example:
log.block.traceon.exec_log = all
log.block.traceon.application_log = error,warning
- The session_log_<serviceId>.0/1 file. This log
file contains all traces for the given service, this file
logs the traces of the blocks: interpreter_context, interpreter_core,
device_mgr, cache_mgr, network_fetcher, doc_parser, resource_req,
application_log. The complete traces are normally not meant
to be read by the Vxml developer. However, if you want
to report a problem to Eloquant's developers support, it
is useful to send them the session log. See the question "How
can I ask help from Eloquant's developer support?".
In addition refer to section 3.2 “Set up Trace and Log
Levels” of the VXML_DevelopersGuide2.
- How can I troubleshoot my application?
If your VoiceXML application does not do what you expect,
you have to troubleshoot your application. The first thing
to do is verify that your VoiceXML is valid. You can do this
for example with an XML editor which performs schema validation
while you edit your XML, e.g. XMLSpy. Otherwise you can enable
schema checking on our platform, see How
can I enable or disable schema checking?.
Look at the logfiles of your VoiceXML application (see How
can I view the log files of the VoiceXML browser?).
Once you have set the correct levels for your log file,
look at the latest exec_log file to see whether it displays
the problem, the error messages are displayed in red. If
not, you might be able to follow the execution sequence,
and discover what is going wrong.
- How can I ask help from Eloquant's
developer support?
If you encounter a problem during your VoiceXML development,
you can ask help. Send an email to developer-support@eloquant.com.
In this email you should include the following:
- A clear description of your problem and how to reproduce
it.
- Provide us with the corresponding exec_log and session_log
traces. (Remove all your log files from the OSS, make a
phone call which traces your problem, and download the
new log files). You can attach the log files in .zip format
to your email.
- “An error has occurred. This call
will be terminated”. What shall I do?
This type of error is most often encountered during VoiceXML
development. Usually the vxml code contains an execution
error.
- “Failed to access page. This call
will be terminated”. What shall I do?
This type of error is often encountered when a vxml page
can not be found or is not parseable (i.e. contains a vxml
syntax error). If this happens for your root vxml page, verify
that your Http connection is alive, and that your first page
is set correctly. See: How can I set my
developer account to use a particular page? and How
can I enable or disable schema checking?
Make sure that you have a default event catcher at the highest level. See What
are the most common errors in a VoiceXML application?
- “Infinite loop prevention mechanism
triggered. Max number of FIA cycles without user interaction
reached”. What shall I do?
When you encounter this log message, the vxml document made
too many transitions without user interaction. The VoiceXML
gateway has this feature to prevent infinite loops triggered
by transitions.
For example, two blocks requesting endlessly <goto> to
each other or an event thrown and caught endlessly. A more
complicated example is a document which makes heavy use of
subdialogs to queue prompts dynamically based on the content
of ECMAScript variables, this results in a large number of
transitions without collecting user input. Such a document
is making excessive use of client-side computation support
and should be modified to have a dynamic VXML page be generated
by a web server and queue the necessary prompts in a single <prompt> element
without the need for transitions to emulate a loop construct.
- What are the most common errors in
a VoiceXML application?
One of the most common problems with a VoiceXML application
is that the pages do not contain (enough) error handling
in case the caller does not reply (<noinput>), or gives
an unexpected reply (<nomatch>).
Another frequent problem is that the root document does not contain the
generic <error> tag to treat all unexpected technical problems. It is
better to have a polite way to disconnect the call, e.g. in case an HTTP
request for a certain vxml file failed. Otherwise the caller would hear
a default prompt and not understand what has happened.
For example, place the <catch> tag in your root vxml document:
<catch>
<prompt xml:lang="en">
<audio src="file:///var/opt/vxml/services/myservice/errorMessage.wav"/>
</prompt>
<log label="level.error">
Caught event <value expr="_event"/> with message
<value expr="(_message!=undefined)
? _message : 'undefined_value' "/>
</log>
<disconnect/>
<
/catch>
Make sure to add a disconnect tag in your <catch>,
to make sure that you avoid infinite loops.
VoiceXML Programming
- How to learn more about VoiceXML?
If you are new to VoiceXML it can be difficult to develop
your application. If you are an experienced programmer, you
might start by reading a tutorial on the web, a book or look
at the standard: http://www.w3.org/TR/voicexml20/.
To get you started in an efficient way, Eloquant offers
training courses. They teach you how to develop your VoiceXML
applications, and how to use our platform. Contact sales@eloquant.com,
or look on our website http://www.eloquant.com/en/prod_formation.html.
- How to get help to design and
implement my VoiceXML application?
If you have no resources to develop your VoiceXML application
yourself, Eloquant can develop your application for you.
Contact sales@eloquant.com to
discuss your requirements with us, so we can propose you
a solution appropriate to your business.
- How can I record messages in VoiceXML?
VoiceXML allows you to record messages, and you can even
play them back. A simple vxml example to record a message
is:
<?xml version="1.0">
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form>
<record name="msg" beep="true" maxtime="10s" finalsilence="4000ms" dtmfterm="true"
type="audio/x-wav">
<prompt>
<audio src="recordYourMessageAfterTheBeep.wav" />
</prompt>
</record>
</form>
</vxml>
See also the W3C standard: http://www.w3.org/TR/voicexml20/#dml2.3.6.
- How can I retrieve or use the
recorded audio files in VoiceXML?
VoiceXML allows you to play back recorded messages, or
submit them to your web server. We can add the following <field> to
the <form> in the previous example to play the message
to the caller and submit it to a web server:
<field name="confirm">
<prompt>
Your message is <audio expr="msg"/>.
</prompt>
<prompt>
To keep it, type 1. To discard it,
type 2.
</prompt>
<option dtmf="1"/>
<option dtmf="2"/>
<filled>
<if cond="confirm=='1'">
<submit
next="save_message" enctype="multipart/form-data"
method="post" namelist="msg"/>
</if>
<clear/>
</filled>
</field>
- How can recorded messages be sent
by email?
You can send your recorded messages by email. VoiceXML
is inherently open to the Internet. Therefore, information
collected by a VoiceXML application, including recorded messages,
can be transmitted in a secure manner to whatever application
server on the Internet or company extranet, including mail
servers. Eloquant provides VoiceXML components, in the form
of subdialogs, that can be easily be integrated to your VoiceXML
application to add email facilities to your voiceXML applications.
Contact us to learn more about the possibilities. See also What
proprietary extensions to VoiceXML are offered by Eloquant?
- What audio file formats are supported?
Audio files in the format of 8 khz, 8 bit mono are supported,
see the standard http://www.w3.org/TR/voicexml20/#dmlAAudioFormats.
Eloquant supports the formats both in a 8 bits version and
16 bits version.
In addition, Eloquant also partially supports the format
Speex. The speex codec allows a level of compression between
5 and 22, and can be suitable if you want to record the user's
input. See http://www.speex.org/.
To use the speex format, you must specify the type="audio/x-speex-ocmp
in the <record> tag, which will record your audio in
a compressed 8kHz mono, 16 bits lineair speex format:
<record name="data" modal="true" dtmfterm="true" type="audio/x-speex-ocmp">
<prompt>Start record.</prompt>
</record>
The speex format is not suitable for music, but we hope
to support a suitable format for music in the near future.
- How can I make outgoing calls?
Outbound calls are not specified in VoiceXML, but Eloquant
does offer this facility. Eloquant’s VoiceXML browser adds
additional functionality which let you make an outbound phone
call from your VoiceXML service. The outbound call can be
initiated by a plain HTTP request which offers the possibility
to automate outbound calls. This facility is for example
very useful for tele-marketing campaigns, where a list of
phone numbers is called automatically. Another possible application
is to use it to generate alerts or alarms. Contact us to
learn more about this facility.
- Does VoiceXML allow call transfers?
Yes, VoiceXML allows call transfers. However, to make use
of this feature, your account needs to be enabled to make
call transfers. Contact us to enable call transfers. A simple
example is:
<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form id="form0">
<transfer dest="tel:0033476774692" name="transfer">
</transfer>
</form>
</vxml>
- What is ECMAScript?
The ECMAScript standard is a Web scripting language that
can enrich and enliven Web pages in a Web browser. ECMAScript
is based on the ECMA-262 specification, which outlines an
object-oriented programming language for performing computations
and manipulating objects within a host environment, such
as the browser. For the complete ECMA-262 specification,
see http://www.ecma-international.org/. The ECMAScript standard
was based on JavaScript. See also Is it
recommended to have lots of scripting in my VoiceXML application?
- Is it recommended to have lots
of scripting in my VoiceXML application?
It is not recommended to have too much scripting in your
VoiceXML application. For every service a clear decision
should be made what functionality is placed on the server
side, and what functionality is best added on the client
side with ECMAScript. While programming in VoiceXML, you
should keep in mind that VoiceXML is primary an interaction
language and not a programming language. Therefore, the use
of ECMAScript should be limited to user input validation
and simple computations. If you need more computation power
(or array storing size), you need to change your application
architecture so that the computation is done at the server
side (running a compiled application e.g. using Java). The
result can then be returned by dynamic VoiceXML pages. Remember
that a call to java method (performed on a web server) can
be much faster (typically 100 times) than calling a script
function within a VXML script.
When making an analogy with HTML, it is preferred to have
dynamically-generated small HTML pages (generated by a server)
than a large HTML file over-loaded with interpreted scripts.
Scripting in a vxml page makes its (re-)loading and execution
slower and CPU-expensive.
The difference with the HTML analogy is that while each HTML session is
running on a different machine (i.e. the desktop with Internet Explorer),
all the VoiceXML sessions run on the same host (the VoiceXML gateway that
runs your VxmlBrowser account). This obviously makes too much scripting
absolutely not recommended in VoiceXML.
The VoiceXML gateway has a built-in limit related to the amount of ECMAScript
expressions to protect it from pages using an excessive amount of scripting.
It makes no sense to make this limit higher, because reaching the limit
means that your VoiceXML application will not scale (in terms of simultaneous
calls) and will not be performing once deployed.
See also What is dynamic VoiceXML?
- What is dynamic VoiceXML?
VoiceXML pages are served by a web server. If a VoiceXML
page contains parts which are dynamically generated, we speak
about dynamic VoiceXML. An example is a banking application,
where the balance of an account is read out to a client.
Techniques to generate dynamic VoiceXML are Php, JSP, Servlets,
ASP etc. In general you application should ensure that dynamic
pages are not cached. See What is caching
and how to enable caching?
- How can I discover the calling
phone number?
VoiceXML offers various session variables. If the caller
presents his phone number, the variable session.connection.remote.uri
is a URI which addresses the remote caller device. However,
for various reasons, the calling phone number can be hidden
or not be completely correct:
- People phoning from behind a PABX will display the general
standard's phone number.
- Depending on network incompatibilities, the calling phone
number will not be known in the session, e.g. for international
or mobile callers.
See the VoiceXML standard: http://www.w3.org/TR/2003/CR-voicexml20-20030128/#dml5.1.4
If you want to access more information about the origin
of your call, ask developer-support@eloquant.com for
the ISUP documentation, which explains how ISUP fields can
be retrieved in your VXML code. (This is an extension to
the VoiceXML standard).
Note that the use of the caller's phone number may be restricted
legally depending on the country of origin. In particular,
even if the caller has "masked" their number then
it will still be presented to the VXML service, but it
should be used for billing reasons only, or for opt-in services.
In order to know if the caller masked their number, a proprietry
variable is provided by Eloquant : session.connection.remote.pi
(Presentation Information), which has the value of "Allowed" if
the caller has not requested masking. The developer and operator
of the service is responsible for ensuring that their application
corresponds to the legal requirements in force.
- Why does Session.telephone.ani
not work?
Session.telephone.ani is a session variable which is implemented
in the standard VoiceXML 1.0. In VoiceXML 2.0 the session
variable is changed to session.connection.remote.uri. See
also How can I discover the calling phone
number?
- How can I implement a loop in VoiceXML?
You can write loops in VoiceXML by using variables and
a clever use of the <clear> tag to make that your form
items are re-visited.
For instance, to say all numbers from 1 to 50:
<var name=”counter” expr=”1”/>
<var name=”max” expr=”50”/>
<field name=”loop” cond=”counter != max”>
<prompt> This is loop number <value expr=”counter”/></prompt>
<assign name=”counter” expr=”counter+1”/>
<clear namelist=”loop”/>
</field>
However, refer also to Is it recommended
to have lots of scripting in my VoiceXML application?.
In most cases the fact that you need a loop in your VoiceXML
indicates that your VoiceXML is too complicated, and that
you are doing too much on the client side. Consider an
architecture of your application where you implement the
loop on the server. See What is dynamic
VoiceXML?
- How can I perform post-call processing?
In your vxml document, catch the event connection.disconnect.hangup:
<event connection.disconnect.hangup>
In this event you can clean up your connection, and use
tags like <submit> or <log>. Having a <prompt> tag
will not make any sense, because the caller did hang up and
will not hear the prompt anymore. However, take care, there
are cases that your disconnect event handler will not be
called. See the question Why is my connection.disconnect.hangup
handler not called?
- Why is my connection.disconnect.hangup
handler not called?
The fact that your connection.disconnect.hangup handle is
not called when you were expecting it, can be very confusing
at first. The problem is related to the Form Interpretation
Algorithm (FIA), the state machine which interprets your
vxml. The FIA can be in one of the two states, WAITING or
TRANSITIONING. In the WAITING state, the FIA is waiting for
input or an input item, such as <field>, <record> or <transfer>.
The TRANSITIONING state encompasses the process and select
phases, the collect phase for control items (such as <block>s),
and the collect phase for input items up until the point
at which the interpreter waits for input. (see the standard
on http://www.w3.org/TR/voicexml20/#dml4.1.8).
Asynchronously generated events (e.g. connection.disconnect.hangup)
not related directly to execution of the transition are buffered
until the waiting state.
The last phrase explains exactly why it can happen that
the hangup handler is not called. If the FIA does not return
any more into the WAITING state, but ends, the event is lost,
and your hangup handler will never be called.
The question to answer is, how can this happen, and how
to avoid it. To illustrate this, look at the difference
between the following VoiceXML application, and the same
vxml application where the <exit/> is changed into
a <disconnect/>. The difference is shown in case the
caller hangs up during a prompt. In the case shown below,
i.e. with an <exit/> tag, when the caller disconnects,
the FIA will not return to the WAITING state anymore, and
the event handler for connection.disconnect.hangup will not
be called. If we change the <exit/> tag to a <disconnect/> tag,
the FIA will return into the WAITING state, and the bufferised
hangup event will be processed by the event handler in the
secondDoc.vxml. Removing the <exit/> tag altogether,
i.e. using an implicit exit, will show the same behaviour
as using the <exit/> tag.
<?xml version="1.0" encoding="ISO-8859-1"?>
<vxml xmlns="http://www.w3.org/2001/vxml" version="2.0" xml:lang="en-EN">
<catch event="connection.disconnect.hangup">
<log>Caught <value expr="_event"/> in base.vxml.</log>
</catch>
<form id="root">
<block>
<prompt>
We will make
a transition to the secondDoc.
</prompt>
<submit next="secondDoc.vxml"/>
</block>
</form>
</vxml>
And the secondDoc.vxml:
<?xml version="1.0" encoding="ISO-8859-1"?>
<vxml xmlns="http://www.w3.org/2001/vxml" version="2.0" xml:lang="en-EN">
<catch event="connection.disconnect.hangup">
<log>Caught in secondDoc.vxml <value expr="_event"/>.</log>
</catch>
<form>
<block>
<prompt>
You are now
in the prompt of the secondDoc.
</prompt>
<exit/>
</block>
</form>
</vxml>
- How can I use speech recognition
in my application?
There are no limits to your imagination. Speech recognition
servers do get better and better. ASR is an optional service
in your contract with Eloquant. ASR needs expertise and applications
using ASR need more development time than applications which
do not use ASR.
To encourage your customers’ satisfaction you have to careful decide on
the possible user input. A traditional example of the use of speech recognition
if VXML:
<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" xml:lang="en">
<menu>
<prompt>
Say one of Sports, Weather or News.
</prompt>
<choice next="http://www.sports.example/start.vxml">
Sports
</choice>
<choice next="http://www.weather.example/intro.vxml">
Weather
</choice>
<choice next="http://www.news.example/news.vxml">
News
</choice>
<noinput>I did not hear you. Please say one of Sports, Weather or
News.</noinput>
</menu>
</vxml>
- How to use TTS in VoiceXML?
All text in <prompt> tags will be vocalised by the TTS
service, e.g:
<prompt> Welcome to our weather service. </prompt>
For prompts which do not change regularly, a recorded audio
should be considered, with a possible TTS alternative if you
wish:
<prompt>
<audio src="welcome.wav"/>
Welcome to our weather service.
</prompt>
See also What are the differences between
deploying my VoiceXML service during my development and
production phase?
- "Could not start ASR due
to exception / Resource :rtsp://NoASR not available" What
shall I do?
If you find these traces in your exec_log files (see How
can I view the log files of the VoiceXML browser?),
you are using the default value of the property inputmodes.
For a description of the property inputmodes, see the W3C
standard: http://www.w3.org/TR/voicexml20/#dml6.3.6.
The default value for the property inputmodes is "voice
dtmf". The VoiceXML browser will try to activate ASR
and DTMF recognition if you use a built-in grammar like digits,
for example:
<field name="field_name" type="digits">
If your account does not allow the usage of ASR, you will
then find the above mentioned error message in your log file.
The way to avoid this is to set the value of the property
inputmodes to dtmf in you vxml application:
<property name="inputmodes" value="dtmf">
- How can I use the built-in grammar "digits"?
If you use the Nuace ASR engine, the built-in grammar digits can
only be used with by setting the property inputmodes="dtmf".
If you use the built-in grammar digits with both DTMF
and ASR activated, your vxml session will be abruptly terminated
because the Nuance ASR engine does not support digits. Make
also sure that when your own grammar contains digits, that
you have to write them out in words, i.e. do not use "1" but
do use "one".
<property name="inputmodes" value="dtmf"/>
<form>
<field name="user_id" type="digits">
<prompt>What is your user id?</prompt>
</field>
</form>
- Why do I not hear my prompt after
a <noinput> or <nomatch> event is caught?
If you use a <catch event="noinput"> or <catch
event="nomatch"> handler, or the shortcuts <noinput> or <nomatch>,
you must use the <reprompt/> tag to make sure that
the prompt of your field is repeated. For example:
<form>
<noinput>
<prompt>I did not hear you.</prompt>
<!-- <reprompt/> -->
</noinput>
<nomatch>
<prompt>That is not an option.</prompt>
<!-- <reprompt/> -->
</nomatch>
<field name="entree">
<prompt>
Please select
an entree. Today, we are featuring <enumerate/>
</prompt>
<option dtmf="1" value="fish"> swordfish </option>
<option dtmf="2" value="beef"> roast
beef </option>
<option dtmf="3" value="chicken"> frog
legs </option>
<filled>
<prompt>You
wanted <value expr="entree"/></prompt>
</filled>
</field>
</form>
If you use the vxml code above, in case the user selected
4, he will only hear "That is not an option". He
will not rehear the prompt "Please selecct an entree....".
To reiterate the prompt in case of a noinput or nomatch event,
you must add the <reprompt/> tag to your <noinput> and <nomatch> handlers.
See also the VoiceXML standard on: http://www.w3.org/TR/voicexml20/#dml5.3.6.
If you have no noinput or nomatch handlers in your VoiceXML
code at all (not recommended), the default handlers apply,
which do offer an automatic reprompt. See the section on
default catch handlers on: http://www.w3.org/TR/voicexml20/#dml5.2.5.
Bibliography
- Where to read more about VoiceXML?
If you are new to VoiceXML, the standard might be a bit
too difficult to start: http://www.w3.org/TR/voicexml20/
You could consider buying a book on VoiceXML, for example:
And on the internet:
See also How to learn more about VoiceXML?
