VoiceXML Development Frequently Asked Questions

This FAQ contains answers to questions about VoiceXML development.

  1. Does Tellme support HTTP cookies?
  2. Which scripting languages can be used within VoiceXML applications?
  3. Which server-side scripting languages does Tellme support?
  4. Does Tellme support "special characters" in VoiceXML?
  5. Which audio formats does Tellme support?
  6. Does the Tellme voice browser transmit an HTTP user agent string?
  7. Does Tellme support Real Audio file formats?
  8. I'd like to restart my VoiceXML application without having to re-enter my developer ID and PIN.
  9. The on-line documentation is great, but are there any books available on VoiceXML 2.0?
  1. How do I get my Web server to communicate with the Tellme Voice Application Network via a secure connection?
  1. I'm not seeing output from the Studio Debug Log for my phone call.
  2. The VoiceXML Syntax Checker says my code is OK, but I get a run-time error when I run it.
  3. The Debug Log reports a Javascript error on a line of code that contains only VoiceXML and no Javascript.
  4. Numerical comparisions within the cond attribute of the if element seem to yield incorrect results.
  5. When I run my application, at some point I hear "bad format" instead of my recorded audio.
  6. Why would VoiceXML, Javascript, or grammar file retrievals time out if I'm reasonably sure that my Web server is OK?
  7. I'm getting an "ERROR STATE: *UNNAMED*" error in the Debug Log.
  8. The Debug Log reports an XML parse error at the very top my of my VoiceXML code.
  9. I have a boolean expression that is evaluating incorrectly. What's going on?
  10. I have problems retrieving VoiceXML pages from my Apache NT server.
  11. I have problems retrieving VoiceXML documents from my IIS server on a Windows NT Workstation.
  1. What is the relationship between VoiceXML and JavaScript?
  2. Is the use of JavaScript a Tellme-specific extension?
  3. What JavaScript runtime engine does the Tellme Platform use?
  4. What version of JavaScript does Tellme support?
  5. How do JavaScript objects like the "document" and "window" map to voice applications?
  1. I've made changes to my ASP/JSP/PHP/Perl/etc. generated page but my old copy keeps cropping up!
  2. How do I optimize my application to allow Tellme to cache effectively?
  3. How do I test if my pages can be cached?
Q: Does Tellme support HTTP cookies?
A: Yes. The Tellme platform accepts from and sends cookies to any Web server. See Using Cookies for more details.

Q: How do I get my Web server to communicate with the Tellme Voice Application Network via a secure connection?
A: The Tellme Voice Application Network supports HTTPS and Secure Sockets Layer (SSL) 3.0. To take advantage of this level of security you must acquire a root certificate signed by a trusted authority such as RSA, Thawte, Verisign, or XCert. The Tellme Voice Application Network supports encryption level requests up to 128-bit. To retrieve data using the HTTPS protocol, reference URLs using "https://" in VoiceXML code.

Q: Which scripting languages can be used within VoiceXML applications?
A: The VoiceXML 1.0 Specification requires VoiceXML interpreters to support JavaScript (ECMAScript) within VoiceXML applications. The Tellme VoiceXML interpreter supports Javascript 1.5.

Q: What is the relationship between VoiceXML and JavaScript?
A: The VoiceXML 1.0 specification defines not just the DTD for an XML-based voice markup language, but a complete voice application execution environment integrating the power of a general-purpose, procedural scripting language, ECMAScript (commonly known as JavaScript) with the declarative simplicity of XML.

The XML portion of the VoiceXML specification is designed purely to simplify the description of a voice application's call flow. It divides the application into a series of "dialogs" which gather data from the user, and between which control either flows sequentially or deterministically based on user input and the desired application behavior. The strength of this XML-based framework is the ease in which a specific caller interaction may be described. Each dialog encapsulates the processing for a single user interaction, including the prompts to play, the processing of caller input, and error handling. Though scoped variables, data operators, and branching/looping statements do exist within this framework, these constructs are primarily used to manage the call flow, rather than manipulate application data.

By allowing JavaScript code to be embedded within the XML call-flow framework, the designers of VoiceXML provided the mechanism to implement higher-order application functions such as data validation and manipulation, calculations, and business rules. JavaScript plays exactly the same role when embedded within a VoiceXML source file as JavaScript embedded within a Web page or HTML source file.

The use of the XML-framework for defining the overall flow of the application, combined with the power of the embedded JavaScript allows the creation of powerful voice applications quickly and easily. Tellme Consumer applications make extensive use of JavaScript to perform tasks such as randomizing user prompts or validating input data. The Tellme Blackjack game, for example, is implemented entirely using VoiceXML and JavaScript in a single file. It has no server-side component.

Q: Is the use of JavaScript a Tellme-specific extension?
A: No. The ability to embed JavaScript code into a VoiceXML page is a part of the VoiceXML 1.0 specification created by the VoiceXML Forum.

Q: What JavaScript runtime engine does the Tellme Platform use?
A: The Tellme Platform uses the JavaScript engine from the Mozilla (Netscape) codebase.

