Building VoiceXML applications

A voice application is a collection of one or more VoiceXML documents. A VoiceXML document is composed of one or more dialogs. A single VoiceXML document serves as the application entrypoint. This is the VoiceXML document that the Tellme VoiceXML interpreter fetches when a customer dials the telephone number associated with your voice application. Upon execution of that document, the interpreter fetches dependencies including grammars, scripts, recorded audio, XML data, and additional VoiceXML documents as required by your application.

The documents in a voice application share a common application root document. An application root document is a VoiceXML document that can contain variable declarations, scripts, links, grammars, event handlers, and properties that are available throughout the application.

Note. Subdialogs are a notable exception, and they are described in detail in Modularizing code with subdialogs.

The remainder of this document provides some simple examples of a voice application and provides details about the application root document

1. Understanding voice applications

The following diagram depicts a simple voice application. The application consists of a main document, "doc1" that serves as the application entrypoint, an application root document, "app_root", that provides shared application resources, and two additional VoiceXML documents, "doc2" and "doc3".

The following diagram depicts a more complex voice application:

2. Defining an application root document

When building a voice application, it is useful to define resources such as variables, scripts, grammars, links, and event handlers that can be shared across the application. Variable declared in the application root document have application scope allowing you to share state across the documents that make up your voice application. Declaring scripts in the application root document allows functions and script variables to be loaded once for the lifetime of your application. Grammars declared in the application root document are active throughout the application as are links, and event handlers.

The document can contain variable declarations, scripts, links, and event handlers. By placing these elements in the application root, they are available for use by the documents that make up your voice application.

The following is an example of an application root document. The document contains the following resources:

<!-- tellmeu_root.vxml -->
<vxml version="2.1">
   <var name="gbLoggedIn" expr="false"/>
   <var name="giStudentID" />
   <var name="gsNextDialog" />
   <link next="tellmeu.vxml#welcome">
      <grammar mode="voice"
        <rule id="root_rule" scope="public">
              start over
   function IsLoggedIn() 
     return application.gbLoggedIn; 
   function InitGlobals() 
     application.gbLoggedIn = false;
     application.giStudentID = null;
     application.gsNextDialog = null;

   <property name="timeout" value="1.0"/>

  <catch event="event.onlistmyclasses">
     <assign name="application.gsNextDialog"
     <goto next="login.vxml"/>

  <!-- handle all error events -->
    <log>APP ERROR!!! <value expr="_event"/>
    Sorry, there was a problem processing your request. 
    Please try again later.

  <!-- handle unhandled non-error events -->
  <catch event="">
    <log>UNHANDLED EVENT!!! <value expr="_event"/>  
    Sorry, there was a problem processing your request. 
    Please try again later.

3. Referencing an application root document

You reference the application root document by setting the application attribute of the VoiceXML documents that make up your voice application with the exception of subdialogs.

<!-- tellmeu.vxml -->
<vxml version="2.1" 

     dialogs and document-scoped variables, 
     scripts, event handlers, and links go here 


When you reference an application root document, the VoiceXML interpreter creates an application scope that exists so long as the VoiceXML documents in the application, with the exception of subdialogs, reference the same application root document. If your voice application transitions to a document that reference a different application root or no application root at all, the previous application scope is destroyed. This behavior can be demonstrated with the following example.

The application entrypoint is doc1.vxml. When the dialog form1 executes, it increments the application-scoped variable gVar by 10 and navigates to the dialog form3 in doc2.vxml. Since doc2.vxml doesn't reference the same application root as doc1.vxml, the previous application scope is destroyed, and a new one is created for doc2.vxml. When the dialog form3 in doc2.vxml navigates to the dialog form2 in doc1.vxml, the application scope for doc1.vxml is reinitialized, and the value of gVar is 1.

<!-- app_root.vxml -->
<vxml version="2.1">
  <var name="gVar" expr="1" />

<!-- doc1.vxml -->
<vxml version="2.0" application="app_root.vxml">
  <form id="form1">
      <assign name="gVar" expr="gVar+10" />
      <goto next="doc2.vxml#form3" />

  <form id="form2">
      <!-- expect 1 -->
      <log>In form2, gVar is 
      <value expr="gVar" />

<!-- doc2.vxml -->
<vxml version="2.0">
  <form id="form3">
      <goto next="doc1.vxml#form2" />

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