Q: What version of JavaScript does Tellme support?
A: Version 1.5 RC 6 of the Mozilla Foundation's JavaScript engine code-named SpiderMonkey.

Q: How do JavaScript objects like the "document" and "window" map to voice applications?
A: The object model exposed by Web browsers such as Netscape Navigator and Microsoft Internet Explorer is applicable to Web browsers only. JavaScript is a general purpose programming language that provides a facility to allow its host to extend the language by adding objects, properties, and methods. The Tellme VoiceXML interpreter hosts the JavaScript engine and extends the language with a limited set of global functions to write text to the Debug Log and to set and retrieve cookies.

Q: Which server-side scripting languages does Tellme support?
A: Since the Tellme VoiceXML interpreter is a client browser and that browser fetches content across the Web from an HTTP server, application developers are free to implement their voice applications using any server-side framework supported by the Web server hosting the content. Example server-side frameworks include: CGIs written in Perl, C/C++, or Java; Active Server Pages written in VBScript or JavaScript, and servlets written in Java. The key is that these frameworks must be programmed to generate VoiceXML and transmit it to the VoiceXML interpreter.

Q: Does Tellme support "special characters" in VoiceXML?
A: Currently, the Tellme VoiceXML interpreter provides limited support for double-byte character encodings in VoiceXML documents. By default, the Tellme interpreter assumes that VoiceXML documents are encoded in UTF-8, which covers the normal set of ASCII characters (and more). Additional the Tellme interpreter supports the ISO 8859-1 encoding, widely used for European character sets. To specify this encoding, insert the following as the first line of any VoiceXML document:
<?xml version="1.0" encoding="iso-8859-1"?> Tellme has built-in support for the following encodings:
  • UTF-8
  • UTF-1
  • ISO-8859-1
  • us-ascii

Q: Which audio formats does Tellme support?
A: For now, the only supported audio format is ".wav". For optimal playback efficiency over the phone, save .wav files in 8KHz, 8-bit mu-law (G.711), mono format. Although the Tellme platform supports higher fidelity .wav formats (up to 44.1 KHz, 16-bit, stereo), current phones can only play back at 8KHz mu-law. We plan to support other formats in the future.

Q: Does the Tellme voice browser transmit an HTTP user agent string?
A: Yes. Tellme's user agent string is "Tellme/1.0 (I; en-US)".

Q: Does Tellme support Real Audio file formats?
A: For now Tellme only supports ".wav" files. However, there are nifty tools available that convert Real Audio to .wav files. Examples of such utilities include Streambox Ripper by Streambox.com , and Total Recorder from High Criteria .

Q: I'd like to restart my VoiceXML application without having to re-enter my developer ID and PIN.
A: Just hit ** (star star) or say "Tellme Menu", and your application will be restarted immediately.

Q: I'm not seeing output from the Studio Debug Log for my phone call.
A: First, make sure that you're using the same Developer ID sign in for both the Tellme Studio website and for your current phone call. Developers who've created multiple Developer IDs can't log in to the website with one Developer ID and call the phone application with a different Developer ID. Second, be sure to click the "Debug Log" button before, or shortly after, beginning your current call. If you wait too long, Tellme Studio will think that your call is old and not display the Debug Log contents for that call. In general, the Debug Log contents should be available within 15 minutes of a call; in most cases, the response will be in real-time.

Q: The VoiceXML Syntax Checker says my code is OK, but I get a run-time error when I run it.
A: Like a compiler, the syntax checker only guarantees that your VoiceXML document is well-formed XML and that it is valid according to the rules established by the VoiceXML Document Type Definition (DTD). Because VoiceXML is executed like a programming language, errors can occur at run-time that are not detectable during the validation process.

To track down and resolve run-time errors, use the Tellme Studio debug log to trace through your code. Add log elements to your code to analyze the state of your program as it executes.

Q: The Debug Log reports a Javascript error on a line of code that contains only VoiceXML and no Javascript.
A: Some attributes (expr, cond) in VoiceXML require JavaScript expressions. Errors in an attribute that requires a Javascript expression are reported as a Javascript error in the Debug Log. To learn more about JavaScript expressions in VoiceXML, see Using JavaScript

Q: Numerical comparisions within the cond attribute of the if element seem to yield incorrect results.
A: Keep in mind that the cond attribute is evaluated by the Javascript engine. When making a numerical comparison, make sure that the variables involved in the comparison are numbers. You can use the var element to declare a variable of any valid type. You can use the native Javascript functions parseInt and parseFloat to explicitly convert variables to an integer or float respectively. The Javascript language can implicity convert variable during a comparison, but it may perform a lexical comparison (e.g. '13' < '3') resulting in an unexpected result. Example of using parseInt(): <var name="i" expr="'3'"/> <!-- i is a string --> <if cond="parseInt(i, 10) == iMax"> <goto next="#abort"/> </if>

Q: When I run my application, at some point I hear "bad format" instead of my recorded audio.
A: Check the value of the src and expr attributes of the audio elements within your appliccation for incomplete URLs. For example, if your code references "http://myserver/mypath/" instead of "http://myserver/mypath/myfile.wav" your Web server may return a 'friendly 404' HTML page. The VoiceXML interpreter will fetch the requested URL, and since it won't recognize the HTML as a valid audio format, it will play an error. You should also consider including a TTS string within each of your audio elements.

Q: Why would VoiceXML, Javascript, or grammar file retrievals time out if I'm reasonably sure that my Web server is OK?
A: This symptom can result if the following two conditions are both in effect:
  1. Your Web server does not send an explict Connection: close when it's done serving up a file
  2. Your Web server also doesn't send the Content-Length: HTTP header.
In this case, there's no way to tell when a particular file retrieval is "complete," therefore, the file fetching mechanism keeps trying (and trying and trying) until it eventually times out.

Q: I'm getting an "ERROR STATE: *UNNAMED*" error in the Debug Log.
A: The following Debug Log output usually indicates that the VoiceXML code is missing a final transition out of the document.
DEV : 000043 MODHAND Get: [[session].[error].[code]] -> [6] 
DEV : 000043 MODHAND Get: [[session].[error].[text]] -> [Failure in speech system] 
DEV : 000043 MODHAND Get: [[session].[error].[state]] -> [*UNNAMED*] 
This error condition is typically the result of a VoiceXML document which contains one or more <field>s, but no exit transition.

Q: The Debug Log reports an XML parse error at the very top my of my VoiceXML code.
A: If you're specifying the XML processing instruction <?xml version="1.0"?>, make sure that this is the first line of your VoiceXML document. An XML parse error occurs if the VoiceXML interpreter finds any text, spaces, or blank lines before the processing instruction. A future version of the Tellme platform will ignore leading spaces at the top of a VoiceXML document.

Q: I have a boolean expression that is evaluating incorrectly. What's going on?
A: Make sure you are not setting your VoiceXML variables with a string expression, like "false". For example: <var name="bAllow" expr="'false'"/> <if cond="bAllow"> <!-- bAllow is true --> <else/> <!-- bAllow is false --> </if> The VoiceXML interpreter uses the JavaScript engine to evaluate the value associated with a cond attribute. JavaScript evaluates strings such as "true" and "false" used in a boolean context to true. Use the constants true and false instead. From http://developer.netscape.com/docs/manuals/js/client/jsref/boolean.htm : "The initial value of the Boolean object. The value is converted to a boolean value, if necessary. If value is omitted or is 0, -0, null, false, NaN, undefined, or the empty string (""), the object has an initial value of false. All other values, including any object or the string "false", create an object with an initial value of true."

Q: I have problems retrieving VoiceXML pages from my Apache NT server.
A: Apache for NT has not been optimized for performance and is still in the experimental stages (for more information go here ). Currently, there is a limitation of 4 simultaneous connections for the Apache server. This could be a problem, because upon loading a VoiceXML document, the Tellme Voice Application Network will also make requests for dependent documents, like external scripts and grammar files. This could conceivably max out the number of allowed connections on an Apache NT server. In cases where the VoiceXML interpreter cannot retrieve a document, it will revert to a cached copy.

Q: I have problems retrieving VoiceXML documents from my IIS server on a Windows NT Workstation.
A: IIS for Windows NT Workstation allows a maximum of ten simultaneous connections. This could be a problem, because upon loading a VoiceXML document, the Tellme Voice Application Network will also make requests for dependent documents, like external scripts and grammar files. This could conceivably max out the number of allowed connections on IIS. In cases where the VoiceXML interpreter cannot retrieve a document, it will revert to a cached copy.

Q: I've made changes to my ASP/JSP/PHP/Perl/etc. generated page but my old copy keeps cropping up!
A: You may be experiencing a cachine issue. In general, the Tellme platform caches audio, compiled grammars, and voiceXML to speed up the responsiveness of the Tellme Voice Application Network. To override caching behavior return one or more of the following HTTP headers from your Web server: Pragma: no-cache , Expires: Thu, 01 Dec 1994 16:00:00 GMT , and Cache-Control: no-cache .

Q: How do I optimize my application to allow Tellme to cache effectively?
A: To optimize performance, Tellme encourages you to allow the VoiceXML interpreter to cache content for as long as possible. The Tellme interpreter normally performs an HTTP If-Modified-Since query for each requested document. By specifying an appropriate HTTP Expires, Pragma, or Cache-Control header, you can prevent the interpreter from making this check.

Q: How do I test if my pages can be cached?
A: The following sites allow you to test if your site's content is cacheable: http://www.Web-caching.com/cacheability.html , http://www.ircache.net/cgi-bin/cacheability.py , and http://www.cacheflow.com/technology/tools/friendly/cacheability/tool/ .

A free tool that allows you test cacheability can be found here: http://www.mnot.net/cacheability/

Q: The on-line documentation is great, but are there any books available on VoiceXML 2.0?
A: Check out VoiceXML: Professional Developers Guide by Chetan Sharma and Jeff Kunins.

[24]7 Inc.| Terms of Service| Privacy Policy| General Disclaimers