Genesys Voice Platform 8.1 Genesys VoiceXML 2.1 Reference help

Copyright © 2008–2013 Genesys Telecommunications Laboratories, Inc. All rights reserved.
gvp_VoiceXML_07-2013_v8.1.700.02

The information contained herein is proprietary and confidential and cannot be disclosed or duplicated without the prior written consent of Genesys Telecommunications Laboratories, Inc.

Overview

Welcome to the Genesys Voice Platform 8.1 Genesys VoiceXML 2.1 Reference Help file. This help file provides reference material for Genesys Voice Platform (GVP) VoiceXML developers. It describes the VoiceXML 2.1 standards as implemented by GVP version 8.0 and later.

GVP 8.1, on Microsoft Windows, can be configured to access the Legacy GVP VoiceXML functionality of GVP 7.6 (for example, the Genesys extensions to TXML, and so on). For details see, the Genesys Voice Platform 8.1 Legacy Genesys VoiceXML 2.1 Reference Manual.

In addition to this overview topic, the help file contains:

  • About This File, provides the version number for this file, and provides general information about Genesys, including the company's copyright information, general disclaimers, support contact information, and so on.

  • About Genesys Patents, provides information about the Genesys's patents.

  • Printing This Help File, describes how to print a single topic or all of the topics within a single book.

  • Quick Start, provides development concepts that will help you get started developing VoiceXML applications.

  • Standard VoiceXML, provides details about ECMAScript, Extended Error Events, Properties, Variables, SSML tags, and VoiceXML tags.

  • Debugging, provides details about how to configure a VoiceXML application to create logs for debugging and application monitoring.

  • GVP Features, provides details about GVP VoiceXML extensions.

  • Best Practices, provides techniques for developing efficient VoiceXML applications.

  • Tutorials, provides tutorials on General VoiceXML Concepts and Advanced VoiceXML Concepts.

  • Sample VoiceXML Applications, provides VoiceXML code samples that show how to access call data during the call setup, mid call, initiate transfer, treatments (post-initiate transfer), and transfer-complete stages of a call.


Quick Start

Overview

The following topics provide VoiceXML development concepts that will help you get started developing VoiceXML applications:

  • Introduction

  • Lesson 1: Getting Started

  • Lesson 2: Using Voice Recognition

  • Lesson 3: Using Voice Recognition

  • Lesson 4: Navigating to a New Page

  • Large VoiceXML Applications

For more details, see the GVP Features topic GVP Extensions.


Quick Start

Introduction

How does a Voice Application Work?

Just as HTML (HyperText Markup Language) is used to create visual applications, VoiceXML is a markup language used to create voice applications. With a traditional web page, a web browser will make a request to a web server, which in turn will send an HTML document to the browser to be displayed visually to the user. With a voice application, it is the VoiceXML Interpreter that sends the request to the web server, which will return a VoiceXML document to be presented as a voice application using a telephone. What makes VoiceXML so powerful is that all of the most popular tools for making web pages are available for making voice applications. Developers can use technologies they are already familiar with like JavaScript, Perl, and JSP to create voice applications.


Quick Start

Lesson 1: Getting Started

This lesson will explain how to create a "Welcome to GVP University!" VoiceXML application. The objective is to show how to structure and run a VoiceXML application.

Step 1—The First and Last Lines

Every VoiceXML document starts and ends as follows:

  1. Enter the XML version:

     <?xml version="1.0"?>

  2. Enter the VoiceXML version:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   . . .
</vxml>

Step 2—VoiceXML Application

  1. Add the <form> tag to your file. The <form> tag is what groups sections of input and output together (known as a dialog). Note: This application has one <form> tag, but there may be multiple <form> tags.

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form>
   <block>
     Welcome to GVP University!
   </block>
</form>
</vxml>

  2. Save your document as welcome.vxml (the file extension must be .vxml).

Summary:

  • An application may include one or more documents, or pages (document is synonymous with page).

  • A document (page) may include one or more <form> tags, or dialogs (form is synonymous with dialog).

  • A form (dialog) may contain one or more field items.

For detail on which tags can be grouped under or over a given tag, see the Parents and Children listed in each VoiceXML element.

Step 3—Upload the Application to a Web Site

Your application needs to be readable (by the GVP VoiceXML browser) on a web site. There are many web sites that offer their services free of charge. Imagine that your file ends up at:

http://www.freewebsite.com/yourname/welcome.vxml

You will need to know this information when you set up your GVP extension.

Step 4—Create an Extension that Points to the Application

  1. Click the Tools tab, and go to the Extension Manager.

  2. Type the URL for your application (Step 3).

  3. Click Add, and make a note of the extension you are given.

Step 5—Test your Application

You are now ready to test your application:

  1. Call either number listed in the Extension Manager.

  2. When you are asked for your extension, either say it or type it using the touchtone keypad on your telephone.

  3. Listen while the TTS engine reads "Welcome to GVP University!"

Congratulations! You have successfully created and run your first VoiceXML application!


Quick Start

Lesson 2: Using Voice Recognition

Before you start this lesson, make sure that you understand the concepts presented in Lesson 1.

Step 1—Start with the VoiceXML Structure

All VoiceXML applications contain the <?xml>, <vxml> and </vxml> lines:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <!-- The code will go here -->
</vxml>

Step 2—Add the Mechanism to Prompt the User and Wait for a Response

<form id="Choices">
   <field name="choice">
      <prompt>
         Please choose from the following:
         To add a course, say add.
         To drop a course, say drop.
         To check your schedule, say check.
      </prompt>
      <grammar type="application/srgs+xml" version="1.0" root="root">
         <rule id="root">
           <one-of>
             <item>add</item>
             <item>drop</item>
             <item>check</item>
           </one-of>
         </rule>
      </grammar>
   </field>
</form>

Notes:

  • Recall in Lesson 1 that a <form> is what groups sections of input and output together. It is also known as a dialog. This lesson calls this <form> Choices because later on you will want to be able to return to it.

  • Call the <field> choice. The user's response will be stored in the variable choice.

Test your code by saying nothing. What happened?
Test it again by saying Whatever. What happened?
Test it again by interrupting the prompt with your response.

Step 3—Override the Default for "No Input"

<field>
   ...
   <noinput>
      I didn't hear you.
      <reprompt/>
   </noinput>
   ...
</field>

Step 4—Override the Default for "No Match"

<field>
   ...
   <nomatch>
      I didn't quite understand you.
      <reprompt/>
   </nomatch>
   ...
</field>

Step 5—Try Bargein

By default, <bargein> is true. While you are testing, it is a good idea to make it false. You will notice much higher accuracy in speech recognition when <bargein> is turned off.

<property name="bargein" value="false"/>

So, here is the code so far. You have an application that accepts an input with three choices, but does not do anything with the input:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<property name="bargein" value="false"/>
   <form id="Choices">
      <field name="choice">
         <prompt>
            Please choose from the following:
            To add a course, say add.
            To drop a course, say drop.
            To check your schedule, say check.
         </prompt>
         <grammar type="application/srgs+xml" version="1.0" root="root">
           <rule id="root">
             <one-of>
               <item>add</item>
               <item>drop</item>
               <item>check</item>
             </one-of>
           </rule>
        </grammar>
        <noinput>
            I didn't hear you.
            <reprompt/>
         </noinput>
         <nomatch>
            I didn't quite understand you.
            <reprompt/>
         </nomatch>
      </field>
   </form>
</vxml>

Step 6—Take Action When Match is Found

The <filled> tag will allow you to take some action when a grammar is recognized. The VoiceXML <if> tag is very similar to <if> in many other programming languages.

<field>
   ...
   <filled>
      <if cond="choice=='add'">
         OK let's add a course.
      <elseif cond="choice=='drop'"/>
         OK let's drop a course.
      <else/>
         OK let's check your schedule.
      </if>
   </filled>
   ...
</field>

Notes:

  • Be very careful to use only lower-case in the cond= construction. The expression following cond= is an example of ECMAScript, otherwise known as Javascript or Jscript. It is case-sensitive.

  • Notice the double-quotes around the entire expression following cond=. Within those double-quotes is a pair of single-quotes around the string 'drop' or 'add'.

Step 7—Add Debugging Information

As a final step, you will add lines to help in debugging:

<meta name="maintainer" content="<your name>@<your server.com>"/>

Note: The maintainer is the e-mail address that error messages will be sent to.

Step 8—Putting It All Together

Your script is now complete, and the entire file should look like this:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="<yourname>@<yourserver.com>"/>
<property name="bargein" value="false"/>
   <form id="Choices">
      <field name="choice">
         <prompt>
            Please choose from the following:
            To add a course, say add.
            To drop a course, say drop.
            To check your schedule, say check.
         </prompt>
         <grammar type="application/srgs+xml" version="1.0" root="root">
           <rule id="root">
             <one-of>
               <item>add</item>
               <item>drop</item>
               <item>check</item>
             </one-of>
           </rule>
         </grammar>
         <noinput>
            I didn't hear you.
            <reprompt/>
         </noinput>
         <nomatch>
            I didn't quite understand you.
            <reprompt/>
         </nomatch>
         <filled>
            <if cond="choice=='add'">
               OK let's add a course.
            <elseif cond="choice=='drop'"/>
               OK let's drop a course.
            <else/>
               OK let's check your schedule.
            </if>
         </filled>
      </field>
   </form>
</vxml>

Step 9—Save and Test

Save this file on your web site with a .vxml extension, for example:
http://www.<freewebsite>.com/<yourname>/lesson2.vxml

Create an extension for this application, just as in Lesson 1, and then call the number and test your VoiceXML program!

What Did You Learn in Lesson 2?

  • A <form> groups sections of input and output together.

  • A <field> contains a variable where user input is stored.

  • <noinput> and <nomatch> are tags that can be used to override the default action taken when there is no input or input that does not match a grammar.

  • The recognizer is more accurate if bargein equals false.

  • <if>, <elseif/> and <else/> control the flow of events.

  • GVP offers several methods to debug your application, which are controlled by adding a <property> or <meta> tag line to the program.


Quick Start

Lesson 3: Using Voice Recognition

Before you start this lesson, make sure that you have completed Lesson 2.

This tutorial includes three code examples. Each example produces the same output as Lesson 2 (except the prompts are slightly abbreviated), using the <menu> tag instead of <form> ... <field>, and the dtmf input instead of voice recognition.

The <dtmf> input could have been used in Lesson 2 with <form> and <field>. Similarly, you could have used a voice recognition grammar with <menu>.

  • <menu> adds no new capabilities compared to <form>. It simply provides a convenient shorthand for the special case where you want to provide a simple choice to the user.

  • A choice is a set of alternatives, exactly one of which must match. In the examples below, instead of having a grammar, you have touch-tone choices.

  • The next=... structure is introduced, as a way of navigating to a specific <form> based on the <choice> input.

Example 1

This example shows a dtmf-only menu offering three choices (add a course, drop a course, or check your schedule).

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="<yourname>@<yourserver.com>"/>
<property name="bargein" value="false"/>
   <menu>
      <prompt>
         To add a course, press 1,
         To drop a course, press 2,
         To check your schedule, press 3.
      </prompt>
       <choice dtmf="1" next="#add"/>
       <choice dtmf="2" next="#drop"/>
       <choice dtmf="3" next="#check"/>
    </menu>
   <form id="add">
      <block>
         <prompt>This is add</prompt>
      </block>
   </form>
   <form id="drop">
      <block>
         <prompt>This is drop</prompt>
      </block>
   </form>
   <form id="check">
      <block>
         <prompt>This is check</prompt>
      </block>
   </form>
</vxml>

<Menu> (remove dtmf="true")
...
<choice dtmf="1" next="#add"/>
<choice dtmf="2" next="#drop"/>
<choice dtmf="3" next="#check"/>

The program does not simply fall from one <form> to another. After it plays "This is add", it stops rather than moving on to the "drop" <form>. To move to a new <form>, the transition must be requested explicitly. When in a <menu>, as in the example above, the <choice> tag can specify the next <form> to execute. In other cases, the <goto> tag, which will be introduced in Lesson 4, can be used to transition to a new <form>.

Example 2

This example uses a shortcut to automatically assign the first three choices to touch-tone numbers 1, 2, and 3.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="<yourname>@<yourserver.com>"/>
   <menu dtmf="true">
      <prompt>
         To add a course, press 1,
         To drop a course,press 2,
         To check your schedule, press 3.
      </prompt>
      <choice next="#add"/>
      <choice next="#drop"/>
      <choice next="#check"/>
   </menu>
   <form id="add">
      <block>
         <prompt>This is add</prompt>
      </block>
   </form>
   <form id="drop">
      <block>
         <prompt>This is drop</prompt>
      </block>
   </form>
   <form id="check">
      <block>
         <prompt>This is check</prompt>
      </block>
   </form>
</vxml>

Example 3

This example uses the <enumerate> tag to generate the touch-tone options.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="<yourname>@<yourserver.com>"/>
   <menu dtmf="true">
      <enumerate>
         For <value expr="_prompt"/>
         please press <value expr="_dtmf"/>,
      </enumerate>
      <choice next="#add">
         add
      </choice>
      <choice next="#drop">
         drop
      </choice>
      <choice next="#check">
         check
      </choice>
   </menu>
   <form id="add">
      <block>
         <prompt>This is add</prompt>
      </block>
   </form>
   <form id="drop">
      <block>
         <prompt>This is drop</prompt>
      </block>
   </form>
   <form id="check">
      <block>
         <prompt>This is check</prompt>
      </block>
   </form>
</vxml>

What Did You Learn in Lesson 3?

  • The <menu> tag provides a shortcut if there are a limited number of choices offered.

  • The <choice> and <enumerate> tags can be used within <menu> in several different ways to automate the prompt generation.


Quick Start

Lesson 4: Navigating to a New Page

Before you start this lesson, make sure that you understand the concepts presented in Lessons 1, 2, and 3.

In this lesson, you will explore three different ways to navigate to a page, or document, within an application:

  • <link> is usually used as a way to have two or more grammars active at a given time.

  • <submit> fetches a page from the server and transfers control to a dialog on that page. You can submit selected fields or all fields in the form.

  • <goto> is similar to <submit> except that no field values are transmitted.

All three of the above are similar to the idea of a hyperlink in html.

Step 1—Start with the Code from Lesson 2

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="<yourname>@<yourserver.com>"/>
<property name="bargein" value="false"/>
   <form id="Choices">
      <field name="choice">
         <prompt>
            Please choose from the following:
            To add a course, say add.
            To drop a course, say drop.
            To check your schedule, say check.
         </prompt>
         <grammar type="application/srgs+xml" version="1.0" root="root">
           <rule id="root">
             <one-of>
               <item>add</item>
               <item>drop</item>
               <item>check</item>
             </one-of>
           </rule>
         </grammar>
         <noinput>
            I didn't hear you.
            <reprompt/>
         </noinput>
         <nomatch>
            I didn't quite understand you.
            <reprompt/>
         </nomatch>
         <filled>
            <if cond="choice=='add'">
               OK let's add a course.
            <elseif cond="choice=='drop'"/>
               OK let's drop a course.
            <else/>
               OK let's check your schedule.
            </if>
         </filled>
      </field>
   </form>
</vxml>

Step 2—Create a Link to a New Page

The <link> tag lets you define a speech and/or dtmf grammar which, when recognized, causes the Interpreter to transition to a specified page. In this case, you are going to allow the caller to say "restart" in order to go back to the same page.

<link next="http://www.freewebsite.com/yourname/lesson4.vxml">
   <grammar type="application/srgs+xml" version="1.0" root="root">
         <rule id="root">
           <one-of>
             <item>restart</item>
           </one-of>
         </rule>
      </grammar>
</link>

Notes:

  • Of course, using the exact same syntax, but with a different URL, you could call a completely different page using this link.

  • Links can be defined within different tags, and its location determines its scope. This means that if a link is defined as a child of <vxml>, the recognizer will accept words from the link grammar(s) anywhere input is accepted inside the <vxml>. Similarly, if defined inside a <form> or <field>, the words will be accepted only within that <form> or <field>.

Step 3—Use <submit> to Obtain a New Document

Take the <if> structure from your code and rewrite it using <submit>:

<if cond="choice=='add'">
   <submit next="add.jsp"/>
<elseif cond="choice=='drop'"/>
   <submit next="drop.jsp"/>
<else/>
   <submit next="check.jsp"/>
</if>

Notes:

  • By default, if multiple fields have been visited prior to the <submit> tag, <submit> will pass all field values to the new page.

  • On the other hand, you can use the namelist attribute to pass only selected field values.

  • Using the expr attribute with <submit>, it is possible to generate the URL dynamically from an expression.

  • The assumption with the example above is that there is a jsp application on the server in the same directory as the current application that is being called. Of course, the next= could just as well be followed by a complete URL beginning with http://www. ...

Step 4—Using <goto>

As mentioned in the introduction, the <goto> tag is similar to <submit>, except that no field values are transmitted. One other difference with <goto> is that it can also be used to jump to another form or menu in the same page.

<if cond="choice=='add'">
   <!-- Transitions to another page -->
   <goto next="add.jsp"/>
<elseif cond="choice=='drop'"/>
   <!-- Transitions to another item in this form -->
   <goto nextitem="dropcourse"/>
<else/>
   <!-- Transitions to another form or menu on this page -->
   <goto next="#checkschedule"/>
</if>

Notes:

  • Since the code above conveniently happens to have three choices, and there are three ways of using <goto>, all three syntaxes were used in the same example (normally you would probably use the same structure for all three choices).

  • The <goto next="add.jsp"/> syntax, like the similar syntax that used <submit> above, requires there to be a document in the same directory as this application, called add.jsp.

  • The <goto nextitem= ...> syntax directed the flow to another item in the same form. The
    <goto next=# ...>     syntax directed the flow to another form in the same document. Notice that the form was named checkschedule but was called using next=#checkschedule. The # is called an anchor notation.

Step 5—Putting it Together; Save this Code as Lesson4.vxml

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="<yourname>@<yourserver.com>"/>
<property name="bargein" value="false"/>
   <!-- Change the specified URL to the URL for this page -->
   <link next="http://www.freewebsite.com/yourname/lesson4.vxml">
     <grammar type="application/srgs+xml" version="1.0" root="root_link">
       <rule id="root_link">
         <one-of>
           <item>restart</item>
         </one-of>
       </rule>
     </grammar>
   </link>
   <form id="Choices">
      <field name="choice">
         <prompt>
            Please choose from the following:
            To add a course, say add.
            To drop a course, say drop.
            To check your schedule, say check.
         </prompt>
         <grammar type="application/srgs+xml" version="1.0" root="root1">
           <rule id="root1">
             <one-of>
               <item>add</item>
               <item>drop</item>
               <item>check</item>
             </one-of>
           </rule>
         </grammar>
         <noinput>
            I didn't hear you.
            <reprompt/>
         </noinput>
         <nomatch>
            I didn't quite understand you.
            <reprompt/>
         </nomatch>
         <filled>
            <if cond="choice=='add'">
               <goto next="add.jsp"/>
            <elseif cond="choice=='drop'"/>
               <goto nextitem="dropcourse"/>
            <else/>
               <goto next="#checkschedule"/>
            </if>
         </filled>
      </field>
      <block name="dropcourse">
         OK let's drop a course.
      </block>
   </form>
   <form id="checkschedule">
      <block>
         OK let's check
      </block>
   </form>
</vxml>

Unless you create a page called add.jsp (or change the code to <goto next="add.vxml"/> and create a page called add.vxml), you will hear "the requested page cannot be found" if you say, "add."

What Did You Learn in Lesson 4?

  • <link>, <submit> and <goto> each function is somewhat similar to an html hyperlink in that the control of the program is transferred to a new document or dialog.

  • It is possible to have several grammars active at the same time. Using <link> is one way to achieve this.

  • It is important to know how your application is using caching when you are calling a program repeatedly from the same machine.


Quick Start

Large VoiceXML Applications

Applications can be built with a single static page or with many static pages. But what if you are building a large application, with many possible user interactions and access to dynamic data?

VoiceXML provides capabilities for developing large applications. In addition, the web-centric model on which VoiceXML is based allows the use of conventional web server technologies for generating dynamic content. Typically these involve templates that are processed by a web application server to insert dynamic content. For example, Java Server Pages containing VoiceXML templates generate dynamic pages by using JavaBeans to generate the dynamic bits.

This topic introduces the elements of VoiceXML that support the building of large applications in these environments.

Application Structure

VoiceXML applications are comprised of a collection of documents. A document is the equivalent of an HTML page, and it encapsulates one or more dialogs. Execution of a dialog typically involves presentation of information to the caller, along with collection of input from that caller. Transition from one dialog to another is controlled by the currently executing dialog. Transition occurs using the <goto> or <submit> tags.

The simplest VoiceXML application, as shown in Figure 1, is going to be a set of VoiceXML pages that are returned by a web server to the VoiceXML platform. These pages are interpreted to control the interaction with the user.

Figure 1: Static VoiceXML Application

The application is entirely analogous to a set of HTML pages delivered by a web server. Transitions are controlled by the <goto> tag (which is executed in VoiceXML, as compared with being "clicked" by the user in a visual web browser).

Dynamic applications function in much the same way, with the exception that some or all of the pages are generated dynamically by a server-based technology such as JSP/JavaBeans, ASP/ActiveX, ColdFusion, or scripting languages such as perl. An overview of this model is shown in Figure 2.

Figure 2: Dynamic VoiceXML Application

VoiceXML defines an application as a collection of documents, possibly tied together with an application root document. The application root document provides a mechanism for retaining state among a related set of VoiceXML documents. A VoiceXML refers to its application root document using an attribute in the <vxml> tag. This means that the event handlers, variables, and global grammars defined in the root document are available to the subdocument for use. This structure is shown in Figure 3:

Figure 3: Application Level Information

So while VoiceXML pages do not retain state across <goto> and <submit>, the application root document allows the definition and management of data and behavior that is persistent across VoiceXML pages. This allows both static and dynamically generated pages to manage global data, and to provide consistent handling of events, and access to global (and consistent) behavior across an entire application.

Abstraction of Components

Abstraction of application components is an important software development technique. In the case of VoiceXML, much of the abstraction can be delegated to the server-side implementation.

Once you start developing VoiceXML applications; however, you will soon find that there are certain dialogs that you are going to need over and over again. For example, the confirmation of input, or the collection of a specific piece of information such as a phone number. Vendors in the speech industry have invested a great deal of effort in designing the call flow, grammars, and prompts for these dialogs, so that they are very good at accurately gathering the information in which you are interested. Wouldn't it be great to be able reuse that experience? Well, with the VoiceXML <subdialog> tag, you can.

<subdialog> tag

Subdialogs allow you to encapsulate a reusable dialog and reuse it in many applications. A subdialog provides the following features:

  • A subdialog can be built-in, defined in the VoiceXML page, or referenced as a server-side component.

  • A subdialog is parameterized (using the <param> tag), allowing the tailoring of the subdialog in very powerful ways.

  • Invocation of a subdialog can include handling of events in the same manner as a field (and, in fact, is used like a field in a form).

  • A subdialog returns a set of variables to the calling document (using the <return> tag).

Samples of useful subdialogs include:

  • Credit card number collection.

  • Confirmation of a previous input.

  • Collection of a date (including support for different inputs, such as yesterday, next Monday, or July 25, 2001).

Subdialogs can be used to build much larger user interactions, while avoiding common mistakes and taking advantage of hard-won experience.

Application Partitioning

One of the most common questions asked by new users is "How do I partition my application between the client and server?" The answer to this is usually "pick the right tool for the right job." You have the following tools available to you:

  • VoiceXML, controlling real-time speech, DTMF, audio, and TTS interaction with the user. It is best used to control the collection of information from the caller, validation of that information if possible, and playback of information to the user.

  • ECMAScript (part of the VoiceXML specification), providing a general "workhorse" component for doing little jobs that do not require a trip to the server. It is best used to support the VoiceXML part, whether it is by massaging data formats, doing simple calculations, and so on. It gives the application author a mechanism to avoid a round-trip to the server for simple processing requirements. It also melds nicely with the variable and object model of the Interpreter itself, so that, for example, field variables and ECMAscript variables are interchangeable.

  • The application server component provides integration with database and legacy systems, and links to data required by the application. It provides your VoiceXML application with access to personalized or dynamic information. By filling a VoiceXML page with information that is relevant to the caller, or based on current events and information, you can build a more compelling application.

This is the model that has migrated the web from being a read-only experience to a much more personalized and useful medium. Think of this partitioning in the same way as typical n-tier web application architectures. Many of the same issues are relevant, with the exception that the interaction with speech, the user has more stringent response requirements than the typical web application.


Standard VoiceXML

Overview

The VoiceXML topics included are:

  • ECMAScript Reference

  • Extended Error Events

  • Properties

  • Variables

  • SSML

  • VoiceXML


Standard VoiceXML

ECMAScript Reference

This topic provides the ECMAScript operators, statements, and core objects that are supported by GVP. GVP uses the SpiderMonkey 1.5 engine to perform ECMAScript (JavaScript) processing.

The following is a reference to many commonly-used features. It is not a comprehensive ECMAScript language specification.

  • Operators

  • Statements

  • Core Objects

    • Array

    • Boolean

    • Date

    • Math

    • Number

    • Object

    • String

    • RegExp

  • Notes

  • Reserved Words

  • Known Issues and Recommendations

Operators

Category

Operator

Description

Arithmetic

+

Adds two numbers.

++

Increments a number.

-

As a unary operator, negates the value of its argument. As a binary operator, subtracts two numbers.

--

Decrements a number.

*

Multiplies two numbers.

/

Divides two numbers.

%

Computes the integer remainder of dividing two numbers.

String

+

Concatenates two strings.

+=

Concatenates two strings and assigns the result to the first operand.

Logical Operators

&&

(Logical AND) Returns true if both logical operands are true; otherwise, returns false.

||

(Logical OR) Returns true if either logical expression is true. If both are false, returns false.

!

(Logical negation) If its single operand is true, returns false; otherwise, returns true.

Bitwise Operators

&

(Bitwise AND) Returns a one in each bit position if bits of both operands are ones.

^

(Bitwise XOR) Returns a one in a bit position if bits of one but not both operands are one.

|

(Bitwise OR) Returns a one in a bit if bits of either operand are one.

~

(Bitwise NOT) Flips the bits of its operand.

<<

(Left shift) Shifts its first operand in binary representation the number of bits to the left specified in the second operand, shifting in zeros from the right.

>>

(Sign-propagating right shift) Shifts the first operand in binary representation the number of bits to the right specified in the second operand, discarding bits shifted off.

>>>

(Zero-fill right shift) Shifts the first operand in binary representation the number of bits to the right specified in the second operand, discarding bits shifted off, and shifting in zeros from the left.

Assignment

=

Assigns the value of the second operand to the first operand.

+=

Adds two numbers and assigns the result to the first.

-=

Subtracts two numbers and assigns the result to the first.

*=

Multiplies two numbers and assigns the result to the first.

/=

Divides two numbers and assigns the result to the first.

%=

Computes the modulus of two numbers and assigns the result to the first.

&=

Performs a bitwise AND and assigns the result to the first operand.

^=

Performs a bitwise XOR and assigns the result to the first operand.

|=

Performs a bitwise OR and assigns the result to the first operand.

<<=

Performs a left shift and assigns the result to the first operand.

>>=

Performs a sign-propagating right shift and assigns the result to the first operand.

>>>=

Performs a zero-fill right shift and assigns the result to the first operand.

Comparison

==

Returns true if the operands are equal.

!=

Returns true if the operands are not equal.

>

Returns true if left operand is greater than right operand.

>=

Returns true if left operand is greater than or equal to right operand.

<

Returns true if left operand is less than right operand.

<=

Returns true if left operand is less than or equal to right operand.

Special

?:

Performs simple "if ? then : else".

,

Evaluates two expressions and returns the result of the second expression.

delete

Deletes an object property or an element at a specified index in an array.

new

Creates an instance of an object.

this

Refers to the current object.

typeof

Returns a string indicating the type of the unevaluated operand.

void

Specifies an expression to be evaluated without returning a value.

Statements

Statement | Description
break | Terminates the current while or for loop and transfers program control to the statement following the terminated loop.
continue | Terminates execution of the block of statements in a while or for loop, and continues execution of the loop with the next iteration.
delete | Deletes an object's property or an element of an array.
do ... while(condition) | Executes its statements until the test condition evaluates to false. Statement is executed at least once.
for (init; condition; increment) | Creates a loop that consists of three optional expressions, enclosed in parentheses and separated by semicolons, followed by a block of statements executed in the loop.
for (var in object) | Iterates a specified variable over all of the properties of an object. For each distinct property, JavaScript executes the specified statements.
function | Declares a JavaScript function name with the specified parameters. Acceptable parameters include strings, numbers, and objects.
if (condition) ... else | Executes a set of statements if a specified condition is true. If the condition is false, another set of statements can be executed.
labeled | Provides an identifier that can be used with break or continue to indicate where the program should continue execution.
return | Specifies the value to be returned by a function.
switch (expression) case label: | Evaluates an expression and attempt to match the expression's value to a case label.
var | Declares a variable, optionally initializing it to a value.
while (condition) ... | Creates a loop that evaluates an expression, and if it is true, executes a block of statements.
with (object) ... | Establishes the default object for a set of statements.
// | Defines comment until end of the line.
/* ... */ | Defines comment within the operators.

Core Objects

Array

Property | Description
length | Size of the array.
index | Position of matched substring (from RegExp object).
input | Original string for matching (from RegExp object).
Method | Description
concat(array1) | Joins two arrays into one array.
join(separator) | Joins array element into a string, separated by separator (defaults to ",").
pop | Removes last element from an array and returns that element.
push(e1, e2 ...) | Adds one or more elements to the end of the array and returns the last element.
reverse | Reverses the elements in the array.
shift | Removes the first element from an array and returns that element.
slice(begin, end) | Extracts elements from index begin to end and returns a new array.
sort | Sorts the elements of an array.
splice | Changes the content of an array by adding and removing elements.
toString | Returns string representation of an array.
unshift(e1, e2 ...) | Adds one or more elements to the beginning of the array and returns new array length.

Boolean

Method | Description
toString | Returns string representation of Boolean.

Date

Method | Description
getDate | Returns the day of the month.
getDay | Returns the day of the week.
getHours | Returns the hour.
getMinutes | Returns the minutes.
getMonth | Returns the month.
getSeconds | Returns the seconds.
getTime | Returns the numeric value corresponding to the time.
getTimezoneOffset | Returns the time-zone offset in minutes for the current locale.
getYear | Returns the year.
parse | Returns the number of milliseconds in a date string since January 1, 1970, 00:00:00, local time.
setDate | Sets the day of the month.
setHours | Sets the hours.
setMinutes | Sets the minutes.
setMonth | Sets the month.
setSeconds | Sets the seconds.
setTime | Sets the value of a Date object.
setYear | Sets the year.
toGMTString | Converts a date to a string, using the Internet GMT conventions.
toLocaleString | Converts a date to a string, using the current locale's conventions.
UTC | Returns the number of milliseconds in a Date object since January 1, 1970, 00:00:00, Universal Coordinated Time (GMT).

Math

Property | Description
E | Euler's constant, approximately 2.718.
LN10 | Natural logarithm of 10, approximately 2.302.
LN2 | Natural logarithm of 2, approximately 0.693.
LOG10E | Base 10 logarithm of E, approximately 0.434.
PI | Pi, approximately 3.14159.
SQRT1_2 | Square root of 1/2, approximately 0.707.
SQRT2 | Square root of 2, approximately 1.414.
Method | Description
abs | Returns the absolute value of a number.
acos | Returns the arccosine (in radians) of a number.
asin | Returns the arcsine (in radians) of a number.
atan | Returns the arctangent (in radians) of a number.
atan2 | Returns the arctangent of the quotient of its arguments.
ceil | Returns the smallest integer greater than or equal to a number.
cos | Returns the cosine of a number.
exp | Returns Enumber, where number is the argument, and E is Euler's constant, the base of the natural logarithms.
floor | Returns the largest integer less than or equal to a number.
log | Returns the natural logarithm (base E) of a number.
max | Returns the greater of two numbers.
min | Returns the lesser of two numbers.
pow | Returns base to the exponent power, that is, baseexponent.
random | Returns a pseudo-random number between 0 and 1.
round | Returns the value of a number rounded to the nearest integer.
sin | Returns the sine of a number.
sqrt | Returns the square root of a number.
tan | Returns the tangent of a number.

Number

Property | Description
MAX_VALUE | The largest representable number.
MIN_VALUE | The smaller representable number.
NaN | Not a number value.
NEGATIVE_INFINITY | Negative infinite value for overflow.
POSITIVE_INFINITY | Infinite value for overflow.
Method | Description
toString | Returns string representation of a number.

Object

Method | Description
eval | Evaluates a string of ECMAScript in the context of this object.
toString | Returns the string representation of this object.
valueOf | Returns the primitive value of the specified object.

String

Property | Description
length | Returns length of the string.
Method | Description
charAt | Returns the character at the specified index.
charCodeAt | Returns a number indicating the ISO-Latin-1 codeset value of the character at the given index.
concat | Combines the text of two strings and returns a new string.
fromCharCode | Returns a string from the specified sequence of numbers that are ISO-Latin-1 codeset values.
indexOf | Returns the index within the calling String object of the first occurrence of the specified value.
lastIndexOf | Returns the index within the calling String object of the last occurrence of the specified value.
match | Matches a regular expression against a string.
replace | Finds a match between a regular expression and a string, and replaces the matched substring with a new substring.
search | Executes the search for a match between a regular expression and a specified string.
slice | Extracts a section of a string and returns a new string.
split | Splits a string into an array of strings by separating the string into substrings.
substr | Returns the characters in a string beginning at the specified location through the specified number of characters.
substring | Returns the characters in a string between two indexes into the string.
toLowerCase | Returns the calling string value converted to lowercase.
toUpperCase | Returns the calling string value converted to uppercase.

RegExp

Property | Description
$1...$9 | Parenthesized substring matches, if any.
global | Whether to test the regular expression against all possible matches in a string, or only against the first.
ignoreCase | Whether to ignore case while attempting a match in a string.
input or $_ | The string against which a regular expression is matched.
lastIndex | The index at which to start the next match.
lastMatch or $& | The last matched characters.
lastParen | The last parenthesized substring match, if any.
leftContext or $` | The substring preceding the most recent match.
multiline or $* | Whether to search in strings across multiple lines.
right Context or $' | The substring following the most recent match.
source | The text of the pattern.
Method | Description
compile | Compiles a regular expression object.
exec | Executes a search for a match in its string parameter.
test | Tests for a match in its string parameter.

Notes

Numeric literals starting with 0 are treated as octal numbers

The JavaScript engine treats numeric literals starting with 0 as octal numbers (base 8). If such numeric literals are specified within scripts or as an ECMAScript expression in any attribute, the numbers will be converted from an octal number to a decimal number when the expressions are evaluated by the JavaScript engine. This may cause unexpected results.

For example, if you are creating an object to send an ANI with an outbound call, you may get unexpected results for ANIs that start with 0. Here are three different cases:

  1. <assign name="callvars.ani" expr="4161234444"/>

  2. <assign name="callvars.ani" expr="0146504262"/>

  3. <assign name="callvars.ani" expr="0153080631"/>

In case (1), the numeric literal does not start with 0. So it will be treated as a decimal number when the expression is evaluated, and the same string of digits will be sent as the ANI with the outbound call.

In case (2), the numeric literal starts with 0, so it will be treated as an octal number. It is a valid octal number (all the digits are less than 8), so when the expression is evaluated, it will be converted to its decimal equivalent, 26904754. Therefore, the string of digits that are sent as the ANI with the outbound call will be different from what was originally specified.

In case (3), the numeric literal starts with 0, so it will be treated as an octal number. However, it is not a valid octal number (one of the digits is 8), so it cannot be converted to its decimal equivalent. In this case, the result of evaluating the expression is the decimal value 153080631, and the same string of digits (minus the leading 0) will be sent as the ANI with the outbound call.

In any case, wrapping the number in single quotes ensures that it will be treated as a string. For numbers starting with 0, this means that there is no danger of it being converted. For example, the following variable setting ensures that the expected string of digits will be sent as the ANI with the outbound call:

<assign name="callvars.ani" expr="'0146504262'"/>

Reserved Words

Avoid using the reserved words in this list as variables, functions, methods, or object names. Some of these words are keywords; others are reserved for future use. Using some of these reserved words will cause an error event to be thrown.

  • abstract

  • boolean

  • break

  • byte

  • case

  • catch

  • char

  • class

  • comment

  • const

  • continue

  • debugger

  • default

  • delete

  • do

  • double

  • else

  • enum

  • export

  • extends

  • false

  • final

  • finally

  • float

  • for

  • function

  • goto

  • if

  • implements

  • import

  • in

  • instanceof

  • int

  • interface

  • label

  • long

  • native

  • new

  • null

  • package

  • private

  • protected

  • public

  • return

  • short

  • static

  • super

  • switch

  • synchronized

  • this

  • throw

  • throws

  • transient

  • true

  • try

  • typeof

  • var

  • void

  • volatile

  • while

  • with

Known Issues and Recommendations

If an undeclared variable appears in an ECMAScript expression, but not on the left side of an assignment statement, an error.semantic event is generated when the offending <assign> tag is executed.


Standard VoiceXML

Extended Error Events

The Next-Generation Interpreter (NGI) extends standard VoiceXML to offer error events that provide detailed information about ASR errors. The events are:

Events | Description
error.badfetch.grammar.uri | If the recognizer reports a failure to fetch a specified grammar, the Interpreter must throw the event. This does not apply for DTMF grammars.
error.badfetch.grammar.syntax | If the recognizer reports a failure to compile a specified grammar, the Interpreter must throw the event.
error.badfetch.grammar.load | If the recognizer reports a failure to load a specified grammar, the Interpreter must throw the event.


Standard VoiceXML

Properties

This topic provides details about the properties that manage platform behavior:

  • Audio Control Properties

  • DTMF Recognizer Properties

  • Fetching Properties

  • Miscellaneous Properties

  • Platform Properties

  • Prompt and Collect Properties

  • Prompt and Collect Properties—Barge-in

  • Prompt and Collect Properties—Magic Word and Selective Barge-in Recognition Modes

  • Prompt and Collect Properties—Wakeup Word Spotting Recognition Mode

  • Receive External Message Properties

  • Speech Recognizer Properties

  • Video Text Overlay Properties

  • Order of Precedence

Note: Properties apply to their parent tag and all the descendants of the parent. A property at a lower level overrides a property at a higher level.

If you already have a GVP installation, note that the properties in defaults-ng.vxml will be updated (as documented below) when a system is installed. If you upgrade from a previous release, the old values will be preserved. This means that manual configuration of defaults-ng.vxml will be saved when you upgrade. It also means that when moving to newer versions in which GVP uses different default values, the defaults will not be updated unless you install (not upgrade).

Audio Control Properties

The Audio Control Feature is a GVP extension to VoiceXML. Audio control functions are only applied to the currently playing prompt; they are not applied across the queued prompt list. These properties may not work properly for TTS.

Property | Description | Default Value
com.genesyslab.noaudiocontrol | If this property is set (to any value), the com.genesyslab.audiocontrol property is disabled. | undefined
com.genesyslab.audiocontrol | Only used if com.genesyslab.noaudiocontrol is undefined. Set to true to enable Audio Control during playing of audio. Set to false to disable the feature. | false
com.genesyslab.audio.skipduration | Sets the duration of audio to be skipped when using the skipahead/skipback features. Time units (s or ms) must be provided. | 6000ms
com.genesyslab.audio.prev | Sets the DTMF button for interrupting the current audio playback. If the DTMF is pressed when the current prompt has just started, the previous prompt will be played. Otherwise, the beginning of the current prompt will be played. If set to "-" or undefined, this feature is disabled. | 0
com.genesyslab.audio.skipahead | Sets the DTMF button for skipping ahead in the audio file/TTS. The duration skipped depends on the value of the com.genesyslab.audio.skipduration property. If set to "-" or undefined, this feature is disabled. | 1
com.genesyslab.audio.skipback | Sets the DTMF button for rewinding the audio file/TTS. The duration rewound depends on the value of the com.genesyslab.audio.skipduration property. If set to"-" or undefined, this feature is disabled. | 2
com.genesyslab.audio.pause | Sets the DTMF button for pausing playback temporarily, until the pause button is pressed a second time. If set to "-" or undefined, this feature is disabled. | 5
com.genesyslab.audio.next | Sets the DTMF button for interrupting the current audio playback, and starting the next audio playback in the queue. If set to "-" or undefined, this feature is disabled. | 6
com.genesyslab.audio.stop | Sets the DTMF button for stopping all queued audio playback. If set to "-" or undefined, this feature is disabled. | 7

DTMF Recognizer Properties

Property

Description

Default Value

com.genesyslab.dtmf.offboard_recognition

Controls the offboard DTMF recognition feature on a per-call basis. This property is in effect during the time of the first input item in execution order. The valid values are:

  • true—offboard DTMF recognition is enabled for the call.

  • false—offboard recognition is disabled for the call.

If the value is anything other than true or false, an error.semantic will be thrown.

Buffering of DTMF digits is supported as long as a DTMF recognition session has already been started and remains active. For example, if there is a transitional prompt before the first input item, DTMF digits that are pressed during the transitional prompt are not buffered. If a DTMF recognition session has been started, but the user called __ReleaseEngine(), any subsequent DTMF digits that are pressed are not buffered until another recognition session is started.

Buffered DTMF digits are lost if the DTMF recognizer is changed in the impending input item.

undefined

interdigittimeout

The timeout period allowed between each digit when recognizing DTMF input.

3s

termtimeout

The terminating timeout to use when recognizing DTMF input.

0s

termchar

The terminating DTMF character for DTMF input recognition.

#

Fetching Properties

Property

Description

Default Value

audiofetchhint

Defines when audio files can be fetched. the valid values are:

  • prefetch—audio file may be downloaded when the page is loaded

  • safe—only load the audio file when needed

Currently, all audio is fetched when needed.

prefetch

audiomaxage

Defines maximum acceptable age, in seconds, of cached audio resources.

undefined

audiomaxstale

Defines maximum staleness, in seconds, of expired cached audio resources.

undefined

datafetchhint

Defines when XML data files can be fetched:

  • safe—only load the XML data file when needed

Currently, all data files are fetched when needed.

safe

datamaxage

Defines maximum acceptable age, in seconds, of cached XML resources.

undefined

datamaxstale

Defines maximum staleness, in seconds, of expired cached XML resources.

undefined

documentfetchhint

Defines when the next document can be fetched:

  • safe—only load the next document when needed

Currently, all documents are fetched when needed.

safe

documentmaxage

Defines maximum acceptable age, in seconds, of cached documents.

undefined

documentmaxstale

Defines maximum staleness, in seconds, of expired cached documents.

undefined

grammarfetchhint

Defines when grammar files can be fetched:

  • prefetch—grammar file may be downloaded when the page is loaded

  • safe—only load the grammar file when needed

Currently, all grammars are fetched when needed.

prefetch

grammarmaxage

Defines maximum acceptable age, in seconds, of cached grammar resources.

SpeechWorks OSR 1.x does not support this.

undefined

grammarmaxstale

Defines maximum staleness, in seconds, of expired cached grammar resources.

SpeechWorks OSR 1.x does not support this.

undefined

objectfetchhint

Defines when objects can be fetched:

  • prefetch—object may be downloaded when the page is loaded

  • safe—only load the object when needed

prefetch

objectmaxage

Defines maximum acceptable age, in seconds, of cached object resources.

undefined

objectmaxstale

Defines maximum staleness, in seconds, of expired cached object resources.

undefined

scriptfetchhint

Defines when scripts can be fetched:

  • prefetch—script may be downloaded when the page is loaded

  • safe—only load the script when needed

Currently, all scripts are fetched when needed.

prefetch

scriptmaxage

Defines maximum acceptable age, in seconds, of cached script resources.

undefined

scriptmaxstale

Defines maximum staleness, in seconds, of expired cached script resources.

undefined

fetchaudio

The URI of audio to play while waiting for documents to be fetched.

builtin:background_audio.wav

fetchaudiodelay

The length of time to wait at the start of a fetch delay before playing fetchaudio.

1s

fetchaudiominimum

The minimum length of time to play fetchaudio, once started, even if the fetch result arrives in the meantime.

0s

fetchtimeout

Timeout for fetches. This is not supported when using Nuance (MRCP). An error.badfetch is thrown when a fetch duration exceeds fetchtimeout.

30s

Miscellaneous Properties

Property

Description

Default Value

com.<vendor_name>.record.enabletimeout

Enables/disables the timeout attribute of <record>. When this property is set to false, begin silence detection will be disabled.

true

com.genesyslab.loglevel

The log level limits execution of <log> tags to the ones whose level attribute have a value up to (including) the log level value.

1

com.genesyslab.private

This property enables data masking for logged metrics (interaction-level messages that describe call flow). The data that is masked is converted to asterisks, and it may contain information such as credit-card numbers, social security numbers (SSNs) and personal-identification numbers (PINs). The valid values are:

  • true—data masking is enabled, and the following data is masked:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • false—data masking is not enabled, and no data is masked.

This property is overridden by the gvp:private attribute (see the <block>, <field>, <transfer>, <record>, <subdialog>, and <initial> tags).

If this property is not specified (is the default—false) and the call flow hits a gvp:private attribute (see the <block>, <field>, <transfer>, <record>, <subdialog>, and <initial> tags) that equals true, masking is enabled. However, once the call flow hits a subsequent tag that supports the gvp:private attribute, and the attribute is not specified (is the default—false), masking is disabled.

false

Platform Properties

The following properties are specific to GVP. The first three are useful for debugging purposes.

Property

Description

Default Value

com.genesyslab.maintainer.sendwhen

This property indicates if the maintainer email message should be sent. Valid values are: always, never, on_message.

on_message

com.genesyslab.savetmpfiles

The value is interpreted as a string with a list of words. The words may be: all, none, prompts, inputs, pages, recordings. When a list of keywords is specified, the superset of all the keywords are saved. In particular, this means if someone specifies
<property name= "com.genesyslab.savetmpfiles" value="none inputs"/> it is equivalent to specifying
<property name= "com.genesyslab.savetmpfiles" value="inputs"/>.

undefined

com.genesyslab.savetmpfilesmode

This property has two valid values: immediate or delayed. This property only takes effect when com.genesyslab.savetmpfiles is enabled. If set to immediate, the files are written to disk immediately. If set to delayed, the files are stored in memory.

immediate

com.genesyslab.onexit.keeptmpfiles

This property specifies whether to keep temp files after the VoiceXML session has ended. This property will only have meaning if at least one temp file has been saved. If this value is false, all temp files on the disk will be erased, and any files in memory will be discarded. If this value is true, all temp files on disk will be kept, and files in memory will be flushed to disk.

true

com.genesyslab.maxrecordtime

Defines the default (also the upper limit) for the maxtime attribute of the <record> tag.

10 minutes

Prompt and Collect Properties

Property

Description

Default Value

inputmodes

Determines which input methods to use. Value is a space separated list of input methods:

  • dtmf—allows DTMF sequences as input

  • voice—allows voice as input

dtmf voice

timeout

Once the prompt has finished playing, the length of time to wait, if no speech or dtmf input occurs, before throwing a noinput event.

10s

universals

Specifies universal command grammars to activate. Value is a space-separated list of all or fewer of the following command grammars:

  • cancel—If this grammar is activated, and the caller says "cancel" (or equivalent phrase configured for another language), the cancel event is thrown.

  • exit—If this grammar is activated, and the caller says "exit" (or equivalent phrase configured for another language), the exit event is thrown.

  • help—If this grammar is activated, and the caller says "help" (or equivalent phrase configured for another language), the help event is thrown.

A setting of none disables universal commands. A setting of all can be used as a short form for activating all three command grammars.

undefined

com.genesyslab.asrengine

(GVP extension)

Specifies the name of the ASR engine to use. For details about available names, consult with your platform administrator.

If this property is not specified, the per call configuration value specified in the vxmli.asr.defaultengine property (see the Genesys Voice Platform 8.1 Configuration Options Reference) will be used. The default value of the com.genesyslab.asrengine property is an empty string ("").

It is valid to specify a particular engine only if that engine is installed for the platform running the application. Otherwise, an error.asr.unknownengine event will be thrown.

The configured name for SpeechWorks OSR must be speechworks, otherwise a recognition error will occur.

platform-specific

com.genesyslab.ttsengine

(GVP extension)

Specifies the name of the TTS engine to use (that is, the voice). For details about available names, consult with your platform administrator.

If this property is not specified, the per call configuration value specified in the vxmli.tts.defaultengine option is used (see the Genesys Voice Platform 8.1 Configuration Options Reference).

The default value is an empty string ("").

It is valid to specify a particular engine only if that engine is installed for the platform running the application. Otherwise, an error.tts.unknownengine event will be thrown.

platform-specific

com.genesyslab.endbeep

(GVP extension)

Specifies whether a beep should be played at the end of prompts in fields, when bargein is disabled. When bargein is enabled, this attribute has no effect (there is never a beep). Platform owners can access the audio file (endofprompt.vox) in the configured audio path.

false

com.genesyslab.utterancedest

(GVP extension)

Specifies the path of the directory to use for saved utterance audio files. The value will be resolved to the configured audio path. This property can be used with the recordutterance property.

If you specify the utterancedest and enable the savetmpfiles property, the utterance will only be saved under the utterancedest path. It will not also be saved with the other tmp files.

Files written to the tmp directory may or may not be saved, depending on whether the savetmpfiles property is enabled.

tmp directory

recordutterance

(VoiceXML 2.1 feature)

This property tells the platform to enable recording while simultaneously gathering input from the user. Set to true to enable user utterance to be recorded. Set to false otherwise. Upon completion of user input, the recording shadow variable will be set.

The <vxml> version attribute must be specified as 2.1 (or higher) to use this property.

If the recordutterance property has been specified in a VoiceXML 2.0 page, it will behave as if it is a VoiceXML 2.1 page.

false

recordutterancetype

(VoiceXML 2.1 feature)

This property specifies the audio format to use for recording utterances. Only used with the recordutterance property. GVP currently supports the following types:

  • audio/basic—Raw (headerless) 8kHz 8-bit mono mu-law [PCM] single channel. (G.711)

  • audio/x-alaw-basic—Raw (headerless) 8kHz 8-bit mono a-law [PCM] single channel. (G.711)

  • audio/x-wav—WAV (RIFF header) 8kHz 8-bit mono mu-law [PCM] single channel.

  • audio/x-wav—WAV (RIFF header) 8kHz 8-bit mono a-law [PCM] single channel.

audio/basic

com.genesyslab.asr.get_swi_literaltimings

(GVP extension)

Set to true to allow the special OSR variable, SWI_literalTimings, to be accessed through the application.lastresult$ variable. Requires com.genesyslab.fieldobject to be set to true. Available with SpeechWorks ASR only.

false

com.genesyslab.asr.<Your vendor specific name>

(GVP extension)

When using GVP's MRCP direct integration with an ASR engine, the VoiceXML application can use this property format to specify arbitrary vendor-specific parameters to be sent to the ASR engine.

In the property name, <Your vendor specific name> is replaced with the actual vendor-specific parameter name, and the value of the property must be a valid value for that vendor-specific parameter. For example, to set Nuance's rec.GrammarWeight parameter to 10:

<property name="com.genesyslab.asr.rec.GrammarWeight" value="10"/>

Vendor parameter names and values may be case-sensitive. Refer to the vendor documentation to ensure you are using valid names and values.

You can only set a vendor parameter using <property> if the parameter can be set by the ASR engine at runtime. Refer to the vendor documentation to confirm which parameters are runtime-settable.

Once a vendor parameter is set using <property>, the setting will stay in effect for the remainder of the call, unless it is set again later in the VoiceXML application.

parameter-specific

com.genesyslab.asr.swiep*
and
com.genesyslab.asr.swirec*

(GVP extension)

Many of OSR's swiep_*/swirec_* configuration parameters can also be set as VoiceXML properties.

To find out whether a particular parameter can be set as a property, check the OSR Reference Manual. If the line under the parameter name includes "API" (and if the description mentions SWIepSetParameter() or SWIrecRecognizerSetParameter()), it can be set as a property.

Some of the parameters that are commonly used are:

  • Swirec_suppress_event_logging

  • Swirec_suppress_waveform_logging

  • Swirec_audio_environment (OSR 2.0+ only)

  • Swirec_backward_compatible_confidence_scores (OSR 2.0+ only)

See the OSR Reference Manual for details about the values/usage for each parameter.

These properties are specific to Nuance OSR, and are only supported in GVP's MRCP native integration with OSR. They are not supported in GVP's MRCP direct integration with OSR, using SWMS.

parameter-specific

com.genesyslab.asr.secure_context

(GVP extension)

Set this property to 1 to suppress ASR logging with NSS 5.x and NRec 9.0 or higher.

undefined

com.genesyslab.logtoasr

(GVP extension)

If set to true, this enables GVP to log data directly to the ASR engine's log, and the <log> tag's level attribute is ignored.

false

com.genesyslab.tts.<Your vendor specific name>

(GVP extension)

When using GVP's MRCP direct integration with a text-to-speech (TTS) engine, the VoiceXML application can use this property format to specify arbitrary vendor-specific parameters to be sent to the TTS engine.

In the property name, <Your vendor specific name> is replaced with the actual vendor-specific parameter name, and the value of the property must be a valid value for that vendor-specific parameter. For example, to set switts.ssftrs_dict_enable parameter to http://10.0.0.136/~csong/dict1.dct:

<property name="com.genesyslab.tts.switts.ssftrs_dict_enable" value="http://10.0.0.136/dict1.dct"/>

Vendor parameter names and values may be case-sensitive. Refer to the vendor documentation to ensure you are using valid names and values.

You can only set a vendor parameter using <property> if the parameter can be set by the TTS engine at runtime. Refer to the vendor documentation to confirm which parameters are runtime-settable.

undefined

com.genesyslab.tts.switts.secure_context.

Set to 1 to suppress TTS logging with NSS 5.x and Vocalizer 5.0 or higher.

undefined

Prompt and Collect Properties—Barge-in

GVP supports recognition-based Barge-in.

Property

Description

Default Value

bargein

Controls whether user input can be collected before prompts have finished playing:

  • true—Any user input can barge in during prompts.

  • false—No user input can barge in during prompts.

true

bargeintype

Specifies the bargein type:

  • speech—Any user utterance can barge in the prompt.

  • hotword (equivalent to recognition)—Only user input that matches a grammar can barge in on the prompt.

  • dtmf—Only dtmf input can barge in on the prompt. This value is a Genesys extension and is only supported using the onboard DTMF recognizer.

Not all bargeintypes are supported with all ASR engines.

speech

Prompt and Collect Properties—Magic Word and Selective Barge-in Recognition Modes

With Nuance SWMS 3.1.4+, OSR's magic word and selective barge-in features are exposed through the following properties.

Note: GVP does not have default values for the following properties. If the application specifies them, GVP passes the specified values through to SWMS. Otherwise, GVP does not pass anything to SWMS—in which case, SWMS would use its own default settings (see the SWMS documentation for these details).

Property

Description

Default Value

com.genesyslab.ASR.Recognition-Mode

(GVP extension)

Set to hotword to enable the OSR selective barge-in or magic word recognition mode:

  • selective barge-in—Only user input that matches a grammar can barge in on the prompt. (This mode is enabled if com.genesyslab.ASR.Hotword-Max-Duration is set to 0.)

  • magic word—Only user input that matches a grammar, and whose duration is between a minimum and maximum length, can barge in on the prompt. (The minimum and maximum utterance lengths are specified by com.genesyslab.asr.Hotword-Min-Duration and com.genesyslab.asr.Hotword-Max-Duration.)

For example:

<property name="com.genesyslab.asr.Recognition-Mode" value="&quot;hotword&quot;"/>

After setting this property, the specified mode will remain in effect for all subsequent recognitions (even if the property is not set in subsequent input fields), unless a new mode is explicitly set. So, to switch back to normal recognition mode after using one of the above hotword modes, the application must explicitly set this property back to normal (and not set any of the three related properties listed below). For example:

<property name="com.genesyslab.asr.Recognition-Mode" value="&quot;normal&quot;"/>

Available with Nuance SWMS 3.1.4+ only.

undefined

com.genesyslab.asr.Hotword-Min-Duration

(GVP extension)

If com.genesyslab.asr.Recognition-Mode is set to hotword, this specifies the minimum length (in ms) that input must be in order for recognition to be performed. For example:

<property name="com.genesyslab.asr.Hotword-Min-Duration" value="&quot;50&quot;"/>

If com.genesyslab.asr.Hotword-Max-Duration is set to 0, this property will be ignored.

undefined

com.genesyslab.asr.Hotword-Max-Duration

(GVP extension)

If com.genesyslab.asr.Recognition-Mode is set to hotword, this specifies the maximum length (in ms) that input may be in order for recognition to be performed. For example:

<property name="com.genesyslab.asr.Hotword-Max-Duration" value="&quot;2000&quot;"/>

If this property is set to 0, the OSR selective barge-in mode will be enabled (for example, no minimum and maximum duration constraints are used, so com.genesyslab.asr.Hotword-Min-Duration will be ignored). Otherwise, the OSR magic word mode will be enabled (for example, the minimum and maximum duration constraints specified by com.genesyslab.asr.Hotword-Min-Duration and com.genesyslab.asr.Hotword-Max-Duration will be used).

undefined

com.genesyslab.asr.Hotword-Confidence-Threshold

(GVP extension)

If com.genesyslab.asr.Recognition-Mode is set to hotword, this specifies the speech recognition confidence level that should be used. Values range from 0 (minimum confidence) to 1000 (maximum confidence). Recognition results are rejected (a nomatch event is thrown) if the confidence level of the results is below this threshold.

For this property to take effect, you must also set the standard confidencelevel property to an equivalent decimal percentage. For example:

<property name="com.genesyslab.asr.Hotword-Confidence-Threshold" value="&quot;100&quot;"/> <property name="confidencelevel" value="0.1"/>

undefined

Prompt and Collect Properties—Wakeup Word Spotting Recognition Mode

In GVP's MRCP native integration with Nuance OSR, OSR's "magic word" feature is exposed through
the following properties.

Property | Description | Default Value
com.genesyslab.wakeupword (GVP extension) | Specifies whether Wakeup Word Spotting should be used for input in fields, menus, and initials. If set to true, recognition is only performed if input length is between a minimum and maximum length, and (only with Nuance OSR 2.0+) if input matches a grammar. | false
com.genesyslab.wakeupwordminimum (GVP extension) | If com.genesyslab.wakeupword is set to true, this specifies the minimum length that input must be in order for recognition to be performed. | 500ms
com.genesyslab.wakeupwordmaximum (GVP extension) | If com.genesyslab.wakeupword is set to true, this specifies the maximum length that input may be in order for recognition to be performed. | 3000ms

Receive External Message Properties

Property

Description

Default Value

com.genesyslab.externalevents.enable

(GVP extension)

This property specifies whether an external message will be received asynchronously. The valid values are:

  • true—external messages will be received asynchronously.

  • false—external messages will be received synchronously.

false

com.genesyslab.externalevents.queue

(GVP extension)

This property specifies whether an external message will be queued or discarded. The valid values are:

  • true—external messages will be queued. The external message is reflected to the application in the application.lastmessage$ variable (an ECMAScript object).

  • false—external messages will not be delivered as a VoiceXML event (they will be discarded).

If no external messages have been received, application.lastmessage$ is ECMAScript undefined. Only the last received message is available. To preserve a message for future reference during the lifetime of the application, copy the data to an application-scoped variable.

false

Speech Recognizer Properties

Property

Description

Default Value

confidencelevel

Specifies the speech recognition confidence level. Values range from 0.0 (minimum confidence) to 1.0 (maximum confidence). Recognition results are rejected (a nomatch event is thrown) if the confidence level of the results is below this threshold.

0.5

sensitivity

Specifies the level of sensitivity to speech. Values range from 0.0 (least sensitive to noise) to 1.0 (highly sensitive to quiet input).

0.5

speedvsaccuracy

A hint specifying the desired balance between speed versus accuracy when processing a given utterance. Values range from 0.0 (fastest recognition) to 1.0 (best accuracy).

The Nuance MRCP engine uses the value of the speedvsaccuracy property to set its proprietary rec.Pruning parameter, using the following algorithm:

If x is the speedvsaccuracy value, and x <= 0.5 then
rec.Pruning = (x * 400) + 600
else
rec.Pruning = (x * 800) + 400

0.5

completetimeout

The length of silence required following user speech before the speech recognizer finalizes a result (either accepting it or throwing a nomatch event). The completetimeout is used when the speech is a complete match of an active grammar and no further words can be spoken.

1s

incompletetimeout

The length of silence required following user speech before the speech recognizer finalizes a result (by either accepting it or throwing a nomatch event). In contrast to completetimeout, the incompletetimeout is used when the speech is an incomplete match to an active grammar, or when the speech is a match but it is possible to speak further.

1s

maxspeechtimeout

The maximum duration of user speech. If this time elapses before the user stops speaking, the maxspeechtimeout event is thrown.

Refer to your ASR engine documentation for support details.

60s

maxnbest

Maximum number of results returned by the recognizer. Also represents the maximum size of the application.lastresult$ array.

1

Video Text Overlay Properties

Property | Description | Default Value
com.genesyslab.videotext.fontname | Specifies the default font name used in a text overlay of video. It accepts a string. | ""
com.genesyslab.videotext.fontstyle | Specifies the default font style used in a text overlay of video. It accepts a string. | ""
com.genesyslab.videotext.fontcolor | Specifies the default font color used in a text overlay of video. It must be specified in HTML color code. It accepts a string. | ""
com.genesyslab.videotext. bgcolor | Specifies the default font background color used in a text overlay of video. It must be specified in HTML color code. It accepts a string. | ""
com.genesyslab.videotext.fontsize | Specifies the default font size used in a text overlay of video. It must be specified in a scale of 0-1000. It accepts an integer. | 80
com.genesyslab.videotext.fontwidth | Specifies the default font width used in a text overlay of video. It must be specified in a scale of 0-1000. It accepts an integer. | 0
com.genesyslab.videotext.xoffset | Specifies the default horizontal/X offset of a text overlay from the left margin in a scale of 0-1000. It accepts an integer. | 0
com.genesyslab.videotext.yoffset | Specifies the default vertical/Y offset of a text overlay from the top margin in a scale of 0-1000. It accepts an integer. | 0

Order of Precedence

To find the property value that will take effect at a particular point in an application, the current form item is checked first (to see if the property is defined there), and enclosing scopes are checked as necessary.

Here is the full order of precedence for properties:

  1. Look for a property in the current form item (for example, in <field>, <record>, <transfer>, and so on). If found, use its value.

  2. If not found, check the current form (for example, look directly under <form> or <menu>). If the property is found, use its value.

  3. If not found, check the current document (for example, look directly under <vxml>). If the property is found, use its value.

  4. If not found, check the current document's application root document (if specified by <vxml application="..."> in the current document). If the property is found, use its value.

  5. Finally, if not found in any of the above, use the setting from the Interpreter context for the current call, which includes the settings in the defaults file (for example, defaults.vxml) and hard-coded default values that are used if no value is configured anywhere else.


Standard VoiceXML

Variables

VoiceXML variables and ECMAScript variables share the same variable space. In other words, variables declared in a <script> tag can be used in VoiceXML, and ECMAScript can use variables declared by a <var> tag. There are three ways that variables can be declared:

  • Declared by a <var> tag

  • Declared within the <script> tag in an ECMAScript block

  • Input item variables declared by one of the form items: <block>, <field>, <initial>, <object>, <record>, <subdialog>, and <transfer>

Scope

VoiceXML defines the following variable scopes:

  • Session—Session variables are available to all VoiceXML applications within a particular session. They are declared by the Interpreter and are read-only. New session variables cannot be declared by VoiceXML documents.

  • Application—Application variables are available to the root document and its application leaf documents. They are declared by the <var> tags of application root document's <vxml> tag.

  • Document—Document variables are available within the VoiceXML document. They are declared by the <var> tags that are children of the <vxml> tag. Certain form items (<field>, <record>, and <transfer>) may declare shadow variables in addition to the field item variable itself. Refer to each tag reference for detailed information.

  • Dialog—Each dialog (<form> or <menu>) has a dialog scope that exists while the user is visiting the dialog. Variables are declared by <var> tags or by form items.

  • (Anonymous)—<block>, <filled>, and <catch> (including <error>, <help>, <noinput>, and <nomatch>) tags define an anonymous scope to contain variables declared in that tag. Other predefined anonymous variables are available within the <catch> and <enumerate> tags. Refer to the tag reference for detailed information.

Session Variables

Undefined Session Variables

Session variables that are not applicable are assigned the ECMAScript undefined keyword. If session variables are submitted with an HTTP request, the value (on the right side of the equal sign) will be empty for any variable that is undefined.

VoiceXML Session Variables

The following are the standard VoiceXML session variables.

Variable

Description

session.com.genesyslab

This object contains all headers that are prefixed with X-Genesys-.

session.com.genesyslab.sessionid

This variable represents the globally unique session ID for the currently executing VoiceXML session. The variable is created by the Media Platform.

session.com.genesyslab.userdata

This variable has the same properties as session.connection.protocol.sip.headers. The property is considered to be userdata, except the prefix will be stripped from the property name.

session.com.genesyslab.userdata.calluuid

This variable is the Universal Unique Identifier (UUID) that is generated by T-Server or SIP Server for the customer interface.

session.com.genesyslab.userdata[’gvp-session-id’]

This variable identifies a call session for a particular GVP Resource. The variable is generated by:

  • Resource Manager when it creates a new session in response to a new
    SIP invite request.

  • Call Control Platform when it initiates a new session for an outbound call.

The value is provided in the following format:

<GUID>[;gvp.rm.cti-call=1][;gvp.rm.datanode=<datanode>][;gvp.rm.tenant-id=<tenant info>]

Note: This variable displays the full SIP header, so the parameter list may continue to expand (any text that appears after the semi-colon is a GVP specific attribute).

session.com.genesyslab.userdata[’r;gvp-att-coda’].

The SIP History-Info header can be accessed using this variable. The value contains the billing number and iidigits in the following format:

X-Genesys-GVP-ATT-CODA: BillingNumber=<billing number> ;IIDigits=<information indicator digits>.

This is only available with the PSTN Connector.

The GVP 8.1.5 release does not contain the PSTN Connector component. Only GVP 8.1.2, 8.1.3, and 8.1.4 releases contain the PSTN Connector. See the Genesys Migration Guide for information about using PSTN Connector 8.1.4 with the GVP 8.1.5 release.

session.connection.aai

Application-to-Application Information (aai) or User-to-User Information provides the data string passed during the connection set-up.

For example, if the current VoiceXML application was called by another application's <transfer> or <call>, with aai or aaiexpr set, the aai data string will be available as session.connection.aai in the current application (assuming the network configuration supports the transmission of aai data).

When the aai is provided as a JSON value, the JSON object will be exposed via the session variable as an ECMAScript object, as defined in RFC5552. Otherwise, the aai value will be exposed as a string.

Generally not supported with SIP.

session.connection.ccxml

When the VoiceXML application is initiated using CCXML, this session variable contains the information provided in the namelist attribute of the CCXML <dialogprepare> or <dialogstart>.

session.connection.local.uri

Represents a URI of a GVP platform.

session.connection.originator

This variable represents the originator device. It is equal to either:

  • session.connection.local

  • session.connection.remote

If the local uri and/or remote uri variables have not been enabled, the originator variable (if it has been enabled) will be undefined.

session.connection.protocol.name

Represents the name of the underlying connection protocol.

session.connection.protocol.sip.headers[’<sip header name>’].

This variable is defined in RFC5552, and can be used to access the SIP header value of the initial SIP INVITE request. The SIP header name must be in lowercase.

session.connection.protocol.sip.requesturi[’cs_base_url’]

This contains the base URL of the Context Services as configured in the service parameter in the IVR Profile.

session.connection.protocol.version

Represents the version of the connection protocol. Not currently supported.

session.connection.protocol.<your name>

When session.connection.protocol.name is available, this variable is a member of the session.connection.protocol object, with the <Your name> specified by session.connection.protocol.name. For instance, if session.connection.protocol.name is h323, there will be a session variable session.connection.protocol.h323, which will be an ECMAScript object, with members and values specific to the H.323 protocol.

session.connection.redirect

This variable is an array representing the connection redirection paths. The first tag is the original called number, the last tag is the last redirected number. Each tag of the array contains a uri, pi (presentation information), si (screening information), and reason property. The reason property can be:

  • unknown

  • user busy

  • no reply

  • deflection during alerting

  • deflection immediate response

  • mobile subscriber not reachable

This is supported with ISDN (Dialogic, Brooktrout), SIP, H.323.

session.connection.remote.uri

Represents a URI of the remote caller device.

session.connection.uuid

This variable is the UUID provided by the SIP Server.

If this variable is not provided, the variable will be ECMAScript undefined.

Application Variables

VoiceXML Application Variables

Application variables defined in the root document can be referenced by the application leaf documents as application.<Your variable name>. The application.lastresult$ shadow variable can be modified by a VoiceXML application. When any shadow variable is not set, its value will be ECMAScript undefined.

The following are standard VoiceXML application variables:

Variable | Description
application.lastresult$ | This read-only variable holds information about the last recognition to occur within this application. It is an array of tags application.lastresult$[i] for the N-best recognition.
application.lastresult$[i].ambig_interpretation | If the interpretation is ambiguous, then this array is populated with each interpretation.
application.lastresult$[i].confidence | The confidence level for this result ranges from 0.0 (minimum confidence) to 1.0 (maximum confidence).
application.lastresult$[i].inputmode | The mode in which user input was provided: dtmf or voice.
application.lastresult$[i].interpretation | The interpretation of this result (set of slot names and values). Each slot is mapped as a property of the object.
application.lastresult$.markname | (VoiceXML 2.1 feature) The name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. For more details, see <mark>.
application.lastresult$.marktime | (VoiceXML 2.1 feature) The number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. For more details, see <mark>.
application.lastresult$.recording | (VoiceXML 2.1 feature) This variable stores a reference to the recording, or undefined if no audio is collected (like application.lastresult$.utteranceaudio). This shadow variable is only set if the recordutterance property is set to true.
application.lastresult$.recordingduration | (VoiceXML 2.1 feature) This variable stores the duration of the recording (in milliseconds), or is undefined if no audio is collected (like application.lastresult$.duration). This shadow variable is only set if the recordutterance property is set to true.
application.lastresult$.recordingsize | (VoiceXML 2.1 feature) This variable stores the size of the recording in bytes, or undefined if no audio is collected (like application.lastresult$.size). This shadow variable is only set if the recordutterance property is set to true.
application.lastresult$[i].utterance | The raw string of words that were recognized for this result.<Your field name>$.utterance, lastresult$.utterance, and lastresult$[0].utterance will all be identical and contain the utterance with the best confidence score. lastresult$[i].utterance, where i>0 and i<maxnbest-1, will each contain the utterance for the ith result.

GVP Application Variables

Variable

Description

application.lastresult$.activegrammars[]

An array containing all the grammar objects that were active at the time of the recognition. This will contain a valid value whenever voice input is recognized.

application.lastresult$.audiooffset

The offset of audio data on bargein, in milliseconds. The offset is calculated from the beginning of each prompt element. The value is -1 if the prompt was played to the end without bargein. This is a Genesys extension.

application.lastresult$.bargein

This is true if bargein occurred, false otherwise.

application.lastresult$.triggeredgrammar

The matched result's grammar object. This will contain a valid value any time voice input is recognized. For now, DTMF input will not result in this variable being set to a meaningful value.

This variable will be undefined in the case of a nomatch event or a timeout.

application.lastmessage$.content

This variable contains the content of the message, if any, or is ECMAScript undefined. If the Content-Type of the message is one of the media types described in RFC 3023, the VoiceXML Interpreter must expose the retrieved content using a read-only subset of the Document Object Model (DOM) as described in the W3C Voice Extensible Markup Language VoiceXML 2.1 specification.

An Interpreter may support additional data formats by recognizing additional media types. If an Interpreter receives an external message with a payload in a data format that it does not understand, or the payload is not well-formed as defined by the specification of that format, the Interpreter throws error.badfetch.

application.lastmessage$.contenttype

This variable contains the media type of the external message.

application.lastmessage$.event

This variable contains the event name, if any, or is ECMAScript undefined if no event name was included in the external message.

application.lastmessage$.headers

This variable contains a list of property names and values corresponding to the network parameters name-value pairs as received from the application module.

application.lastmessage$.source

This variable contains the URI or equivalent source identifier of the message.

application.lastmessage$.sourcetype

This variable contains the protocol (for example file, http, SIP) used to send the message.

application.lastresult$.xmlresult

This variable exposes the NLSML XML data using a read-only subset of the World Wide Web Consortium (W3C) Document Object Model (DOM).


SSML Overview

Standard VoiceXML > SSML Tags

Overview

This page provides a list of the Speech Synthesis Markup Language (SSML) tags available for managing text-to-speech (TTS) pronunciation, rate, pitch, and so on.

Some speech-synthesis processors do not support the use of all SSML tags. For details, see your speech-synthesis processor documentation.

The SSML tags include are:

A - D | E - L | M - O | P - R | S - U | V - Z
<audio> <break> <desc> | <emphasis> <lexicon> | <mark> <meta> <metadata> | <p> <phoneme> <prosody> | <say-as> <s> <speak> <sub> | <voice>


Audio

Standard VoiceXML > SSML Tags

<AUDIO>

The SSML <audio> tag supports the insertion of recorded audio files and the insertion of other audio formats in conjunction with synthesized speech output. The <audio> tag may be empty. If the <audio> tag is not empty, then the content should be the marked-up text to be spoken if the audio document is not available. The content may:

  • Include text (#PCDATA), speech markup, or other audio tags.

  • Be used when rendering the document to non-audible output and for accessibility.

An <audio> tag is successfully rendered:

  • If the referenced audio source is played.

  • If the synthesis processor is unable to execute the first audio output but the alternative content is successfully rendered.

  • If the processor can detect that text-only output is required and the alternative content is successfully rendered.

Deciding which conditions result in the alternative content being rendered is speech-synthesis processor-dependent. If the <audio> tag is not successfully rendered, a speech-synthesis processor should continue processing and should notify the hosting environment. The speech-synthesis processor may determine after beginning playback of an audio source that the audio cannot be played in its entirety. For example, encoding problems and/or network disruptions may occur. The speech-synthesis processor may designate this either as successful or unsuccessful rendering, but it must document this behavior.

Syntax

<audio src="Your URI">
   child tags
</audio>

Attributes

Attribute | Description
src | Specifies the URI of an audio file to play.

Parent

Audio, Emphasis, Enumerate, P, Prompt, Prosody, S, Speak, and Voice

Child

Audio, Break, Desc, Emphasis, Mark, P, Phoneme, Prosody, Say-as, S, Sub, Text (#PCDATA), and Voice

Example

<!-- Empty tag -->
<audio audio src="beep.wav"/>
<!-- Tags with alternative text -->
<audio src="prompt.au">
  What city do you want to fly from?
</audio>
<audio src="welcome.wav">
  <emphasis>Welcome</emphasis> to the Voice Portal.
</audio>
<audio src="thankyou.vox">
  If you can hear this, thankyou.vox was not found.
</audio>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <audio> tag.


Break

Standard VoiceXML > SSML Tags

<break>

The SSML <break> tag is an empty tag that specifies the pause in speech output. If the tag is present, the behavior of the speech-synthesis processor is overridden. If the tag is not present, the speech-synthesis processor determines breaks based on the linguistic context.

Syntax

<break
   strength="none"|"x-weak"|"weak"|"medium"|"strong"|"x-strong"
   time="Your time interval">

Attributes

Attribute

Description

strength

(Optional) Specifies the relative pause duration. The actual pause duration depends on the speech-synthesis processor. Valid values are:

  • x-weak

  • extraweak

  • weak

  • medium

  • strong

  • x-strong

  • extrastrong

The default value is medium.

time

(Optional) Specifies an absolute pause in seconds or milliseconds.

Parent

Audio, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

None.

Example

<prompt>
   Take a deep breath <break/> then continue.
   Press 1 or wait for the tone. <break time="3s"/>
   I didn't hear you! <break strength="weak"/>
   Please repeat.
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <break> tag.

The Next Generation Interpreter (NGI) will execute the break, independent of the speech synthesis processor, when the <break> tag is not within SSML.


Desc

Standard VoiceXML > SSML Tags

<desc>

The SSML <desc> tag can only occur within the content of the <audio> tag. When the audio source referenced in audio is not speech, for example, audio wallpaper or sonicon punctuation, it should contain a <desc> tag with textual content that describes the audio source (for example, "door slamming"). If text-only output is being produced by the speech-synthesis processor, the content of the <desc> tag should be rendered instead of other alternative content in audio.

Syntax

<desc xml:lang="Your predfined language value">
   text
</desc>

Attributes

Attribute

Description

xml:lang

(Optional) This attribute can be used to indicate that the content of the tag is in a different language from that of the content surrounding the tag.

The presence or absence of this attribute will have no effect on the output in the normal case of audio (rather than text) output.

Parent

Audio

Child

None.

Example

<!-- Normal use of <desc> -->
Heads of State often make mistakes when speaking in a foreign language.
One of the most well-known examples is that of John F. Kennedy:
<audio src="ichbineinberliner.wav">
   If you could hear it, this would be a recording of John F. Kennedy
   speaking in Berlin. <desc>Kennedy's famous German language gaffe</desc>
</audio>
<!-- Suggesting the language of the recording -->
<!-- Although there is no requirement that a recording be in the current language
     (since it might even be non-speech such as music), an author might wish to
     suggest the language of the recording by marking the entire <audio> tag
     using <voice>. In this case, the <desc> xml:lang attribute can be used
     to put the description back into the original language.
-->
Here's the same thing again but with a different fallback:
<voice xml:lang="de-DE">
   <audio src="ichbineinberliner.wav">
      Ich bin ein Berliner.
      <desc xml:lang="en-US">
         Kennedy's famous German language gaffe
      </desc>
   </audio>
</voice>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <desc> tag.


Emphasis

Standard VoiceXML > SSML Tags

<emphasis>

The SSML <emphasis> tag specifies that the text should be spoken with emphasis.

Syntax

<emphasis level="strong"|"moderate"|"none"|"reduced">
    child tags
</emphasis>

Attributes

Attribute

Description

level

(Optional) Specifies the level of emphasis. Valid values are:

  • strong

  • moderate

  • none

  • reduced

Parent

Audio, Emphasis, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

Audio, Break, Emphasis, Mark, Phoneme, Prosody, Say-as, Sub, Text (#PCDATA), Value, and Voice

Example

<prompt>
   Hello, <emphasis level="strong">world</emphasis>!
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <emphasis> tag.


Lexicon

Standard VoiceXML > SSML Tags

<lexicon>

The SSML <lexicon> tag references one or more lexicon documents (sometimes called dictionaries). A lexicon document:

  • Is an external document.

  • Contains pronunciation information for words and phrases that can appear in the text to be spoken.

There is no standard format supported for lexicon documents. The proprietary formats that are supported, and the pronunciation handling of the documents, are specific to each speech-synthesis processor. There is a <lexicon> tag for grammars.

Syntax

<lexicon
   uri="Your lexicon file's URI"
   type="Your MIME type"
/>

Attributes

Attribute | Description
uri | The Uniform Resource Identifier (URI) of the lexicon document.
type | (Optional) The Multipurpose Internet Mail Extensions (MIME) type of the lexicon document. The supported types (and default values) for this attribute depend on the speech-synthesis processor being used.

Parent

Audio, Enumerate, Foreach, Prompt, and Speak

Child

None.

Example

<prompt>
   <lexicon uri="http://www.example.com/lexicon.xml"/>
   Hello, world!
</prompt>

Known Issues and Recommendations

When multiple lexicons are referenced, their precedence goes from lower to higher with document order. Precedence means that a word or phrase is looked up in the lexicon with highest precedence first. If the word or phrase is not found in that lexicon, the next lexicon is searched. This process repeats until a first match occurs or until all lexicons have been used for lookup.

The <lexicon> tags must occur at the beginning of the SSML content.

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <lexicon> tag.


Mark

Standard VoiceXML > SSML Tags

<mark>

The SSML <mark> tag is an empty tag that places a marker in the text or tag sequence. It can be used to reference a specific location in the text or tag sequence, or to insert a marker into an output stream for asynchronous notification. When processing a <mark> tag, a speech-synthesis processor must do one or both of the following:

  • Inform the hosting environment with the value of the name attribute and with information allowing the platform to retrieve the corresponding position in the rendered output.

  • Issue an event that includes the required name attribute of the tag when audio output of the SSML document reaches the mark. The hosting environment defines the destination of the event.

The <mark> tag does not affect the speech output process.

Syntax

<mark
   name="Your mark name"
   nameexpr="Your ECMAScript expression"
/>

Attributes

Attribute | Description
name | (Optional) The name of this mark. This name can be referenced by the VoiceXML application.
nameexpr | (Optional) An ECMAScript expression to be evaluated as the name of the mark, as above. If nameexpr cannot be evaluated, an error.semantic event is thrown.

Parent

Audio, Enumerate, Foreach, and Prompt

Child

None.

Example

<prompt>
  <mark name="ad_start"/>
    Baseball scores brought to you by Elephant Peanuts.
    There's nothing like the taste of fresh roasted peanuts.
    Elephant Peanuts. Ask for them by name.
  <mark name="ad_end"/>
  <break time="500ms"/>
    Say the name of a team. For example, say Boston Red Sox.
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <mark> tag.

The GVP Next Generation Interpreter (NGI) will execute the mark, independent of the speech-synthesis processor engine, when the <mark> tag is not within SSML.

Some versions of RealSpeak support only numeric mark names (for example, "1234"). If you are using this speech-synthesis processor, refer to their documentation for details.


Meta

Standard VoiceXML > SSML Tags

<meta>

The SSML <meta> tag provides general information about the SSML file. It does not provide information about the file's content. The <meta> tag can specify a property of the file, or it can specify HTTP response headers. The Metadata tag provides a more general and powerful treatment of metadata information than <meta>, by using a metadata schema.

Note: A <meta> tag exists for VoiceXML files (see VoiceXML Meta) and for grammars.

Syntax

<meta
   content="Your content"
   name="seeAlso"|"Your property name"|http-equiv="Your http-equivalent content"
/>

Attributes

Either name or http-equiv is required. If both of these attributes are provided, an error will be thrown.

Attribute

Description

content

The value of the metadata property.

name

The value can be either:

  • seeAlso (a defined value). This value is used to specify a resource that might provide additional metadata information about the content.

  • Your own property name value.

http-equiv

This attribute specifies the name of an HTTP response header. It has a special significance when documents are retrieved using HTTP. Although the preferred method of providing HTTP header information is to use HTTP header fields, the http-equiv content may be used in situations in which the SSML document author is unable to configure HTTP header fields associated with their document on the origin server, for example, cache control information.

HTTP servers and caches are not required to introspect the contents of meta in SSML files and thereby override the header values they would send otherwise.

Parent

Audio, Enumerate, Foreach, Prompt, and Speak

Child

None.

Example

<prompt>
   <meta
      name="seeAlso"
      content="http://example.com/my-ssml-metadata.xml"
   />
   <meta
      http-equiv="Cache-Control"
      content="no-cache"
   />
   Hello, world!
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <meta> tag.


Metadata

Standard VoiceXML > SSML Tags

<metadata>

The SSML <metadata> tag contains information about the SSML file. It provides general metadata information by using a metadata schema. Although any metadata schema can be used with <metadata>, Genesys recommends that the Resource Description Framework (RDF) schema is used in conjunction with the general metadata properties defined in the Dublin Core Metadata Initiative.

Note: A <metadata> tag exists for grammars.

The RDF is a declarative language and provides a standard way to use XML to represent metadata in the form of statements about properties and relationships of items on the Web. Content creators should refer to W3C metadata Recommendations (RDF-XMLSYNTAX) and (RDF-SCHEMA) when deciding which metadata RDF schema to use in their documents. Content creators should also refer to the Dublin Core Metadata Initiative (DC), which is a set of generally applicable core metadata properties (such as, Title, Creator, Subject, Description, and Rights).

Document properties declared with the <metadata> tag can use any metadata schema.

Syntax

<metadata>
  "Your RDF schema"
</metadata>

Attributes

None.

Parent

Audio, Enumerate, Foreach, Prompt, Speak, and VXML

Child

CDATA, and Text (#PCDATA)

Example

This example shows how metadata can be included in an SSML file using the Dublin Core version 1.0 RDF schema (DC) describing general document information such as Title, Description, Date, and so on:

<prompt>
  <metadata>
    <rdf:RDF
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
      xmlns:rdfs="http://www.w3.org/TR/1999/PR-rdf-schema-19990303#"
      xmlns:dc="http://purl.org/metadata/dublin_core#">
      <!-- Metadata about the synthesis document -->
      <rdf:Description about="http://www.example.com/meta.ssml"
        dc:Title="Hamlet-like Soliloquy"
        dc:Description="Aldine's Soliloquy in the style of Hamlet"
        dc:Publisher="W3C"
        dc:Language="en-US"
        dc:Date="2002-11-29"
        dc:Rights="Copyright 2002 Aldine Turnbet"
        dc:Format="application/ssml+xml">
        <dc:Creator>
          <rdf:Seq ID="CreatorsAlphabeticalBySurname">
            <rdf:li>William Shakespeare</rdf:li>
            <rdf:li>Aldine Turnbet</rdf:li>
          </rdf:Seq>
        </dc:Creator>
      </rdf:Description>
    </rdf:RDF>
  </metadata>
  Hello, world!
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <metadata> tag.

The <metadata> tag can have arbitrary content, although none of the arbitrary content will be rendered by the speech-synthesis processor.


P

Standard VoiceXML > SSML Tags

<p>

The SSML <p> tag represents a paragraph.

Syntax

<p
  gvp:ssft-dtype="email"
  xml:lang="A predefined language value"
  child tags
</p>

Attributes

Attribute | Description
gvp:ssft-dtype | (Optional) This attribute supports TTS email processing with RealSpeak 4.5.
xml:lang | (Optional) This attribute defines the language and locale for the paragraph.

Parent

Audio, Enumerate, Foreach, Prompt, Prosody, Speak, and Voice

Child

Audio, Break, Emphasis, Mark, Phoneme, Prosody, Say-as, S, Sub, Text (#PCDATA), Value, and Voice

Example

<vxml xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension" ...>
  <form>
    <block>
      <prompt>
        <p gvp:ssft-dtype="email">
          From: Alice
          Sent: May-10-10 2:39 PM
          To: Bob
          Subject: email subject
          Email content
        </p>
      </prompt>
    </block>
  </form>
</vxml>

The gvp namespace will be removed from the ssft-dtype attribute when transmitting the SSML to the RealSpeak TTS. For example, this is the SSML to be transmitted to the RealSpeak TTS.

<?xml version="1.0"?>
<speak ...>
  <p ssft-dtype="email">
    From: Alice
    Sent: May-10-10 2:39 PM
    To: Bob
    Subject: email subject
    Email content
  </p>
</speak>

Known Issues and Recommendations

The <paragraph> tag is not supported.

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <p> tag.


Phoneme

Standard VoiceXML > SSML Tags

<phoneme>

The SSML <phoneme> tag provides a phonemic and/or phonetic pronunciation for the contained text (words or very short phrases). The tag:

  • May only contain text.

  • May be empty. However, Genesys recommends that the tag contain human-readable text that can be used for non-spoken rendering of the document. For example, the content may be displayed visually for users with hearing impairments.

Syntax

<phoneme
   alphabet="ipa"|"Your vendor-defined string"
   ph="Your phonetics type">
  text
</phoneme>

Attributes

Attribute | Description
alphabet | (Optional) This attribute specifies the alphabet to use. An error will result if a value for alphabet is specified that is not known or cannot be applied by the speech-synthesis processor. The default behavior when the alphabet attribute is left unspecified is processor-specific.
ph | This attribute specifies the phonetic string. Valid values are strings of the values. For details, see The Handbook of the International Phonetic Association:Appendix 2, The International Phonetic Alphabet, and The International Phonetic Alphabet Unicode for IPA-to-Unicode mappings.

Parent

Audio, Emphasis, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

Text (#PCDATA)

Example

<prompt>
   <!-- If your speech-synthesis processor supports the 'ipa' alphabet,-->
   <!-- then this reads out "tomato" with a UK accent -->
   <phoneme alphabet="ipa" ph="t&#x259;mei&#x325;&#x27E;ou&#x325;">
      tomato
   </phoneme>
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <phoneme> tag.

The speech-synthesis processor should support a value for an alphabet of ipa (International Phonetic Alphabet), corresponding to Unicode representations of the phonetic characters developed by the International Phonetic Association (PA). In addition to an exhaustive set of vowel and consonant symbols, this character set supports a syllable delimiter, numerous diacritics, stress symbols, lexical tone symbols, intonational markers, and more. For this alphabet, valid ph values are strings of the values as specified in the Handbook of the International Phonetic Association (Appendix 2). Additionally, informative tables containing the IPA-to-Unicode mappings can be found in The International Phonetic Alphabet and The International Phonetic Alphabet Unicode. Not all of the IPA characters are available in Unicode.

For processors supporting this alphabet:

  • The processor must syntactically accept all legal ph values.

  • The processor should produce output when given Unicode IPA codes that can reasonably be considered to belong to the current language.


Prosody

Standard VoiceXML > SSML Tags

<prosody>

The SSML <prosody> tag permits control of the pitch, speaking rate, and volume of the speech output.

Syntax

<prosody
   contour="<(X1%,<Your first pitch value>)...(Xn%,<Your nth pitch value>)"
   duration="Your time interval"
   pitch="high"|"medium"|"low"|"default"|"Your pitch value"|"Your relative change"
   range="high"|"medium"|"low"|"default"|"Your pitch range"|"Your relative change"
   rate="fast"|"medium"|"slow"|"default"|"Your rate value"|"Your relative change"
   volume="silent"|"soft"|"medium"|"loud"|"default"|"Your volume value"|"Your relative change">
   child tags
</prosody>

Attributes

Each attribute is optional; however, at least one is required if the <prosody> tag is used. All units ("Hz", "st") are case-sensitive. Pitch levels and pitch ranges may vary by language, as may the meanings of the labeled values for pitch targets and ranges.

Attribute

Description

contour

(Optional) Specifies the pitch contour for the text. The pitch contour is defined as a set of white space-separated targets at specified time positions in the speech output. The algorithm for interpolating between the targets is speech synthesis processor-specific.

In each value-pair (for example, X1%,pitch1):

  • The first value (X1%) is the time position. It specifies the percentage of the period of the contained text. Time position values outside 0% to 100% are ignored. If a pitch value is not defined for 0% or 100% then the nearest pitch target is copied.

  • The second value (pitch1) is the value of the pitch attribute. it is a number followed by "Hz", a relative change, or a label value. All relative values for the pitch are relative to the pitch value just before the contained text.

duration

(Optional) Specifies the duration in seconds or milliseconds for the time to read the text (for example, "250ms", "3s").

pitch

(Optional) Specifies the baseline pitch for the contained text. Although the exact meaning of baseline pitch will vary across speech-synthesis processors, increasing or decreasing this value will typically increase or decrease the approximate pitch of the output. The valid values are:

  • A number followed by "Hz" ("+10Hz", "-5.5Hz").

  • A relative change ("+0.5st", "+5st", "-2st").
    St     is a semitone, or half of a tone, on the standard diatonic scale.

  • A predefined label ("x-low", "low", "medium", "high", "x-high", or "default") where "x-low" through "x-high" represent a sequence of monotonically non-decreasing pitch levels.

range

(Optional) Specifies the pitch range for the contained text. Pitch range will vary across speech-synthesis processors. Increasing or decreasing this value will typically increase or decrease the dynamic range of the output pitch. Valid values are:

  • A number followed by "Hz" ("+10Hz", "-5.5Hz").

  • A relative change ("+0.5st", "+5st", "-2st").
    St     is a semitone, or half of a tone, on the standard diatonic scale.

  • A predefined label ("x-low", "low", "medium", "high", "x-high", or "default") where "x-low" through "x-high" represent a sequence of monotonically non-decreasing pitch levels.

rate

(Optional) Specifies a change in the speaking rate for the contained text. The valid values are:

  • A relative change (1, 2, 0.5). When a number is used to specify a relative change it acts as a multiplier of the default rate. For example, a value of 1 means no change in speaking rate, a value of 2 means a speaking rate twice the default rate, and a value of 0.5 means a speaking rate of half the default rate. The default rate for a voice depends on the language and dialect and on the personality of the voice. The default rate for a voice should be such that it is experienced as a normal speaking rate for the voice when reading text aloud. Since voices are speech synthesis processor-specific, the default rate will be as well.

  • A predefined label ("x-slow", "slow", "medium", "fast", "x-fast", or "default") where labels "x-slow" through "x-fast" represent a sequence of monotonically non-decreasing speaking rates.

volume

(Optional) Specifies the volume for the contained text in the range "0.0" to "100.0" where "100.0" is loud and "0" is silent. The volume scale is linear amplitude. The valid values are:

  • A number ("0" to "100.0"). The default is "100.0".

  • A relative change ("+10", "-5.5").

  • A predefined label ("silent", "x-soft", "soft", "medium", "loud", "x-loud", or "default"). Labels "silent" through "x-loud" represent a sequence of monotonically non-decreasing volume levels.

Parent

Audio, Emphasis, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

Audio, Break, Emphasis, Mark, P, Phoneme, Prosody, Say-as, S, Sub, Text (#PCDATA), Value, and Voice

Example

<prompt>
The price of XYZ is
<prosody rate="-10%">
$45
</prosody>
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <prosody> tag.


Say-as

Standard VoiceXML > SSML Tags

<say-as>

The SSML <say-as> tag allows you to:

  • Indicate information about the type of text contained within the tag.

  • Specify the level of detail for rendering the contained text.

Note: Defining a comprehensive set of text format types is difficult because of the variety of languages that must be considered and because of the innate flexibility of written languages. SSML only specifies the <say-as> tag, its attributes, and their purpose. It does not enumerate the possible values for the attributes.

Syntax

<say-as
   detail="Your valid detail value"
   format="Your valid format value"
   interpret-as="date"|"time"|"telephone"|"characters"|"cardinal"|"ordinal">
  text
</say-as>

Attributes

Attribute

Description

detail

(Optional) Indicates the level of detail to be read aloud or rendered. This attribute can be used for all interpret-as types. See your speech-synthesis processor documentation for supported values.

format

(Optional) This option further specifies the precise formatting of the contained text for content types that may have ambiguous formats. When the value for the format attribute is unknown or unsupported by a speech-synthesis processor, it must render the contained text as if no format value were specified, and should render it using the interpret-as value that is specified. The valid values are:

  • Number

  • String

  • Text

  • Time

  • Ordinal

  • Currency

  • Bookmark

  • DTMF

  • Date(mm/dd/yyyy)

interpret-as

Indicates the content type of the contained text construct. Specifying the content type helps the speech-synthesis processor to distinguish and interpret text constructs that may be rendered in different ways depending on what type of information is intended. When the value for the interpret-as attribute is unknown or unsupported by a processor, it must render the contained text as if no interpret-as value were specified. The valid values include:

  • date—This value indicates that the contained text is a Gregorian calendar date. The <say-as> tag then only gives a hint that the content is a Gregorian calendar date.

  • time—This value indicates that the contained text is a time. The intention is to cover most formats for time that might occur in a written document. This format covers wall clock time only, not durations or time ranges.

  • telephone—This value indicates that the contained text is a telephone number. The intention is to give a hint to the speech-synthesis processor about how to interpret the contained text in order to speak it properly.

  • character—This value indicates that the contained text should be spoken as a series of alpha-numeric characters. (It is thus a generalization of the concept of digit string.) The text may include punctuation. The pronunciation of the individual characters is not indicated. For example, the digit "0" may be pronounced in English "zero" or "oh" or "naught" at the discretion of the speech-synthesis processor.

  • cardinal—This value indicates that the enclosed text is an integral or decimal number and should be spoken as a cardinal number (as opposed to an ordinal number or digit string). An optional leading dash -) or plus sign (+) is permitted to indicate negative (positive) numbers. The exact rendering of the cardinal number is still determined by the speech-synthesis processor.

  • ordinal—This value indicates that the enclosed text is an integral number and should be spoken as an ordinal number (as opposed to a cardinal number or digit string). This value is a hint to the processor on how to interpret the contents. If the sentence containing the <say-as> tag provides sufficient context for appropriate number and gender concordance, it is expected that the speech-synthesis processor will produce the correct ordinal. If the context is not sufficient, the processor will produce the best representation of the ordinal that it can.

    The format and detail attributes are not used for ordinal content. Because no standard values for these attributes are defined, the speech-synthesis processor is expected to ignore any values in these attributes that it does not support.

    For example,
    <say-as interpret-as="ordinal">123</say-as>
    In English, this example will likely be spoken as "One hundred twenty third."

When the content of the <say-as> tag contains additional text next to the content that is in the format and interpret-as type, this additional text must be rendered. The processor may make the rendering of the additional text dependent on the interpret-as attribute of the tag in which it appears.

When the content of the <say-as> tag contains no content in the indicated interpret-as type or format, the processor must render the content either as if the format attribute were not present, or as if the interpret-as attribute were not present, or as if neither the format nor interpret-as attributes were present. The processor should also notify the environment of the mismatch.

Parent

Audio, Emphasis, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

Text (#PCDATA), and Value

Example

<speak>
   <p>
      This is a W3C-defined date:
      <say-as interpret-as="date" format="dm">
         4/6
      </say-as>
      . This is a VoiceXML date:
      <say-as interpret-as="vxml:date">
         ????0604
      </say-as>
      . This is an example dot com date:
      <say-as interpret-as="example:date" format="weekandday">
         23/5
      </say-as>
      .
   </p>
</speak>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <say-as> tag.


S

Standard VoiceXML > SSML Tags

<s>

The SSML <s> tag identifies the enclosed text as a sentence. The use of the <s> tag is optional. Where text occurs without an enclosing <s> tag the speech-synthesis processor should attempt to determine the structure using language-specific knowledge of the format of plain text.

Syntax

<s xml:lang="Your language value">
  child tags
</s>

Attributes

Attribute | Description
xml:lang | (Optional) Defines the language and locale for this sentence.

Parent

Audio, Enumerate, Foreach, P, Prompt, Prosody, Speak, and Voice

Child

Audio, Break, Emphasis, Mark, Phoneme, Prosody, Say-as, Sub, Text (#PCDATA), Value, and Voice

Example

<prompt>
<p>
<s>
This is the first sentence of the first paragraph.
</s>
<s>
This is the second sentence of the first paragraph.
</s>
</p>
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <s> tag.


Speak

Standard VoiceXML > SSML Tags

<speak>

The SSML <speak> tag is the root tag. It provides the root tag for SSML but no additional functionality. If you are defining SSML content within <audio>, <choice>, <enumerate>, <prompt>, or <foreach> within <prompt>, do not include the <speak> tag or the XML header. For details, see the Known Issues and Recommendations section.

Syntax

<speak
version="1.0"
xml:base="Your base URI"
xml:lang="Your language value"
>
child tags
</speak>

Attributes

Attribute | Description
xml:base | (Optional) This attribute specifies the Base URI of the root document.
xml:lang | This attribute specifies the language of the root document.
version | This attribute indicates the version of the specification to be used for the document and must have the value "1.0".

Parent

None.

Child

Audio, Break, Emphasis, Lexicon, Mark, Meta, Metadata, P, Phoneme, Prosody, Say-as, S, Sub, Text (#PCDATA), Value, and Voice

Example

<?xml version="1.0"?>
<speak version="1.0"
xmlns="http://www.w3.org/2001/10/synthesis"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/10/synthesis
http://www.w3.org/TR/speech-synthesis/synthesis.xsd"
xml:lang="en-US"
>
The body ...
</speak>

Known Issues and Recommendations

The GVP Next Generation Interpreter (NGI) wraps the <speak> tag around text that will be synthesized into speech and adds the XML header. Therefore, you should never add a <speak> tag or the XML header. If you add a <speak> tag or an XML header, embedded <speak> tags will result, and all text will be ignored.


Sub

Standard VoiceXML > SSML Tags

<sub>

The SSML <sub> tag specifies that the text in the alias attribute value replaces the contained text for pronunciation. This allows a document to contain both a spoken and written form.

Syntax

<sub alias="Your replacement text">
   text
</sub>

Attributes

Attribute | Description
alias | This attribute specifies the string to be spoken instead of the enclosed string.

Parent

Audio, Emphasis, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

Text (#PCDATA)

Example

<prompt>
<sub alias="Genesys Voice Platform">
GVP
</sub>
</prompt>

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <sub> tag.


Voice

Standard VoiceXML > SSML Tags

<voice>

The SSML <voice> tag specifies voice characteristics for the spoken text.

Syntax

<voice
   age="Your age value"
   gender="male"|"female"|"neutral"
   name="Your name value"
   variant="Your variant value"
   xml:lang="A predefined language value">
   child tags
</voice>

Attributes

Each attribute is optional; however, at least one must be specified.

Attribute

Description

age

(Optional) This attribute indicates the preferred age in years (since birth) of the voice to speak the contained text.

The valid values are of type xsd:nonNegativeInteger. For details, see the W3C, 2 May 2001:XML Schema Part 2: Datatypes specification.

gender

(Optional) This attribute indicates the preferred gender of the voice to speak the contained text. The valid values include:

  • male

  • female

  • neutral

name

(Optional) This attribute indicates a speech-synthesis-processor-specific voice name to speak the contained text.
The valid values may be a space-separated list of names ordered from top preference down.

A name must not contain any white space.

variant

(Optional) This attribute indicates a preferred variant of the other voice characteristics to speak the contained text. For example, the second male child voice).

The valid values of variant are of type xsd:positiveInteger. For details, see the W3C, 2 May 2001:XML Schema Part 2: Datatypes specification.

xml:lang

(Optional) This attribute defines the language and locale for this paragraph.

Parent

Audio, Emphasis, Enumerate, Foreach, P, Prompt, Prosody, S, Speak, and Voice

Child

Audio, Break, Emphasis, Mark, P, Phoneme, Prosody, Say-as, S, Sub, Text (#PCDATA), Value, and Voice

Example

<?xml version="1.0"?>
<speak version="1.0"
   xmlns="http://www.w3.org/2001/10/synthesis"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.w3.org/2001/10/synthesis
                http://www.w3.org/TR/speech-synthesis/synthesis.xsd"
   xml:lang="en-US">
   <voice gender="female">
      Mary had a little lamb,
   </voice>
   <!-- now request a different female child's voice -->
   <voice gender="female" variant="2">
      Its fleece was white as snow.
   </voice>
   <!-- processor-specific voice selection -->
   <voice name="Mike">
      I want to be like Mike.
   </voice>
</speak>

When there is not a voice available that exactly matches the attributes specified, or there are multiple voices that match the criteria, the following voice selection algorithm must be used. There are cases in the algorithm that are ambiguous; in such cases voice selection may be speech-synthesis processor specific. Approximately speaking, the xml:lang attribute has the highest priority and all other attributes are equal in priority but below xml:lang . The complete algorithm is:

  1. If a voice is available for a requested xml:lang, a speech-synthesis processor must use it.

  2. If there are multiple such voices available, the speech-synthesis processor should use the voice that best matches the specified values for name, variant, gender and age.

  3. If there is no voice available for the requested xml:lang, the speech-synthesis processor should select a voice that is closest to the requested language (for example, a variant or dialect of the same language).

  4. If there are multiple such voices available, the processor should use a voice that best matches the specified values for name, variant, gender and age.

It is an error if the speech-synthesis processor decides it does not have a voice that sufficiently matches the above criteria.

Known Issues and Recommendations

Refer to your speech-synthesis processor documentation for details on the limitations and restrictions associated with the <voice> tag.

Relative changes in prosodic parameters should be carried across voice changes. However, different voices have different natural defaults for pitch, speaking rate, and so on, because they represent different personalities, so absolute values of the prosodic parameters may vary across changes in the voice.

The quality of the output audio or voice may suffer if a change in voice is requested within a sentence.

If you are using a speech-synthesis processor that does not support the <voice> tag, use the VoiceXML, <prompt> tag, ttsengine attribute to:

  • Specify which speech-synthesis processor you want to use.

  • Switch between speech-synthesis processor engines.

For example,

<prompt>
   <value expr="greeting"/>
      This will use the default voice.
</prompt>
<prompt ttsengine="SPEECHIFY_TOM">
   This will use a male voice, if a male voice
   is configured as Speechify Tom.
</prompt>
<prompt ttsengine="SPEECHIFY_MARA">
   This will use a female voice, if a female voice
   is configured as Speechify Mara.
</prompt>

You can switch between any of the voices you have installed, using the ttsengine names you have configured for each voice.


VoiceXML (VXML) Tags

Standard VoiceXML > VoiceXML Tags

Overview

The VoiceXML 2.1 tags supported include:

A - C

<assign>

<audio>

<block>

<catch>

<choice>

<clear>

D - E

* <data>

*<disconnect>

<else>

<elseif>

<enumerate>

<error>

<exit>

F - J

*<field>

<filled>

*<foreach>

<form>

<goto>

*<grammar>

<help>

<if>

<initial>

K - O

<link>

<log>

* <mark>

<menu>

<meta>

<noinput>

<nomatch>

<object>

<option>

P - R

<param>

<prompt>

<property>

<receive>

*<record>

<reprompt>

<return>

S - Z

*<script>

<send>

<subdialog>

<submit>

<throw>

*<transfer>

<value>

<var>

<vxml>

* New or updated for VoiceXML 2.1.


Assign

Standard VoiceXML > VoiceXML Tags

<assign>

This tag assigns a value to a variable. If you attempt to <assign> a value to a variable that has not been previously declared (with <var> or var in a <script>), it will result in an error.semantic event being thrown.

Syntax

<assign
   expr="Your ECMAScript expression"
   name="Your name value"
/>

Attributes

Attribute | Description
expr | This attribute specifies an ECMAScript expression to be evaluated and used as the value assigned to the variable.
name | This attribute specifies the name of the variable that the value will be assigned to. This attribute may take on a valid ECMAScript left-hand-side expression. If the attribute is a variable name without a scope or object qualification, the variable must have been previously declared. The variable is resolved against the closest enclosing scope of the currently active element. If any of the above actions fails, an error.semantic event is generated at the time the tag is visited. This attribute is required; if it is not provided, a parse error is generated.

An error event may be thrown if the application attempts to <assign> a value to a read-only variable (for example, to a session variable).

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <var name="var1" expr="'first'"/>
  <form>
    <block>
      The initial value is <value expr="var1"/>.
      <assign name="var1" expr="'second'"/>
      The new value is <value expr="var1"/>.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <assign> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Audio

Standard VoiceXML > VoiceXML Tags

<audio>

This tag supports the insertion of audio and video files. If the file cannot be played, the content of the <audio> tag is played. If the file cannot be played and there is no content, no audio is played and no error is thrown.

Syntax

<audio
   expr="<Your ECMAScript expression>"
   fetchhint="safe"]
   fetchtimeout="<Your time value>"
   maxage="<Your maxage value>"
   maxstale="<Your maxstale value>"
   src="<Your URI>"
   gvp:lengthexpr="<Your ECMAScript expression>"
   gvp:offsetexpr="<Your ECMAScript expression>"
   gvp:videotextexpr="<Your ECMAScript expression>"
>
  child tags
</audio>

Attributes

This section provides the tag-attribute descriptions. Either src or expr must be specified. Otherwise, the document containing the tag will generate a parsing error.

Attribute

Description

expr

This attribute specifies an ECMAScript expression that references a previously recorded audio, or evaluates to the URI of an audio resource to fetch. When this attribute is found, the value of the expr is evaluated once. The behavior depends on the result:

  • If the expr evaluates to ECMAScript undefined, the element, including its alternate content, is ignored.

  • If the expr evaluates to an audio reference previously recorded (with the <record/> tag or the recording shadow variable), the reference to the recorded audio must be sent back to the platform.

  • If the expr evaluates to null, the <audio> tag will be skipped, including its alternate content.

  • Otherwise, the value of the expr is converted to an ECMAScript string and treated in the same manner as the src attribute described above.

Either src or expr must be specified. Otherwise, the document containing the tag will generate a parsing error.

Unless the <audio> tag expr attribute evaluates to ECMAScript undefined, when the <audio> tag is executed, the tags enclosed within the <audio> tag must be attached to the prompt fragment of the <audio> tag as alternate content to be sent to the platform, to be played if the audio reference itself cannot be played.

fetchhint

(Optional) This attribute defines when the audio file should be fetched. If this attribute is not specified, the value derived from the innermost relevant fetchhint attribute is used. The valid value is:

  • safe—the audio file is downloaded when it is needed.

This value overrides the value of the audiofetchhint property.

Support for this feature is dependent on the platform.

fetchtimeout

(Optional) This attribute specifies the interval to wait for the content to be returned before throwing an error.badfetch event. The value is a time designation (for example, "3s", "850ms", "0.7s", ".5s" and "+1.5s"). If not specified, a value derived from the innermost fetchtimeout property is used.

This value overrides the value of the fetchtimeout property.

Support for this feature is dependent on the platform.

maxage

(Optional) This attribute indicates that this document will use a cached copy of this audio file if the age of the cached copy is less than or equal to the number of seconds specified.

This value overrides the value of the audiomaxage property.

Support for this feature is dependent on the platform.

maxstale

(Optional)This attribute indicates that this document will use a cached copy of this audio file that has exceeded its expiration time by as much as the number of seconds specified.

This value overrides the value of the audiomaxstale property.

Support for this feature is dependent on the platform.

src

This attribute provides the Universal Resource Indicator (URI) of the audio prompt. When it is found, a prompt fragment of type AudioFile is queued to the prompt queue. The value of the src attribute is resolved against the base-URL in effect for the <audio> tag, and the full URL is used for the prompt fragment. The URI can reference:

  • The URL of an external audio file, where the URL can be http, https, file, or rtsp. For example, rtsp://ourserver/audio/hello.vox.

  • The builtin_path option and a local audio file.
    The builtin_path option is configured in the Media Control Platform (MCP) VXMLi section (see the Genesys Voice Platform 8.1 Configuration Options Reference).

Either the src or expr attribute must be specified, otherwise, the document containing the tag will generate a parsing error.

gvp:lengthexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the time length (specified in milliseconds) of the audio data to be played from the file.

The default value is the length if the referenced audio.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Support for this feature is dependent on the platform.

gvp:offsetexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the time offset (specified in milliseconds) to begin playing the audio file.

The default value is 0.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Support for this feature is dependent on the platform.

gvp.streaming

(Optional) This attribute specifies the value of the <audio> attribute streaming.

The default value is based on the com.genesyslab.streamingaudio property, which defaults to false.

If true, <audio> streaming is enabled.

If false, <audio> streaming is disabled.

gvp:videotextexpr

(Optional) This attribute specifies an ECMAScript expression that must be evaluated to an array of an object. If the expression is evaluated to a non-array result, the error.semantic event will be thrown.

In the array provided in the videotextexpr attribute, each element must be an object, and each object supports the following properties:

  • text—(mandatory) The text content of a text overlay of video. This property accepts a string. If this property is missing, the error.semantic event will be thrown. GVP supports having newline and tab characters in the ASCII text. The newline character will move the rest of the text to the beginning of the next line. The tab character will advance the next character to the next tab stop, with a tab size/length of 4 (times the font size/width).

  • fontname—(optional) The name of the font to be used in a text overlay of video. This property accepts a string, and defaults to the value of the com.genesyslab.videotext.fontname property. The font name corresponds to the .ttf or postscript fonts installed in the directory specified in the [mpc] font_paths_win (Windows) and [mpc] font_paths_linux (Linux) MCP configuration options. If this attribute or the corresponding property is not specified, a default system font will be chosen.

  • fontstyle—(optional) The font style used in a text overlay of video; for example, regular, bold, or italic. This property accepts a string, and defaults to the value of the com.genesyslab.videotext.fontstyle property.

  • fontcolor—(optional) The font color of a text overlay specified in HTML hexadecimal triplet RGB color code (for example, #FFFFFF represents white). This property accepts a string, and defaults to the value of the com.genesyslab.videotext.fontcolor property.

  • bgcolor—(optional) The font's background color of a text overlay specified in HTML hexadecimal triplet RGB color code (for example, #FFFFFF represents white). This property accepts a string, and defaults to the value of the com.genesyslab.videotext.bgcolor property.

  • xoffset—(optional) The text overlay’s display horizontal/X offset from the left margin in a scale of 0-1000. This value will be scaled to the video resolution width at the time of the use. This property accepts an integer, and defaults to the value of the com.genesyslab.videotext.xoffset property.

  • yoffset—(optional) The text overlay’s display vertical/Y offset from the top margin in a scale of 0-1000. This value will be scaled to the video resolution height at the time of use. This property accepts an integer, and defaults to the value of the com.genesyslab.videotext.yoffset property.

  • fontsize—(optional) The font size of a text overlay in a scale of 0-1000. The font size is scaled to the video frame height. This property accepts an integer, and defaults to the value of the com.genesyslab.videotext.fontsize property.

  • fontwidth—(optional) The font width of a text overlay in a scale of 0-1000. The font size is scaled to the video frame width. If font width is not specified in either this attribute or the corresponding property, it will be the same as the size/height for this video. This property accepts an integer, and defaults to the value of the com.genesyslab.videotext.fontwidth property.

If an array element is not an object, or if a mandatory attribute in one of the array elements is not present or is given a value of an unexpected type, then an error.semantic event will be thrown.

If an optional attribute in one of the array elements is given a value of an unexpected type, the default value will be used.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Audio, Catch, Choice, Enumerate, Error, Field, Filled, Foreach, Help, If, Initial, Menu, Noinput, Nomatch, Object, Prompt, Record, Subdialog, and Transfer

Child

Audio, Enumerate, and Value

GVP Extensions

  • Support for accessing built-in (local) audio resources

  • lengthexpr attribute

  • offsetexpr attribute

  • videotextexpr attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      Here is the recorded thank you message:
      <audio src="thankyou.vox">
         If you can hear this, thankyou.vox was not found.
      </audio>
      <audio src="builtin:default_audio/the_requested_page_cannot_be_found.vox">
        If you can hear this, the local builtin:default_audio
        file was not found.
      </audio>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None


Block

Standard VoiceXML > VoiceXML Tags

<block>

This tag specifies executable content to be executed in document order.

Syntax

<block
   cond="Your ECMAScript expression"
   expr="Your ECMAScript expression"
   name="Your name string"
   gvp:private="true|false"
>
  child tags
</block>

Attributes

Attribute

Description

cond

(Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This block will be visited only if the expression evaluates to true.

The default value is true.

expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the initial value of the block. This block will be visited only if the expression evaluates to undefined.

The default value is undefined.

name

(Optional) This attribute specifies the name of the block. This variable can be referenced anywhere within the block's form. The default variable-declaration (for example, a private variable versus a public variable) is an inaccessible internal variable.

gvp:private

(Optional) This attribute enables data masking for logged metrics (interaction-level messages that described call flow). This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:

  • True—If gvp:private equals true, data masking is enabled. The data that is masked includes:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • False—If gvp:private equals false, data masking is not enabled (no data is masked).

The default value is false. If an invalid value is used, the page will be rejected.

Once this tag is used, all masked data is masked until the functionality is turned off.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

This attribute takes precedence over com.genesyslab.private.

Parent

Form

Child

Assign, Clear, Data, Disconnect, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

GVP Extensions

  • private attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form>
   <block name="first" expr=”somevalue”>
      This is first block.
    </block>
    <block name="second" cond=”false”>
       This is second block.
    </block>
    <block name="third" cond=”true”>
      This is third block.
      <goto nextitem="fourth"/>
    </block>
    <block name="fourth">
       This is fourth block.
    </block>
</form>
</vxml>

This code will be executed as follows:

  • The first and second <block> will not execute because, expr is not undefined and cond is not true (respectively).

  • The third <block> will execute because, cond equals true, and by default if expr is not included, expr equals undefined.

  • The fourth <block> will execute because, by default, cond equals true, and by default if expr is not included, expr equals undefined.

Known Issues and Recommendations

Using the private attribute does not prevent sensitive data from being logged. Therefore, if the VoiceXML application should not log some data, Genesys recommends that the VoiceXML application use the post method not the get method to submit the data to the web server.


Catch

Standard VoiceXML > VoiceXML Tags

<catch>

This tag catches events thrown by the VoiceXML application or the Genesys Voice Platform (GVP). The <catch> tag associates a catch with a document, dialog (for example, form or menu), or form item (except for blocks). It contains executable content.

The <catch> tag catches an event where:

  • The name matches exactly with the event attribute.

  • The event attribute is a prefix match. The event attribute is a prefix match if event attribute is a token prefix of the thrown event, where the dot is the token separator. For example, <catch event="telephone.disconnect"> is a prefix match for the event telephone.disconnect.transfer.

Syntax

<catch
   cond="Your ECMAScript expression"
   count="Your count value"
   event="event_1 event_2 event_n">
  child tags
</catch>

Attributes

Attribute

Description

cond

(Optional) This attribute specifies an ECMAScript expression that will be evaluated as a boolean condition. This <catch> tag only catches the event if the expression evaluates to true.

The default is true.

count

(Optional) This attribute allows you to handle different occurrences of the same event differently. Each form, menu, and form item maintains a counter for each event that occurs while it is being visited. These counters reset each time the menu or form item's form is re-entered. When more than one <catch> tag catches the same event, the tag in the closest scope with the highest count that is less than or equal to the current counter is selected.

The default value is 1.

event

(Optional) This attribute is a space-separated list of events indicating that this tag catches all of the events named in the list.

  • If the attribute is unspecified, all events match the <catch> tag name.

  • If the attribute is a single dot (.), all events match the <catch> tag name.

  • If the attribute is an empty string, the document containing the <catch> tag must generate a parse error.

The default value is all events.

Anonymous Variables

  • _event—Contains the name of the event that was thrown.

  • _message—Contains the message string from the corresponding <throw>, <choice>, <link>, or <return> tag, or a platform defined value for events thrown by the platform. If no message is specified, the value of this variable is ECMAScript undefined.

  • _url—Contains the url of the page where the error occurred.

  • _element—Contains the name of the element that generated the event.

  • _line—Contains the line number of the start of the element that generated the event.

Parent

Field, Form, Initial, Menu, Object, Record, Subdialog, Transfer, and Vxml

Child

Assign, Audio, Clear, Data, Disconnect, Enumerate, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

GVP Extensions

  • _url variable

  • _element variable

  • _line variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="digits">
      <prompt> Please say some digits. </prompt>
      <catch event="noinput">
        I didn't hear you.
        <reprompt/>
      </catch>
      <filled>
        Thanks. You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

None.


Choice

Standard VoiceXML > VoiceXML Tags

<choice>

This tag defines a menu item. The <choice> tag serves several purposes:

  • Specifies a speech grammar fragment and/or a Dual Tone Multi-Frequency (DTMF) grammar fragment to determine when that choice has been selected.

  • Specifies what to do when that choice has been selected.

  • Uses the contents to form the <enumerate> prompt string.

Syntax

<choice
   accept="exact"|"approximate"
   dtmf="<Your DTMF sequence>"
   event="Your event"|eventexpr="Your ECMAScript"|expr="Your ECMAScript"|next="Your URI"
   fetchaudio="Your URI"
   fetchtimeout="Your time interval"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   message="Your message string"|messageexpr="Your ECMAScript Expression"
   gvp:fetchaudiodelay="Your time interval"
   gvp:fetchaudiominimum="Your time interval">
  child tags
</choice>

Attributes

The next, expr, event, or eventexpr attributes are optional; however, one of them is required.

Attribute

Description

accept

(Optional) This attribute overrides the setting for the accept attribute in the <menu> tag. The valid values are:

  • Exact—The text contained in the <choice> tag defines the exact phrase to be recognized.

  • Approximate—The text contained in the <choice> tag defines an approximate recognition phrase. A subset of the words in the phrase can be matched. For example, "hello world" can be matched with "hello world", "hello", or "world".

If an invalid value is specified, an error.semantic event is thrown when the menu is initialized.

The default value is exact.

dtmf

(Optional) This attribute specifies the DTMF sequence required to select the item.

event

(Optional) This attribute specifies the name of the event to be thrown when this choice is selected.

As noted, this attribute is optional; however, one of next, expr, event, or eventexpr is required. The next and expr have precedence over this attribute.

eventexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the name of the event to be thrown when this choice is selected.

As noted, this attribute is optional; however, one of next, expr, event, or eventexpr is required. The next and expr have precedence over this attribute.

expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated and used as the URI of the dialog (for example, form or menu) or document to transition to when this choice is selected.

As noted, this attribute is optional. However, one of next, expr, event, or eventexpr is required. The next attribute has precedence over this attribute.

An error.badfetch event is thrown if next or expr refer to a non-existent dialog (form or menu), either within the same page, or within a different, existent, page.

fetchaudio

(Optional) This attribute specifies the URI of audio to play while waiting for the document to be fetched.

This attribute overrides the value of the fetchaudio property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

This attribute is ignored if either the eventexpr or event attribute is specified.

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the next document to be fetched before throwing an error.badfetch event.

This value overrides the value of the fetchtimeout property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

This attribute is ignored if either the eventexpr or event attribute is specified.

maxage

(Optional) This attribute indicates that this document will use a cached copy of the next document if the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This value overrides the value of the documentmaxage property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

This attribute is ignored if either the eventexpr or event attribute is specified.

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the next document that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This value overrides the value of the documentmaxstale property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

This attribute is ignored if either the eventexpr or event attribute is specified.

message

(Optional) This attribute specifies a message string that provides additional context about the event being thrown. The message will be available as a variable within the scope of the <catch> tag.

This attribute can only be used if the event or eventexpr attribute is specified. Also, only one of the message or messageexpr can be specified.

messageexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated and used as a message string, as documented in the preceding message attribute.

This attribute can only be used if the event or eventexpr attribute is specified. Also, only one of the attributes message or messageexpr can be specified.

next

(Optional) This attribute specifies the URI of the dialog (for example, the form or menu) or document to transition to when this choice is selected.

As noted, this attribute is optional; however, one of next, expr, event, or eventexpr is required.

An error.badfetch event is thrown if next or expr refer to a non-existent dialog (form or menu), either within the same page, or within a different, existent, page.

gvp:fetchaudiodelay

(Optional) This attribute specifies the length of time to wait at the start of the fetch delay before playing fetchaudio.

This attribute overrides the value of the fetchaudiodelay property (for details search the Properties topic).

This attribute is ignored if either the eventexpr or event attribute is specified.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiominimum

(Optional) This attribute specifies the minimum length of time to play fetchaudio, once started, even if the document arrives in the meantime.

This value overrides the value of the fetchaudiominimum property (for details search the Properties topic).

This attribute is ignored if either the eventexpr or event attribute is specified.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Menu

Child

Grammar, and Text (#PCDATA)

GVP Extensions

  • fetchaudiodelay attribute

  • fetchaudiominimum attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <menu>
    <prompt> What do you want to drink, coffee or tea? </prompt>
    <choice next="#getcoffee"> coffee </choice>
    <choice next="#gettea"> tea </choice>
  </menu>
  <form id="getcoffee">
    <block>
      Ok, here's your coffee.
    </block>
  </form>
  <form id="gettea">
    <block>
      Ok, here's your tea.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Clear

Standard VoiceXML > VoiceXML Tags

<clear>

This tag resets one or more form items. It will:

  • Set the form item variable or variables to ECMAScript undefined.

  • Reinitialize the prompt counter and event counters for the form item or items.

With this tag it is possible to:

  • Transition back to a single form item variable, without reinitializing the item's prompt and event counters. To do this use <goto nextitem="Your item name"/>, rather than clearing the item.

  • Set one or more form item variable or variables back to ECMAScript undefined, without reinitializing the items' prompt and event counters. To do this use
    <assign name="Your item name" expr="undefined"/>     for each item, rather than clearing the item or items.

Syntax

<clear namelist="item1 item2 ..."/>

Attributes

Attribute | Description
namelist | (Optional) This attribute specifies the list of variables to be reset. This may include variable names other than form items, as long as variables are in the current scope. When not specified, all of the form items in the current form are cleared.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="boolean">
      <prompt> Please say yes or no. </prompt>
      <filled>
        You said <value expr="field1"/>.
        Let's try that again.
        <clear namelist="field1"/>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The <clear> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Data

Standard VoiceXML > VoiceXML Tags

<data>

This tag, new in VoiceXML 2.1, allows a VoiceXML application to fetch:

  • Arbitrary XML data from a document server without transitioning to a new VoiceXML document.

  • JavaScript Object Notation (JSON) data from a text-based file (see the JSON Data Example).

The XML data fetched by the <data> tag is bound to ECMAScript through the named variable that exposes a read-only subset of the W3C Document Object Model (DOM).

If this tag is used, the <vxml> version attribute must equal 2.1; otherwise, an error.badfetch will be thrown.

Syntax

<data
   enctype="Your MIME type"
   fetchaudio="Your URI"
   fetchhint="safe"
   fetchtimeout="Your time interval"
   maxage="Your maxage integer value"
   maxstale="Your maxstale integer value"
   method="get"|"post"|"put"|"delete"
   name="Your name value"
   namelist="variable_1 variable_2 ..."
   src="Your URI"
   srcexpr="Your ECMAScript expression"
   gvp:contentexpr="Your ECMAScript expression"
   gvp:fetchaudiodelay="Your time interval"
   gvp:fetchaudiominimum="Your time interval"
   gvp:passwordexpr="Your ECMAScript expression"
   gvp:usernameexpr="Your ECMAScript expression"
/>

Attributes

Individually, the src and srcexpr attributes are optional; however, the <data> tag requires that either the src or srcexpr attribute be provided. Otherwise, the document containing the <data> tag will generate a parsing error.

Attribute

Description

enctype

(Optional) If the method attribute value is post or put, this attribute specifies the MIME encoding of the submitted data. The valid values are:

  • Application/x-www-form-urlencoded

  • Multipart/form-data

  • Application/json

The default value is application/x-www-form-urlencoded.

fetchaudio

(Optional) This attribute specifies the URI of the audio to play while waiting for the XML data to be fetched.

This attribute overrides the value of the fetchaudio property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

fetchhint

(Optional) This attribute specifies when the XML data should be fetched. The valid value is:

  • Safe—If the value equals safe, the XML data is only load when needed.

This attribute overrides the value of the datafetchint property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the XML data to be fetched before an error.badfetch event is thrown.

This attribute overrides the value of the fetchtimeout property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

maxage

(Optional) This attribute indicates that this document will use a cached copy of the XML data if the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the datamaxage property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the XML data that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute overrides the value of the datamaxstale property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

method

(Optional) This attribute specifies the request method. The valid values are:

  • get

  • post

  • put

  • delete

If unspecified, the default value is get. If specified as any other value, an error.semantic event is generated when the tag is visited.

This attribute is not case sensitive.

name

(Optional) This attribute specifies the name of the variable that exposes the DOM.

If this attribute is specified and the web server returns a 204 No Content response, the Interpreter will not check for the presence of the content-type and content-length headers. The Interpreter will not alter the value of the <data> name variable, and will not throw error.badfetch.

For details about ECMAScript functions to navigate this variable, see the Voice Extensible Markup Language (VoiceXML) 2.1, W3C Recommendation 19 June 2007.

namelist

(Optional) This attribute specifies a space-separated list of variables to submit with the request. Any declared VoiceXML and ECMAScript variables can be referenced.

The default value is an empty list.

src

(Optional) This attribute specifies the URI of the request, to fetch the XML or JSON data.

srcexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the URI of the request, to fetch the XML or JSON data.

If srcexpr cannot be evaluated, an error.semantic event is thrown.

gvp:contentexpr

This attribute specifies an ECMAScript expression that is evaluated in the context of the <data> element.

This attribute is valid only when the method attribute is put or post, and only one of contentexpr and namelist attribute is allowed.

The value of contentexpr will be converted to the format specified with the enctype attribute and transmitted in the HTTP request content. Only application/json is supported.

Example:

  <block>
<var name="Address" expr="new Object()"/>
<script>
Address.city = "San Francisco"
Address.state = "CA"
Address.street = "1 Columbus Ave"
</script>
<data name="sample" gvp:contentexpr="Address" src="http://10.0.0.117:8080/mytest/NGI/receiveJSON.jsp"
 enctype="application/json" method="POST"/>
</block>

In the HTTP POST request, the content of the body must be:

{city:"San Francisco", state:"CA", street:"1 Columbus Ave"}

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiodelay

(Optional) This attribute specifies the length of time to wait at the start of the fetch delay before playing fetchaudio.

This attribute overrides the value of the fetchaudiodelay property (for details see the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiominimum

(Optional) This attribute specifies the minimum length of time to play fetchaudio, once started, even if the document arrives in the meantime.

This attribute overrides the value of the fetchaudiominimum property (for details see the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:passwordexpr

(Optional) This attribute takes an EcmaScript expression, which will be evaluated to a string. The Interpreter passes the value to the Fetching Module as the password for HTTP Basic Authentication. The Interpreter does not perform validation of the value.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Note: If the password evaluates to a string exceeding 255 characters, or if the sum of the lengths of password and username exceeds 506 characters, they will be truncated in the HTTP request sent to the web server.

gvp:usernameexpr

(Optional) This attribute takes an EcmaScript expression, which will be evaluated to a string. The Interpreter passes the value to the Fetching Module as the user name for HTTP Basic Authentication. The Interpreter does not perform validation of the value.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Note: If the username evaluates to a string exceeding 255 characters, or if the sum of the lengths of password and username exceeds 506 characters, they will be truncated in the HTTP request sent to the web server.

Parent

Block, Catch, Error, Filled, Foreach, Form, Help, If, Noinput, Nomatch, and Vxml

Child

None

GVP Extensions

  • fetchaudiodelay attribute

  • fetchaudiominimum attribute

  • passwordexpr attribute

  • usernameexpr attribute

Examples

  • The first example shows how to use the <data> tag to fetch XML data.

  • The second example shows how to use the <data> tag to fetch JSON data.

  • The third example shows how to use the <data> tag to fetch JSON data when the method attribute is set to post or put.

Example 1—Fetching XML data

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
  <data name="quotedata" src="http://www.quoteserver.com/20040517/f.xml"/>
  <form>
    <block>
      <var name="quote" expr="quotedata.documentElement"/>
      The change for Ford Motor Company is
      <value expr="quote.getElementsByTagName('change').item(0).firstChild.data"/>.
    </block>
  </form>
</vxml>

The XML data associated with the preceding example is:

<?xml version="1.0"?>
<?access-control allow="*"?>
<quote>
  <ticker>F</ticker>
  <name>Ford Motor Company</name>
  <change>1.00</change>
  <last>30.00</last>
</quote>

Example 2—Fetching JSON data

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form>
   <block name = "block1">
      <data name="sample1" src="dataJSON1Sample.txt"/>
      <script>
         var first = sample1.firstName;
         var city = sample1.address.city;
      </script>
      <log>
         <value expr="first"/>
      </log>
      <log>
         <value expr="city"/>
      </log>
   </block>
</form>
</vxml>

The text file (dataJSON1Sample.txt) with the data associated with the preceding example is:

{
   "firstName": "Jason",
   "lastName": "Jones",
   "address":
   {
      "city": "San Francisco, CA",
      "zip": 94121,
      "address": "444 Columbus Ave"
   },
   "email":
   [
      "jason@sf.com","sjones@adobe.com"
   ]
}

Example 3—Fetching JSON data when method is set to post or put

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form>
   <block name = "block1">
      <var name="firstName"/>
      <var name="lastName"/>
      <var name="Address" expr="new Object()"/>
      <var name="email" expr="new Array()"/>
      <script>
         firstName = "Jason";
         lastName = "Jones";
         Address.city = "San Francisco";
         Address.state = "CA";
         Address.street = "1 Columbus Ave";
         email.push("jason@sf.com");
         email.push("jason@yahoo.com");
      </script>
      <data name ="sample1" src="http://myserver/ocsresponse.php"
       enctype="application/json" method="post" namelist="firstName lastname Address email"/>
   </block>
</form>
</vxml>

The HTTP request will look like this:

POST /ocsresponse.php HTTP/1.1

Host: myserver

....

Content-Type=application/json

Content-Length=xx

{firstName:"Jason", lastName:"Jones", Address:{city:"San Francisco", state:"CA", street:"1 Columbus Ave"}, email:["jason@sf.com", "jason@yahoo.com"]}

Known Issues and Recommendations

The <data> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.

Variables declared in the name attribute must not:

  • Start with the underscore character (_).

  • End with the dollar sign character ($).

  • Contain a dot (for example, x.y).

If one of these characters is included, the error.semantic event is thrown when the tag is executed.

When a recording is submitted in the namelist of a <data> request with enctype="multipart/form-data", the Content-Type of the submitted audio data in the request is set to the actual MIME type associated with the audio file format of the recording.

When using the DOM methods to parse XML data, note that:

  • The DOM methods getAttribute() and getAttributeNS() return an empty string if an attribute does not exist.

  • XML namespaces are supported for DOM methods such as getAttributeNS().

  • The DOM method hasChildNodes() returns an ECMAScript value true or false.

When using JSON to deserialize a string into an object where one of the properties is an ECMAScript reserved word (for example, double), as shown in the following code sample, you will not be able to access the variable (double):

<var name="JSONVar"
     expr="{'double':{'content':'40.015','XMLNS':'HTTP://WWW.WEBSERVICEX.NET/'}}"
/>

Note: This syntax does not result in an error; however, you will not be able to access the variable (double).


Disconnect

Standard VoiceXML > VoiceXML Tags

<disconnect>

This tag disconnects the user's phone call. As a result, the Interpreter context throws the connection.disconnect.hangup event. A <disconnect> differs from an <exit> in that it forces the Interpreter context to drop the call.

Syntax

<disconnect
   namelist="var1  var2 ..."
   gvp:expr="Your ECMAScript expression"
   gvp:reasonexpr="Your ECMAScript expression"
/>

Attributes

Only one of the attributes expr or namelist can be specified; otherwise, the document containing the tag will generate a parse error.

Attribute

Description

namelist

(Optional) This attribute, new in VoiceXML 2.1, specifies a space-separated list of variables to be returned to the Interpreter context when the hang up request is sent. See the Known Issue and Recommendation below.

If this tag is used, the <vxml> version attribute must equal 2.1. Otherwise, the document containing this tag will generate a parsing error.

The namelist will be URL encoded as name=value&name=value, with each value encoded using JSON.

If a variable in the namelist attribute cannot be evaluated, an error.semantic event is thrown.

gvp:expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated and returned to the calling context. See the Known Issue and Recommendation below.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:reasonexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated and returned to the calling context. It is evaluated to a string and is used as the value of the Reason header in the SIP BYE message. The NGI does not validate the content. The user is expected to properly specify the value of this attribute by following RFC 3326: The Reason Header Field for SIP (http://www.ietf.org/rfc/rfc3326.txt).

This format enables the user to specify the ISDN disconnect cause code when PSTNC is used. PSTNC will read from the Reason header and generate the ISDN disconnect cause code accordingly. For example: <disconnect gvp:reasonexpr="'Q.931; cause=200; text=&quot;VXML disconnect&quot;'"/>

In the SIP BYE message, the Reason header will be: Reason: Q.931; cause=500; text=”VXML disconnect”

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

  • reasonexpr attribute

  • expr attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      Thanks for calling. Goodbye.
      <disconnect/>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <disconnect> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.

The expr and namelist attributes can be specified but are not useful in PSTN environments. These attributes are only useful when used in a VoIP platform, where the SIP BYE message is used to terminate a call. Additional information (in this case, attribute/value pairs) can be sent with the terminating SIP BYE message. In the case of a PSTN hangup/disconnect, additional information cannot be sent. These attributes are useful for advanced applications that use external elements (such as an external call control server) in addition to the VoiceXML server. In such applications, calls are routed to the VoiceXML server from the external servers whenever VoiceXML must be executed to collect user input. After input has been collected, information can be passed back to the external servers with a <disconnect> tag.


Else

Standard VoiceXML > VoiceXML Tags

<else>

This tag is used within the conditional logic statement <if> and with the optional <elseif> tag. It is used to define content to be executed if the conditions specified by the <if> and any previous <elseif> tags are not satisfied.

Syntax

<else/>

Attributes

None.

Parent

If

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <var name="number_var" expr="5"/>
    <var name="boolean_var" expr="true"/>
    <var name="string_var" expr="'hello'"/>
    <block>
      <if cond="number_var != 5">
        The number is not five.
      <elseif cond="!boolean_var"/>
        The boolean is not true.
      <elseif cond="string_var != 'hello'"/>
        The string is not hello.
      <else/>
        The number is five and
        the boolean is true and
        the string is hello.
      </if>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


ElseIf

Standard VoiceXML > VoiceXML Tags

<elseif>

This tag is used within the conditional logic statement <if> and with the optional <else> tag. It is used to define content to be executed in a specific condition and is only interpreted if the conditions specified by the <if> tag and any previous <elseif> tags are not satisfied.

Syntax

<elseif
    cond="Your ECMAScript expression"
/>

Attributes

Attribute | Description
cond | This attribute specifies an ECMAScript expression to be evaluated as a boolean value for this conditional logic statement.

Parent

If

Children

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <var name="number_var" expr="5"/>
    <var name="boolean_var" expr="true"/>
    <var name="string_var" expr="'hello'"/>
    <block>
      <if cond="number_var != 5">
        The number is not five.
      <elseif cond="!boolean_var"/>
        The boolean is not true.
      <elseif cond="string_var != 'hello'"/>
        The string is not hello.
      <else/>
        The number is five and
        the boolean is true and
        the string is hello.
      </if>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Enumerate

Standard VoiceXML > VoiceXML Tags

<enumerate>

This tag is an automatically generated description of the choices available to the user. It specifies a template that is applied to each choice in the order they appear in the <menu> tag, or in a <field> tag that contains <option> tags.

The <enumerate> tag may only be used within the prompts and the catch tags associated <menu> or <field> tags that contain <option> tags. As well, when used in catch tags for such elements, the <enumerate> tag is not supported in form, document, or application level event handlers; only in handlers within <field> or <menu> tags.

Syntax

<enumerate>
   child tags
</enumerate>

Attributes

None.

Anonymous Variables

If <enumerate> is used with no content, a default template that lists all choices is used. If it has content, the content is the template specifier. This specifier may refer to two variables:

  • _prompt—This is the prompt for the current choice (the content of the <choice> or <option>).

  • _dtmf—This is the assigned DTMF sequence for the current choice.

Parent

Audio, Catch, Error, Field, Foreach, Help, If, Menu, Noinput, Nomatch, and Prompt

Child

Audio, Text (#PCDATA), and Value

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="maincourse">
      <prompt>
        Please select an entree.
        <enumerate>
          For <value expr="_prompt"/>, press <value expr="_dtmf"/>.
        </enumerate>
      </prompt>
      <option dtmf="1"> sword fish </option>
      <option dtmf="2"> roast beef </option>
      <filled>
        Very good.
        I'll bring out your <value expr="maincourse"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The <enumerate> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Error

Standard VoiceXML > VoiceXML Tags

<error>

This tag catches error events thrown by the VoiceXML application or by GVP. The <error> tag associates an error handler with a document, dialog (form or menu), or form item. It contains executable content. It is a shorthand notation for <catch event="error"> and catches all error events with a name whose prefix is error. For example, error.badfetch and error.grammar.asr can be handled by this tag.

Syntax

<error
   cond="Your ECMAScript expression"
   count="Your count value">
   child tags
</error>

Attributes

Attribute | Description
cond | (Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This <error> tag will only catch the error if the expression evaluates to true. The default value is true.
count | (Optional) This attribute allows you to handle different occurrences of the same error event differently. Each form, menu, and form item maintains a counter for each error event that occurs while it is being visited. These counters are reset each time the menu or form item's form is re-entered. When more than one <error> tag catches the same error event, the tag in the closest scope with the highest count that is less than or equal to the current counter will be selected. The default value is 1.

Anonymous Variables

  • _event—Contains the name of the error event that was thrown.

  • _message—Contains the message string from the corresponding <throw>, <choice>, <link>, or <return> tag, or a platform defined value for error events thrown by the platform. If no message is specified, the value of this variable is ECMAScript undefined.

  • _url—Contains the url of the page where the error occurred.

  • _element—Contains the name of the element that generated the event.

  • _line—Contains the line number of the start of the element that generated the event.

Parent

Field, Form, Initial, Menu, Object, Record, Subdialog, Transfer, and Vxml

Child

Assign, Audio, Clear, Data, Disconnect, Enumerate, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

Genesys Extensions

  • The _url variable

  • The _element variable

  • The _line variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <error>
     An error has occurred.
     <exit/>
  </error>
  <form>
    <property name="TTSENGINE" value="NONEXISTENT"/>
    <block>
      Trying to use an invalid TTS engine will cause an error.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Exit

Standard VoiceXML > VoiceXML Tags

<exit>

This tag exits the Interpreter session and returns control to the Interpreter context, which determines what to do next. This tag differs from the <return> tag in the case that <exit> terminates all loaded tags, while the <return> returns from a <subdialog> that is already invoked.

Note: The <exit> tag does not cause an exit event to be thrown.

The <exit> tag is comparable to the <disconnect> tag:

  • The <exit> tag is similar to the <disconnect> tag, in that <disconnect> will terminate the current dialog and return control to the Interpreter. For example, the browser will release the call.

  • The <exit> tag allows the developer to specify both a namelist and an expression that can be sent back to the browser, whereas the <disconnect> tag has no inherent method of sending such information back to the browser.

  • The <exit> tag will not throw a connection.disconnect event, however the <disconnect> tag will.

Syntax

<exit
    expr="Your ECMAScript expression"
    namelist="var1 var2 ..."
/>

Attributes

The expr and namelist attributes are optional; however, only one of them is required. Otherwise, the document containing the tag will generate a parsing error.

Attribute | Description
expr | (Optional) This attribute specifies an ECMAScript expression to be evaluated. See below for details on General Usage.
namelist | (Optional) This attribute specifies a space-separated list of variables to be returned to the Interpreter context when the exit request is sent. It returns nothing by default. See below for details on General Usage as well as Usage with Multiphase Transfers. The namelist will be URL encoded as name=value&name=value, with each value encoded using JSON. If a variable in the namelist attribute cannot be evaluated, an error.semantic event is thrown.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      Thanks for calling.
      <exit/>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <exit> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.

General Usage

The expr and namelist attributes can be specified but are not useful in PSTN environments. These attributes are only useful when used in a VoIP platform, where the SIP BYE message is used to terminate a call. Additional information (in this case, attribute/value pairs) can be sent with the terminating SIP BYE message. In the case of a PSTN hangup/disconnect, additional information cannot be sent.

These attributes are useful for advanced applications that use external elements (such as an external call control server) in addition to the VoiceXML server. In such applications, calls are routed to the VoiceXML server from the external servers whenever VoiceXML must be executed to collect user input. After input has been collected, information can be passed back to the external servers with an <exit> tag.

CCXML-Specific Note:

If you are writing a VoiceXML dialog for use in a CCXML application, note that if the CCXML application uses <dialogterminate> to end the VoiceXML dialog, the dialog cannot return results in the <exit> namelist.

Usage with Multiphase Transfers

One exception to the preceding generalization is the use of <exit> namelist in multiphase transfers (for example, when <transfer> consultexpr is set). After interacting with the callee, a child script can pass information (including the accepttransfer boolean variable to indicate whether the call is accepted) back to the parent page by exiting with <exit namelist="<var1> <var2> .../>. The combined length of the variable names and values must not exceed 4096 characters. The parent page can then access these results through the <transfer> shadow variable(s) <transfer_name>$.result.<vari>.


Field

Standard VoiceXML > VoiceXML Tags

<field>

This tag declares an input field in a form and prompts user for values that match a grammar.

Syntax

<field
   cond="Your ECMAScript expression"
   expr="Your ECMAScript expression"
   modal="Your modal value (a boolean)"
   name="Your name value"
   slot="Your ECMAScript expression"
   type="boolean"|"currency"|"date"|"digits"|"number"|"phone"|"time"
   gvp:audioinexpr="Your ECMAScript expression"
   gvp:endbeep="true"|"false"
   gvp:private="true"|"false"
   gvp:recordutterance="Your record utterance value"
   gvp:recordutterancetype="Your record utterance type value"
   gvp:utterancedest="Your utterance audio destination"
   gvp:wakeupword="Your wakeup word value">
    child tags
</field>

Attributes

Attribute

Description

cond

This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This field will be visited only if the expression evaluates to true.

The default value is true.

expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the initial value of this field. This field will be visited only if the expression evaluates to undefined.

The default value is undefined.

name

(Optional) This attribute specifies the name of this field. This variable holds the matched user input and can be referenced anywhere within the field's form.

This attribute defaults to an inaccessible internal variable.

modal

(Optional) This attribute specifies which grammars are enabled. The valid values are:

  • True—If this value is true, only the field's grammars are to be enabled.

  • False—If this value is false, all active grammars are enabled (while this field is visited in the collect phase of the FIA.).

The default value is false.

slot

(Optional) This attribute is a very restricted ECMAScript expression that selects some portion of the result to be assigned to the field (usually used for mixed initiative dialogs). In addition to selecting the top-level result property, the attribute can select properties at arbitrary levels of nesting, using a dot-separated list of tag or property names (for example, pizza.number or order.pizza.topping). If this attribute is used to select a sub-property of the result, and that sub-property does not exist in the result, then the field does not match the result (even if the name of <field> matches a property name of the form-level grammar result), and the field will not be matched.

The default value is "your ECMAScript expression".

type

(Optional) This attribute specifies a built-in speech and DTMF grammar for this field. This attribute provides an alternative to using speech and DTMF <grammar> tags to specify the built-in grammar.

gvp:audioinexpr

(Optional) This attribute specifies an ECMAScript expression which should evaluate to a string that specifies a recording to be used as speech input in this field. This can specify a complete or relative URI, or a variable reference to a recording (for example, <record> variable, or $.utteranceaudio shadow variable). This value is to be passed to the platform as a recognition parameter.

If the ECMAScript is invalid, an error.semantic is thrown.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:endbeep

(Optional) This attribute specifies whether a beep should be played at the end of the prompts. The valid values are:

  • True—If this value is true, the last fragment of the prompt queue sent to the platform for this <field> must be of type endbeep.

  • False—If this value is false, an endbeep will not be played.

If neither true or false is used, an error.semantic is generated when the <field> tag is visited.

The beep is treated as any <audio> tag.

Access the audio file at the location specified in the vxmli.beep.uri parameter.

This attribute overrides the value of the com.genesyslab.endbeep property.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

The default value is false.

gvp:private

(Optional) This attribute enables data masking for logged metrics (interaction-level messages that described call flow). This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:

  • True—If gvp:private equals true, data masking is enabled. The data that is masked includes:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • False—If gvp:private equals false, data masking is not enabled (no data is masked).

The default value is false. If an invalid value is used, the page will be rejected.

This attribute takes precedence over com.genesyslab.private.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:recordutterance

(Optional) This attribute enables or disables the recording of user utterance. The valid values are:

  • True—If this value is true, enable recording of user utterances.

  • False—If this value is false, disable recording of user utterances.

This attribute overrides the value of the recordutterance property (for details search the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

The default value is false.

gvp:recordutterancetype

(Optional) This attribute specifies the media type of the recorded utterance, if recordutterance is enabled.

This attribute overrides the value of the recordutterancetype property (for details, see the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

The default value is audio/basic.

gvp:utterancedest

(Optional) This attribute specifies the path to the directory where the utterance-audio files are saved. The value is resolved relative to the configured directory. This attribute overrides the value of the com.genesyslab.utterancedest property.

The default location is C:\Program Files\SpeechWorks\MediaServer\server\session in your Speech Works Media Server SWMS.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:wakeupword

(Optional) This attribute specifies whether Wakeup Word Spotting should be used for input in this field.

This attribute overrides the value of the com.genesyslab.wakeupword property. (Only supported with SpeechWorks OSR.)

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

The default value is false.

An error.unsupported.builtin event is thrown at runtime if:

  • A reserved ECMAScript word is used as the name.

  • vxmli.conformance.supported_builtin_dtmf and/or vxmli.conformance.supported_builtin_voice are set.

  • The type attribute references an invalid builtin type.

Shadow Variables

For each <field> tag whose name attribute is set to <your name value>, there is a shadow variable <Your name value>$ (in the same scope as the field name variable), containing the following properties:

Property

Description

<Your name value>$
.confidence

The recognition confidence level. Floating point value between 0.0 and 1.0.

<Your name value>$
.inputmode

The user input mode. The valid values are:

  • dtmf—If this property contains dtmf, the grammar builtin:dtmf/<type> is enabled.

  • voice—If this property contains voice, the grammar builtin:grammar/<type> is enabled.

The Interpreter does not perform any checking on the validity of <type>.

<Your name value>$
.interpretation

The same value as application.lastresult$.interpretation.

<Your name value>$
.markname

The name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. This only meaningful when the <field>'s prompts contain at least one <mark> tag.

This property is a new VoiceXML 2.1 feature.

<Your name value>$
.marktime

The number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. This only meaningful when the <field>'s prompts contain at least one <mark> tag.

This property is a new VoiceXML 2.1 feature.

<Your name value>$
.recording

A reference to the recording, or undefined if no audio is collected. This is only meaningful if the recordutterance property is set to true.

This property is a new VoiceXML 2.1 feature.

<Your name value>$
.recordingduration

The duration of the recording, or undefined if no audio is collected. This is only meaningful if the recordutterance property is set to true.

This property is a new VoiceXML 2.1 feature.

<Your name value>$
.recordingsize

The size of the recording in bytes, or undefined if no audio is collected. This is only meaningful if the recordutterance property is set to true.

This property is a new VoiceXML 2.1 feature.

<Your name value>$
.audiooffset

The offset of the audio data on bargein (the value is -1 if the audio was played to the end). This is undefined if the last played prompt was not <audio>.

This property is a GVP extension.

<Your name value>$
.bargein

The value is true if bargein occurred, and it is false otherwise.

This property is a GVP extension.

The field shadow variable is only set if the user's input is recognized and the field name variable is set, according to the Field Variable Assignment rules. The application.lastresult$ object has corresponding properties which are set after every utterance, even if a nomatch occurs or the recognition result is not used to set the field variable. Also, when any shadow variable is not set, its value will be ECMAScript undefined.

Built-in Types

Type | Description
boolean | Grammar for affirmative and negative phrases. Returns true for "yes" (or DTMF equivalent) and false for "no" (or DTMF equivalent).
currency | Grammar for currency amount. The result is a string with the format UUUmm.nn, where UUU is the three character currency indicator according to ISO standard 4217:1995, or mm.nn if the currency is not spoken by the user or if the currency cannot be reliably determined (for example, "dollar" and "peso," are ambiguous). If the field value is subsequently used in a prompt, it will be spoken as a currency amount appropriate to the current locale. The set of accepted spoken currency formats is platform dependent and may vary by locale.
date | Grammar for specifying a date. Returns a fixed-length date string format yyyymmdd. If the year is not specified, yyyy becomes ????; if the month is not specified, mm becomes ??; if the day is not specified, dd becomes ??.
digits | Grammar for a string of digits. Returns the string of digits.
number | Grammar for numbers. Returns a string of digits from 0 to 9, and may optionally include a decimal point (.) and/or a plus or minus sign.
phone | Grammar for a phone number. DTMF asterisk "*" represents "x". The result is a string containing a telephone number consisting of a string of digits and optionally containing the character "x" to indicate a phone number with an extension. For North America, a result could be "8005551234x789".
time | Grammar for specifying time. The result is a five character string in the format hhmmx, where x is one of "a" for AM, "p" for PM, "h" to indicate a time specified using 24 hour clock, or "?" to indicate an ambiguous time. Because there is no DTMF convention for specifying AM/PM, in the case of DTMF input, the result will always end with "h" or "?".

The boolean and digits built-in types can be parameterized with the following syntax:

typename?parameter1=value1;parameter2=value2

For example, DTMF equivalents for "yes" and "no" can be assigned in the boolean type:

<field name="mychoice" type="boolean?y=5;n=6">

Type

Input Parameters

boolean

  • y—The DTMF sequence for an affirmative answer

  • n—The DTMF sequence for a negative answer

digits

  • minlength—The minimum number of digits

  • maxlength—The maximum number of digits

  • length—The exact number of digits

If there is a conflict among these parameters, an error.badfetch event is thrown.

Parent

Form

Child

Audio, Catch, Enumerate, Error, Filled, Grammar, Help, Link, Noinput, Nomatch, Option, Prompt, Property, Text (#PCDATA), and Value

GVP Extensions

  • audioinexpr attribute

  • endbeep attribute

  • private attribute

  • recordutterance attribute

  • recordutterancetype attribute

  • utterancedest attribute

  • wakeupword attribute

  • audiooffset shadow variable

  • bargein shadow variable

  • info shadow variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="boolean">
      <prompt> Please say yes or no. </prompt>
      <filled>
        You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

Using the private attribute does not prevent sensitive data from being logged. Therefore, if the VoiceXML application should not log certain data, Genesys recommends that the VoiceXML application use the post method not the get method to submit the data to the web server.

When a <field> tag has a type attribute, it will not enable any field-level grammars defined inside the field (they are silently ignored with a user warning). However, outer scope grammars may still be active, depending on the modal attribute.

The availability of the wakeupword attribute functionality, depends on the support from the underlying platform. Refer to your ASR vendor documentation for details.


Filled

Standard VoiceXML > VoiceXML Tags

<filled>

This tag specifies an action to perform when some combination of input items are filled by user input. After the user's input is gathered and the relevant input items are set, the Interpreter looks at each <filled> tag in document order. Those whose conditions are matched by the utterance are then executed in order.

Syntax

<filled
    mode="all"|"any"
    namelist="item1 item2 ...">
  child tags
</filled>

Attributes

Attribute

Description

mode

(Optional) This attribute provides the filled mode. The attribute cannot be defined when the <filled> tag is in an input item. The valid values are:

  • All—If the value equals all, the <filled> tag is executed when all of the input items in the namelist attribute are filled, and at least one has been filled by the last user input.

  • Any—If the value equals any, the <filled> tag is executed when any of the specified input items is filled by the last user input.

If an invalid value is specified, an error.semantic event is generated when the filled is encountered.

The default value is all.

namelist

(Optional) This attribute provides the list of input items that will trigger this <filled> tag. This attribute cannot be defined when <filled> is in an input item.

The default is a list of all the form's input items.

An error.badfetch event is thrown if mode or namelist is specified for a <filled> tag that is within an input item (for example, in a <field> tag).

Parent

Field, Form, Object, Record, Subdialog, and Transfer

Child

Assign, Audio, Clear, Data, Disconnect, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit,
Text (#PCDATA), Throw, Value, and Var

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="boolean">
      <prompt> Please say yes or no. </prompt>
      <filled>
        You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

None.


ForEach

Standard VoiceXML > VoiceXML Tags

<foreach>

This tag, new in VoiceXML 2.1, iterates through the given ECMAScript array and repeats the enclosed content. The tag:

  • Will not create its own scope; all ECMAScript operation within the tag is done in the parent's scope.

  • Operates on a shallow copy of the array specified by the array attribute.

If this tag is used, the <vxml> version attribute must equal 2.1; otherwise, an error.badfetch will be thrown.

Syntax

<foreach
    array="Your ECMAScript expression"
    item="Your ECMAScript variable">
  child tags
</foreach>

Attributes

Both the array and item attributes must be specified; otherwise, the document will generate a parse error.

Attribute | Description
array | This attribute is an ECMAScript expression to be evaluated and used as the array. If the expression does not evaluate to an ECMAScript array, an error.semantic will be thrown.
item | This attribute is an ECMAScript variable that stores the array item upon each iteration of the loop. A new variable will be declared if it is not already defined within the parent's scope.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, Nomatch, and Prompt

Child

Assign, Audio, Clear, Data, Disconnect, Enumerate, Exit, Foreach, Goto, If, Log, Mark, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      <var name="numbers" expr="new Array(1, 2, 3, 4, 5)"/>
      <foreach array="numbers" item="i">
         The square of <value expr="i"/> is <value expr="i*i"/>.
      </foreach>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

If the <foreach> tag is used as a child of the <prompt> tag, and the GVP vxmli.conformance.disallow_exec_content_within_prompts parameter is set to true, it can only contain:

  • <audio>

  • <enumerate>

  • <foreach>

  • <mark>

  • Speech Markup (SSML)

  • Text (#PCDATA)

  • <value>


Form

Standard VoiceXML > VoiceXML Tags

<form>

This tag is a key component in VoiceXML applications. Forms collect user input and present information to the user. A form can define a field item (for collecting user input) or a control item (containing procedural items to help collect inputs).

Syntax

<form
    id="Your ID value"
    scope="dialog"|"document"
    gvp:cleardtmf="Your clear DTMF value">
  child tags
</form>

Attributes

Attribute

Description

id

(Optional) This attribute specifies the name of this form. If specified, it can be referenced within the same document or from another document. For example, <form id="hello"> can be referenced by <goto next="#hello"/>.

Matching this value is case sensitive.

scope

(Optional) This attribute specifies the scope of the form's grammars. The valid values are:

  • Dialog—If the value equals dialog, then the form's grammars are only active within the form.

  • Document—If the value equals document, then the form's grammars are active throughout the document. If the current page is an application root document, then the form grammars are active throughout the application.

If any other value is specified, an error.semantic event is thrown when the form is initialized.

The default value is dialog.

gvp:cleardtmf

(Optional) This attribute specifies whether the DTMF buffer should be cleared on entry to this form or whether any remaining DTMF inputs from previous forms should be carried over to this form. The valid values are:

  • True—If the value equals true, the buffer is cleared.

  • False—If the value equals false, the buffer is not cleared (the DTMF input is carried over).

If any other value is specified, an error.semantic event is thrown when the form is initialized.

T his attribute is a GVP extension and must be prefixed by the GVP namespace when used in the page.

The default value is false.

Parent

Vxml

Child

Block, Catch, Data, Error, Field, Filled, Grammar, Help, Initial, Link, Noinput, Nomatch, Object, Property, Record, Script, Subdialog, Transfer, and Var

GVP Extensions

  • cleardtmf attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form id="first">
    <block>
      This is a form.
      <goto next="#second"/>
    </block>
  </form>
  <form id="second">
    <block>
      This is another form.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

An error.badfetch event is thrown if multiple forms and/or grammars have the same id (on the same page).


Goto

Standard VoiceXML > VoiceXML Tags

<goto>

This tag provides the ability to transition to one of the following:

  • An item in the current form (for example, <goto nextitem="Your field name"/>)

  • A dialog (for example, a form or menu) in the current document (for example, <goto next="Your form id number"/>)

  • A document (for example, <goto next="Your URI"/>)

  • A dialog (for example, a form or menu) in a document (for example, <goto next="Your URI number form id"/>)

Document variables are lost when transitioning to the current document with a URI reference. For example, if the current document is http://www.voicexml.org/index.vxml, the document variables are lost if the following syntax is used to transition to the foo dialog in the current document:

<goto next="http://www.genesyslab.com/index.vxml#foo"/>

Document variables are retained when transitioning to the current document with an empty URI reference. For example, the document variables are retained if the following syntax is used to transition to the foo dialog in the current document:

<goto next="#foo"/>

Note: Using a URI to transition to a document causes the old document's variables to be lost. Be aware of this when deciding which syntax to use to transition to a dialog in the current document.

Syntax

<goto
   expr="Your ECMAScript expression"|expritem="Your ECMAScript expression"|next="Your URI"|nextitem="Your next item"
   fetchaudio="Your URI"
   fetchhint="safe"
   fetchtimeout="Your time interval"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   gvp:fetchaudiodelay="Your time interval"
   gvp:fetchaudiominimum="Your time interval"
/>

Attributes

The next, expr, nextitem, or expritem attributes are optional; however, one of them is required. If more or less than one of next, expr, nextitem, or expritem are specified, the document containing the tag will generate a parsing error.

Attribute

Description

expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the URI of the dialog (for example, a form or menu) or document to transition to when this <goto> is executed.

An error.badfetch event is thrown if this attribute refers to a non-existent dialog (for example, a form or menu), either within the same page, or within a different, existent, page.

expritem

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the URI of the form item to transition to when this <goto> is executed.

fetchaudio

(Optional) This attribute specifies the URI of audio to play while waiting for the document to be fetched.

This attribute overrides the value of the fetchaudio property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

fetchhint

(Optional) This attribute specifies when the next document should be fetched. The valid value for this attribute is:

  • Safe—If the value equals safe, the next document is only loaded when it is needed.

This attribute overrides the value of the documentfetchhint property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the next document to be fetched before throwing an error.badfetch event.
The value of the attribute can be either seconds or milli seconds. For example, fetchtimeout=”6s” or fetchtimeout=”5000ms”.

This attribute overrides the value of the fetchtimeout property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxage

(Optional) This attribute indicates that this document will use a cached copy of the next document if the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the documentfetchhint property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the next document that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute overrides the value of the documentmaxstale property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

next

(Optional) This attribute specifies the URI of the dialog (for example, a form or menu) or document to transition to when the <goto> tag is executed.

An error.badfetch event is thrown if this attribute refers to a non-existent dialog (for example, a form or menu), either within the same page or within a different, existent, page.

nextitem

(Optional) This attribute specifies the URI of the form item to transition to when this <goto> is executed.

gvp:fetchaudiodelay

(Optional) This attribute specifies the length of time to wait at the start of the fetch delay before playing fetchaudio. The value of the attribute can be either seconds or milliseconds. For example, gvp:fetchaudiodelay=”6s” or gvp:fetchaudiodelay=”5000ms”.

This attribute overrides the value of the fetchaudiodelay property (for details search the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiominimum

(Optional) This attribute specifies the minimum length of time to play fetchaudio, once started, even if the document arrives in the meantime. The value of the attribute can be either seconds or milliseconds. For example, gvp:fetchaudiominimum=”6s” or gvp:fetchaudiominimum=”5000ms”.

This attribute overrides the value of the fetchaudiominimum property (for details search the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

  • fetchaudiodelay attribute

  • fetchaudiominimum attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      This is the first block.
      <goto nextitem="block2"/>
    </block>
    <block name="block2">
      This is the second block.
      <goto next="#form2"/>
    </block>
  </form>
  <form id="form2">
    <block>
      This is the second form.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <goto> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Grammar

Standard VoiceXML > VoiceXML Tags

<grammar>

This tag specifies a grammar for speech recognition or DTMF recognition. Inline grammars that use the XML grammar format will be passed into the ASR engine as an XML document. When the VoiceXML page is first parsed by the Interpreter, the inline grammar will be decoded. The Interpreter will then re-encode the inline grammar into an XML UTF-8 encoded document to pass to the ASR engine. For more information on writing DTMF grammars, refer to http://www.w3.org/TR/speech-grammar/

Syntax

<grammar
   fetchhint="safe"
   fetchtimeout="Your timeout value"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   mode="dtmf"|"voice"
   root="Your root value"
   scope="dialog"|"document"
   src="Your URI"|
   srcexpr="Your ECMAScript expression"
   type="Your MIME type"
   tag-format="Your tag-format string"|"Your URI"
   version="Your version value"
   weight="Your positive floating_point value"
   xml:base="Your URI"
   xml:lang="Your language value"
   gvp:contentexpr="Your ECMAScript expression"
   gvp:expr="Your ECMAScript expression"
   inline grammar
</grammar>

Attributes

Individually, src, expr, srcexpr, and contentexpr are optional. However, the tag requires that one of them, or an inline grammar, be provided. If more or less than one of src, expr, srcexpr, or contentexpr and an inline grammar are specified, the document containing the tag will generate a parsing error. If src, expr, or srcexpr are empty strings an external grammar fetch will be attempted. The resulting absolute URI will likely be an invalid URI and this will result in an error.badfetch event being thrown.

Attribute

Description

fetchhint

(Optional) This attribute specifies when the grammar file should be fetched. The valid value is:

  • Safe—If the value equals safe, the grammar files are loaded when needed.

This attribute overrides the value of the grammarfetchhint property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the grammar file to be fetched before throwing an error.badfetch event.

This attribute overrides the value of the fetchtimeout property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

This is not supported when using Nuance (MRCP).

maxage

(Optional) This attribute indicates that this document will use a cached copy of the grammar file if the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the grammarmaxage property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the grammar file that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute overrides the value of the grammarmaxstale property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

mode

(Optional) This attribute specifies the mode of the grammar. The valid values are:

  • Voice—If the value equals voice, then voice input is accepted.

  • DTMF—If the value equals DTMF, then DTMF input is accepted. This replaces the <dtmf> tag from VoiceXML 1.0.

The default value is voice.

root

(Optional) This attribute specifies the root rule of the grammar.

The default value depends on the ASR engine being used.

scope

(Optional) This attribute specifies the scope of the grammar. This attribute can be defined only if the <grammar> tag is the child of a <form> or <menu> tag. The valid values are:

  • Dialog—If this value equals dialog, this grammar is only active within the form.

  • Document—If this value equals document, this grammar is active throughout the document. If the current page is an application root document, then the grammar is active throughout the application.

The default value is dialog.

src

(Optional) This attribute specifies the URI of the grammar file. The URI can be one of the following formats:

  • An external grammar file—URL of the grammar file

  • A Built-in grammar—builtin:grammar/<Your type>. Refer to the <field> tag for built-in types.

srcexpr

(Optional) This attribute, new to VoiceXML 2.1, specifies an ECMAScript expression to be evaluated as the URI of the grammar file, as documented under src.

If the srcexpr attribute cannot be evaluated, an error.semantic event is thrown.

If this attribute is provided, the <vxml> version attribute must equal 2.1. Otherwise, the document containing the tag will generate a parsing error.

tag-format

(Optional) This attribute specifies the format that will be used to define tags, for slot filling. Support for this attribute depends on the ASR engine being used.

For DTMF, the supported formats are semantics/1.0 and semantics/1.0-literals.

type

(Optional) This attribute specifies the MIME type of the grammar format. The supported types (and default values) for this attribute depend on the ASR and/or DTMF engine being used.

The supported DTMF types are xml and abnf.

version

(Optional) This attribute specifies the version of the grammar.

The default value is 1.0.

weight

(Optional) This attribute specifies the weight of a grammar, which indicates the likelihood of using a grammar. This value is passed to the ASR engine and affects the actual recognition results returned by the ASR engine; it is not used by the VoiceXML Interpreter to process recognition results after they have been returned by the ASR engine. Different ASR engines and VoiceXML platforms treat weights differently. This attribute is not supported for DTMF grammars and implicit grammars (for example, <grammar> tags as children of <option> or <choice> tags). The range of values depends on the ASR engine, but it is usually 0.0 to 1.0.

The default value is 1.0.

xml:base

(Optional) This attribute specifies the base URI from which relative URIs in the grammar are resolved. This base declaration has precedence over the <vxml> base URI declaration.

If a local declaration is omitted, the value will be inherited down the document hierarchy.

xml:lang

(Optional) This attribute specifies the language identifier of the grammar. The list of supported values for this attribute depends on the ASR engine being used. This attribute is irrelevant for DTMF grammars.

The default value is platform specific. Refer to your ASR engine documentation for details.

gvp:contentexpr

(Optional) This attribute allows dynamic generation of grammars from an ECMAScript and accepts an ECMAScript expression.

This attribute is only supported by <grammar> within an input-item scope, that is, within a <field>, <record>, or <transfer> element. Otherwise, a parse error will occur.

When this attribute is specified, the evaluated ECMAScript will be used as the grammar content without performing any validation against the content type.

When vxmli.inlinegrammar_by_url=true, the Interpreter stores the grammar content to a local file that can be accessed by an http URL. The URL of the grammar file is passed to the recognition engine.

When vxmli.inlinegrammar_by_url=false, the Interpreter directly passes the grammar content to the recognition engine.

When <grammar> is specified with this attribute, if the grammar is to be exposed as a URL reference to an external recognizer, the type attribute value is used to map with a file extension for the grammar file name. If the grammar content is directly exposed to the recognizer, the type attribute is verified based on vxmli.grammar.mimetypes. For a type outside of the vxmli.grammar.mimetypes list, an error.unsupported.format is thrown.

When <grammar> is specified with this attribute, the mode attribute is used to specify which type of recognizer is to be used for the grammar. Valid values are voice and dtmf, with the default to voice.

When <grammar> is specified with this attribute, the attribute version xml:lang, root, tag-format, and xml:base of the <grammar> element will be ignored.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:expr

(Optional) This attribute is an ECMAScript expression to be evaluated and used as the initial value of this grammar. This record will be visited only if the expression evaluates to undefined.

The default value is undefined.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

If an unsupported built-in grammar is referenced, an error.unsupported.builtin will be thrown.

If scope is used in a <link> grammar or in an input item grammar, an error.badfetch will be thrown.

Parent

Choice, Field, Form, Link, Record, and Transfer

Child

Text (#PCDATA)

GVP Extensions

  • contentexpr attribute

  • expr attribute

Example

See Lesson 4 for an example.

Known Issues and Recommendations

Application developers should either make sure they explicitly specify the grammar type (for example, "application/grammar+xml") using the type attribute, or configure their application servers to return the correct MIME types for grammar files. Otherwise, GVP will consider the grammar to be invalid.

Using an escape sequence to replace non-ASCII accented characters (such as é) is not supported. For example, you cannot use <tag>out.a="\u00e9";</tag> or <tag>out.a="\351";</tag> to replace é.

DTMF Recognition Limitations:

  • XML grammars are only allowed to have a limited amount of text data within any tag. This limit is 4096 characters.

  • Semantic interpretation does not currently support UTF-8.

  • Global tags are not supported for ABNF grammars.

  • String literal syntax is not supported for ABNF grammars.

  • Semantic interpretation does not support the score property. It also does not support the nsdecl or nsprefix objects.

  • External Ruleref is not supported. A ruleref can be used only to refer a rule within the same grammar document.

  • Sufficiently complex grammars with sufficiently long input can cause resource starvation.

  • Grammar caching is not setup for the default installation.


Help

Standard VoiceXML > VoiceXML Tags

<help>

This tag catches a help event thrown by the VoiceXML application or GVP. The <help> tag associates a help handler with a document, dialog (form or menu), or form item. It contains executable content. It is a shorthand notation for <catch event="help">.

Syntax

<help
   cond="Your ECMAScript expression"
   count="Your count value">
  child tags
</help>

Attributes

Attribute | Description
cond | (Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This <help> tag will only catch the help event if the expression evaluates to true. The default value is true.
count | (Optional) This attribute allows you to handle different occurrences of the help event differently. Each form, menu, and form item maintains a counter for the help event while it is being visited. These counters are reset each time the menu or form item's form is re-entered. When more than one <help> tag catches a help event, the tag in the closest scope with the highest count that is less than or equal to the current counter will be selected. The default value is 1.

Anonymous Variables

  • _event—Contains the name of the event that was thrown (for example, help).

  • _message—Contains the message string from the corresponding <throw>, <choice>, <link>, or <return> tag, or a platform defined value (for example, help) for help events thrown by the platform. If no message is specified, the value of this variable is ECMAScript undefined.

  • _element—Contains the name of the element that generated the event.

  • _line—Contains the line number of the start of the element that generated the event.

  • _url—Contains the url of the page where the error occurred.

Parent

Field, Form, Initial, Menu, Object, Record, Subdialog, Transfer, and Vxml

Child

Assign, Audio, Clear, Data, Disconnect, Enumerate, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

GVP Extensions

  • _element variable

  • _line variable

  • _url variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <property name="universals" value="help"/>
  <form>
    <field name="field1" type="boolean">
      <help>
        Please say yes or no.
        <reprompt/>
      </help>
      <prompt> Is that correct? </prompt>
      <filled>
        You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

None.


If

Standard VoiceXML > VoiceXML Tags

<if>

This tag is a conditional logic statement that is used with the optional <elseif> and <else> tags. It is used to define content to be executed in a specific condition.

Syntax

<if cond="Your ECMAScript expression">
  child tags
</if>

Attributes

Attribute | Description
cond | This attribute specifies an ECMAScript expression to be evaluated as a boolean value for this conditional logic statement.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

Assign, Audio, Clear, Data, Disconnect, Else, ElseIf, Enumerate, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <var name="number_var" expr="5"/>
    <var name="boolean_var" expr="true"/>
    <var name="string_var" expr="'hello'"/>
    <block>
      <if cond="number_var != 5">
        The number is not five.
      <elseif cond="!boolean_var"/>
        The boolean is not true.
      <elseif cond="string_var != 'hello'"/>
        The string is not hello.
      <else/>
        The number is five and
        the boolean is true and
        the string is hello.
      </if>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <if> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Initial

Standard VoiceXML > VoiceXML Tags

<initial>

This tag provides the initial prompts, catches, and event counters while waiting for the user to provide form-wide information, in a mixed initiative form. Unlike <field>, <initial> has no grammars and no <filled> action; <initial> can only request user input and handle events. The <initial> item continues to be visited while its form item variable is undefined and cond is true.

When any of the form's fields are filled by user input, then all <initial> form item variables are set to true, before any <filled> actions are executed. Next, the form visits those fields that are still unfilled to complete the form. The <initial> tags of a form are set to true as type boolean, once one or more of the form's input item variables are set by user input.

Syntax

<initial
   cond="Your ECMAScript expression"
   expr="Your ECMAScript expression"
   name="Your name value"
   gvp:private="true"|"false"
   gvp:wakeupword="Your boolean value">
  child tags
</initial>

Attributes

Attribute

Description

cond

(Optional) This attribute is an ECMAScript expression to be evaluated as a boolean condition. This initial item will be visited only if the expression evaluates to true.

The default value is true.

expr

(Optional) This attribute is an ECMAScript expression to be evaluated as the initial value of this initial item. This initial item will be visited only if the expression evaluates to undefined.

The default value is undefined.

name

(Optional) This attribute is the name of this initial item. This variable can be referenced anywhere within the initial's form. Use this variable if you want to explicitly control the <initial> tag execution.

An error event may be thrown if a reserved ECMAScript word is used as the name.

The default value is an inaccessible internal variable.

gvp:private

(Optional) This attribute enables data masking for logged metrics (interaction-level messages that described call flow). This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:

  • True—If gvp:private equals true, data masking is enabled. The data that is masked includes:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • False—If gvp:private equals false, data masking is not enabled (no data is masked).

The default value is false. If an invalid value is used, the page will be rejected.

This attribute takes precedence over com.genesyslab.private.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:wakeupword

(Optional) This attribute specifies whether Wakeup Word Spotting should be used for input in this initial item.

This attribute overrides the value of the com.genesyslab.wakeupword property and is only supported with SpeechWorks OSR.

This attribute must be prefixed by the GVP-namespace.

This value defaults to false.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Form

Child

Audio, Catch, Error, Help, Link, Noinput, Nomatch, Prompt, Property, Text #PCDATA, and Value

GVP Extensions

  • private attribute

  • wakeupword attribute

Example

The syntax for specifying form-level grammars that can be used with the <initial> tag depends on whether DTMF or speech grammars are being used, and on which ASR engine is being used (with speech grammars). This example uses an ABNF DTMF form-level grammar with the <initial> tag. It allows the user to enter multiple pieces of information at once (area code and phone number) or to enter a single piece of information (phone number). The collected information is used to fill the appropriate field(s), and then if the area code field is still unfilled, it uses its specific prompt and grammar to elicit the missing piece of information.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <grammar mode="dtmf" type="application/srgs+xml" root="root" version="1.0">
       <rule id="root">
           <one-of>
               <item>
                   7369731 <tag>out.number=7369731';</tag>
               </item>
               <item>
                   4167369731 <tag>out.areacode="416";out.number="7369731";</tag>
               </item>
           </one-of>
       </rule>
    </grammar>
    <initial name="start">
      <prompt> Please enter your phone number. </prompt>
    </initial>
    <field name="field1" slot="areacode">
      <grammar mode="dtmf" type="application/srgs+xml" root="root" version="1.0">
         <rule id="root">
             <one-of>
                 <item>
                     905
                 </item>
                 <item>
                     416
                 </item>
             </one-of>
         </rule>
      </grammar>
      <prompt> Please enter your three-digit area code. </prompt>
    </field>
    <field name="field2" slot="number"/>
    <filled>
      Your phone number is <value expr="field1"/> <value expr="field2"/>.
    </filled>
  </form>
</vxml>

Known Issues and Recommendations

Using the private attribute does not prevent sensitive data from being logged. Therefore, if the VoiceXML application should not log certain data, Genesys recommends that the VoiceXML application use the post method not the get method to submit the data to the web server.


Link

Standard VoiceXML > VoiceXML Tags

<link>

This tag may have one or more grammars. The grammars are in the scope of the tag containing this <link> tag. When the user input matches one of the linked grammars, it activates the <link> to either throw an event, or transition to another document or dialog (a form or menu).

Syntax

<link
   dtmf="Your DTMF sequence"
   event="Your event"
   eventexpr="Your ECMAScript expression"
   expr="Your ECMAScript expression"
   fetchaudio="Your URI"
   fetchhint="safe"
   fetchtimeout="Your time value"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   message="Your message string"
   messageexpr="Your ECMAScript expression"
   next="Your URI"
   gvp:fetchaudiodelay="Your time value"
   gvp:fetchaudiominimum="Your time value">
  child tags
</link>

Attributes

One of next, expr, event, or eventexpr is required. If one of these attributes is not provided, the document containing the tag will generate a parsing error.

Attribute

Description

dtmf

(Optional) This attribute specifies the DTMF sequence for this link. It is equivalent to a simple DTMF grammar. This attribute can be used at the same time as other grammars; the link is activated when user input matches either a link grammar or this DTMF sequence.

expr

This attribute specifies an ECMAScript expression to be evaluated as the URI of the dialog (for example, a form or menu) or document to transition to when the user input matches one of the link grammars.

event

This attribute specifies the name of the event to be thrown when the user input matches one of the link grammars.

The event specified is thrown based on the scope of the active dialog (for example, <field>, or <menu>, and so on. Basically, where the user was when the link grammar was matched.

eventexpr

This attribute specifies an ECMAScript expression to be evaluated as the name of the event to be thrown when the user input matches one of the link grammars.

The event specified is thrown based on the scope of the active dialog (for example, <field>, or <menu>, and so on. Basically, where the user was when the link grammar was matched.

fetchaudio

(Optional) This attribute specifies the URI of audio to play while waiting for the document to be fetched.

This attribute overrides the value of the fetchaudio property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

fetchhint

(Optional) This attribute specifies when the next document should be fetched. The valid value is:

  • Safe—If the value equals safe, the next document will be load when needed.

This attribute overrides the value of the documentfetchhint property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the next document to be fetched before throwing an error.badfetch event. The value of the attribute can be either seconds or milliseconds. For example, fetchtimeout=”6s” or fetchtimeout=”5000ms”.

This attribute overrides the value of the fetchtimeout property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxage

(Optional) This attribute indicates that this document will use a cached copy of the next document only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the documentmaxage property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the next document that has exceeded its expiration time by as much as the number of seconds specified by this attribute..

This attribute overrides the value of the documentmaxstale property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

message

(Optional) This attribute specifies a message string that provides additional context about the event being thrown. The message will be available as a variable within the scope of the <catch> tag.

This attribute can only be used if event or eventexpr is specified.

Only one of the attributes message or messageexpr can be specified.

messageexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as a message string, as documented under message, above.

This attribute can only be used if event or eventexpr is specified.

Only one of the attributes message or messageexpr can be specified.

next

This attribute specifies the URI of the dialog (for example, a form or menu) or document to transition to when the user input matches one of the link grammars.

gvp:fetchaudiodelay

(Optional) This attribute specifies the length of time to wait at the start of the fetch delay before playing fetchaudio. The value of the attribute can be either seconds or milliseconds. For example, gvp:fetchaudiodelay=”6s” or gvp:fetchaudiodelay=”5000ms”.

This attribute overrides the value of the fetchaudiodelay property (for details search the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiominimum

(Optional) This attribute specifies the minimum length of time to play fetchaudio, once started, even if the document arrives in the while it is playing. The value of the attribute can be either seconds or milliseconds. For example, gvp:fetchaudiominimum=”6s” or gvp:fetchaudiominimum=”5000ms”.

This attribute overrides the value of the fetchaudiominimum property (for details search the Properties topic).

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

All attribute values that are ECMAScript expressions are evaluated based on variables from the scope of the active dialog (for example, <field>, or <menu>. Basically, wherever the user was when the link grammar was matched).

Parent

Field, Form, Initial, and Vxml

Child

Grammar

GVP Extensions

  • fetchaudiodelay attribute

  • fetchaudiominimum attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <link event="goodbye" dtmf="*"/>
  <catch event="goodbye">
    Thank you for calling. Goodbye.
    <exit/>
  </catch>
  <form>
    <field name="field1" type="boolean">
      <prompt>Please press the star.</prompt>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

None.


Log

Standard VoiceXML > VoiceXML Tags

<log>

This tag allows the application to generate messages for debugging. It can contain a combination of text and <value> tags, and the resulting message will be the concatenation of the text and string value of <value> tag. The message is logged to one or more files for viewing, as well as to the page that is sent as an e-mail (if applicable). For details, see the Log reference in the VoiceXML 2.0 specification.

Note: A failure to evaluate a <value> inside a <log> will result in an error.semantic event being thrown.

Syntax

<log
    expr="Your ECMAScript expression"
    label="Your label"
    gvp:cond="Your ECMAScript expression"
    gvp:dest="dest1 dest2 ..."
    gvp:level="Your level value">
  text
</log>

Attributes

Attribute

Description

expr

This attribute specifies an ECMAScript expression, the evaluated value will be appended to the <log> tag content and label attribute value.

label

This attribute specifies a string label that will be appended to the <log> tag content before the value of the expr attribute is appended.

gvp:cond

This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. The valid values are:

  • True—the log will be executed.

  • False—the log will not be executed.

The default value is true.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:level

This attribute specifies an integer value that must be less than or equal to the loglevel property value for the log to be executed. The valid values are:

  • 0—the MCP log level is Critical

  • 1—the MCP log level is Error

  • 2—the MCP log level is Warning

  • 3—the MCP log level is Notice

  • 4—the MCP log level is Info

  • 5—the MCP log level is Debug

  • 6—the MCP log level is Interaction

The default value is 1.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

This attribute is ignored if the com. genesyslab.logtoasr property is set to true.

gvp:dest

This attribute specifies a space-separated list of files (<dest1> ..<destN>) to which the message generated by this log should be written. The valid values are:

  • Metrics—the logs are written as interaction level log messages (configured in the Management Framework).

  • Syslog—the logs will be written to the system log file. In a Windows environment, the logs will be written to the Event Viewer.

  • Maintainer—the logs will be written to the maintainer's (administrator's) e-mail address.

  • File (<Your path>/<Your filename>)—the user defined log file will be located in the directory structure relative to the "logs" directory.

  • SNMP—a Simple Network Management Protocol (SNMP) trap is generated.

If dest is an empty string, metrics is assumed.

This value defaults to metrics.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

Text (#PCDATA), and Value

GVP Extensions

  • cond attribute

  • level attribute

  • dest attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="boolean">
      <prompt>Please say yes or no.</prompt>
      <filled>
        You said <value expr="field1"/>.
        <log>The user said <value expr="field1"/>.</log>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The <log> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.

After a call has hung up, information intended to be written to the ScanSoft OSR log using the <log> tag for use with OpenSpeech Insight (OSI) will not be sent to the OSR and thus is not available when using OSI.

All data is logged in UTF-8 format.


Mark

Standard VoiceXML > VoiceXML Tags

<mark>

This tag, new in VoiceXML 2.1, places a marker into the text or tag sequence. An SSML processor must either allow the VoiceXML Interpreter to retrieve information or inform the Interpreter when a <mark> is executed during audio output. The <mark> tag provides a convenient way to detect at which point a user barge-in has occurred.

For details on using <mark> within SSML, click here.

Syntax

<mark
    name="<Your name value>"
    nameexpr="<Your ECMAScript expression>"
/>

Attributes

Attribute

Description

name

(Optional) This attribute specifies the name of this mark. This name is used when appropriate shadow variables are being set as described below.

nameexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the name of the mark, as above.

If this attribute is used, the <vxml> version attribute must equal 2.1. Otherwise, the document containing the tag will generate a parsing error.

If nameexpr cannot be evaluated, an error.semantic event is thrown.

Shadow Variables

The following two properties of the application.lastresult$ object are set when the application.lastresult$ object is assigned and a <mark> has been executed:

  • application.lastresult$.markname—The name of the mark last executed by the SSML processor before barge-in occurred or before the end of audio playback occurred. If no mark was executed, this variable is undefined.

  • application.lastresult$.marktime—The number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or until the end of audio playback occurred. If no mark was executed, this variable is undefined.

When a <mark> is executed during the processing of a form item (for example, <field>, <record>, and so on), the Interpreter also sets itemName$.markname and itemName$.marktime shadow variables for the form item, with the same values used for the lastresult shadow variables above.

Parents

Foreach and Prompt

Child

None.

GVP Extensions

None.

Example

Some versions of RealSpeak may only support numeric mark names (for example, 1234). In that case, the following example would need to be modified. Refer to your speech-synthesis processor documentation for details.

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
  <var name="played_ad" expr="false"/>
  <form>
    <field name="field1" type="boolean">
      <prompt>
        <mark name="ad_start"/>
        Baseball scores brought to you by Elephant Peanuts.
        There's nothing like the taste of fresh roasted peanuts.
        Elephant Peanuts. Ask for them by name.
        <mark name="ad_end"/>
        <break time="500ms"/>
        Would you like to continue?
      </prompt>
      <filled>
        <if cond="typeof(field1$.markname) == 'string' &amp;&amp;
           (field1$.markname=='ad_end' ||
           (field1$.markname=='ad_start' &amp;&amp;
              field1$.marktime &gt;= 5000))">
          <assign name="played_ad" expr="true"/>
        <else/>
          <assign name="played_ad" expr="false"/>
        </if>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

Use of this tag depends on whether the SSML processor (the TTS engine) supports <mark>. That is, when a <mark> is executed during audio output, if the SSML processor neither allows the VoiceXML Interpreter to retrieve the mark information nor informs the Interpreter about the mark, then the Interpreter will not have mark information to store in the markname and marktime variables. Refer to your TTS vendor documentation for support details.

Where possible, the Interpreter will attempt to execute the <mark> tag independently of the SSML processor.


Menu

Standard VoiceXML > VoiceXML Tags

<menu>

This tag is shorthand for a form containing a single anonymous field that prompts the user to make a choice, and which then transitions to different places based on that choice. Menus can rely purely on speech, purely on DTMF, or on both.

Syntax

<menu
    id="Your ID value"
    scope="dialog"|"document"
    accept="exact"|"approximate"
    dtmf="true|False"
    gvp:wakeupword="true|false">
   child tags
</menu>

Attributes

Attribute

Description

id

(Optional) This attribute specifies the name of this menu. If specified, it can be referenced within the same document or from its leaf document. For example, <menu id="hello"> can be referenced by <goto next="#hello"/>.

The id attribute must be set to a valid ECMAScript variable name. Otherwise, an error may be thrown.

Matching this value is case sensitive.

scope

(Optional) This attribute specifies the scope of the menu's grammars. The valid values are:

  • Dialog—the menu's grammars are only active within the menu.

  • Document—the menu's grammars are active throughout the document. If the current page is an application root document, the menu grammars are active throughout the application.

This attribute provides a default value for the scope attribute of the choice grammars, including:

  • Grammars explicitly declared within the <choice> tag.

  • Grammars generated from the words within the <choice> tag.

If any other value is specified, an error.semantic event is thrown when the menu is initialized.

The default value is dialog.

accept

(Optional) This attribute specifies how to generate the default grammar for each <choice> tag. The valid values are:

  • Exact—the text contained in the <choice> tag defines the exact phrase to be recognized.

  • Approximate—the text contained in the <choice> tag defines an approximate recognition phrase. A subset of the words in the phrase expression can be matched. For example, "hello world" can be matched with "hello world," "hello," or "world."

If any other value is specified, an error.semantic event is thrown when the menu is initialized.

The default value is exact.

dtmf

(Optional) This attribute enables DTMF input for all menu choices. The valid values are:

  • True—the Interpreter assigns DTMF sequence 1, 2, 3... to the first nine choices in document order for menu choices that do not explicitly define a DTMF sequence. If there are choices which have specified their own DTMF sequences to be something other than *, #, or 0, a parse error will occur.

  • False—the Interpreter does not implicitly assign DTMF sequences.

If any other value is specified, an error.semantic event is thrown when the menu is initialized.

The default value is false.

gvp:wakeupword

(Optional) This attribute specifies whether or not Wakeup Word Spotting should be used for input in this menu. The valid values are:

  • True—Wakeup Word Spotting is used for input.

  • False—Wakeup Word Spotting is not used for input.

This attribute overrides the value of the com.genesyslab.wakeupword property, and is only supported with SpeechWorks OSR.

The default value is false.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Vxml

Child

Audio, Catch, Choice, Data, Enumerate, Error, Help, Noinput, Nomatch, Prompt, Property,
Text (#PCDATA), and Value

GVP Extensions

  • wakeupword attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <menu>
    <prompt> What do you want to drink, coffee or tea? </prompt>
    <choice next="#getcoffee"> coffee </choice>
    <choice next="#gettea"> tea </choice>
  </menu>
  <form id="getcoffee">
    <block>
      Ok, here's your coffee.
    </block>
  </form>
  <form id="gettea">
    <block>
      Ok, here's your tea.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The document containing the tag will generate a parsing error if a VoiceXML page contains two <menu> tags with the same id attribute.


Meta

Standard VoiceXML > VoiceXML Tags

<meta>

This tag specifies general information about the VoiceXML document rather than the document's content. The <meta> tag can specify a property of the document as a whole, or it can specify HTTP response headers.

Note: A <meta> tag exists for SSML content (see the SSML <meta>) and for grammars.

Syntax

<meta
    name="seeAlso"|"<Your name value>"
    http-equiv="<Your http-equivalent content>"
    content="<Your content>"
/>

Attributes

Either name or http-equiv is required. Otherwise, the document containing the tag will generate a parsing error.

Attribute | Description
name | This attribute specifies the name of the meta information represented by the tag.
content | This attribute specifies the content of the meta information. If the tag does not have the content attribute, the document containing the tag generates a parse error.
http-equiv | This attribute specifies the name of the HTTP response header. The content attribute represents the value of the header.

Properties

Name

Description

callrequest

If this property is set to decline in the first page being fetched when a call is made, the call will not be answered. Otherwise, the call will be answered. If this property is set in any subsequent pages fetched during the call, it will have no effect.

This property can also be used to support call redirection. For example, <meta name="callrequest" content="redirect;sip:dialog@127.0.0.2"/>

If you are calling into a developer platform with an extension, setting this property to decline in the first page of the associated application will have no effect, since a VoiceXML page that collects the extension input is always fetched first.

maintainer

This property defines the e-mail address that log files will be sent to (if applicable). E-mails are sent only when a session ends. When GVP is shut down, all unsent maintainer e-mails will be discarded. If the VoiceXML document contains multiple <meta> tags with name="maintainer", the content of the first tag will be used; subsequent tags will be ignored.

The maintainer content can be a space-separated list of recipients. For example:
<meta name="maintainer"
content="email1@yourserver.com
email2@yourserver.com
email3@yourserver.com"
/>
This tag points to a single e-mail. The recipients will be specified in the To: header of the e-mail.

Parents

Vxml and Grammar

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <meta name="maintainer" content="yourname@yourserver.com"/>
  <property name="loglevel" value="3"/>
  <form>
    <block>
      <prompt>
        <!-- If you set the maintainer to your email address -->
        <!-- You should get email because log cannot be used within prompt -->
        <log> INVALID LOG </log>
        Hello, world!
      </prompt>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Noinput

Standard VoiceXML > VoiceXML Tags

<noinput>

This tag catches a noinput event, which is thrown by the VoiceXML application or by the platform when, during an input context, the user fails to input any data after a specified time-out duration. The <noinput> tag associates a noinput handler with a document, dialog (form or menu), or form item. It contains executable content. It is a shorthand notation for <catch event="noinput">.

Syntax

<noinput
   count="Your count value"
   cond="Your ECMAScript expression">
  child tags
</noinput>

Attributes

Attribute | Description
count | (Optional) This attribute allows you to handle different occurrences of the noinput event differently. Each form, menu, and form item maintains a counter for the noinput event while it is being visited; these counters are reset each time the menu or form item's form is re-entered. When more than one <noinput> tag catches a noinput event, the tag in the closest scope with the highest count that is less than or equal to the current counter will be selected. The default value is 1.
cond | This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This <noinput> tag will only catch the noinput event if the expression evaluates to true. The default value is true.

Anonymous Variables

  • _event—Contains the name of the event that was thrown (for example, noinput).

  • _message—Contains the message string from the corresponding <throw>, <choice>, <link>, or <return> tag, or a platform defined value for noinput events thrown by the platform. If no message is specified, the value of this variable is ECMAScript undefined.

  • _url—Contains the url of the page where the error occurred.

  • _element—Contains the name of the element that generated the event.

  • _line—Contains the line number of the start of the element that generated the event.

Parent

Field, Form, Initial, Menu, Object, Record, Subdialog, Transfer, and Vxml

Child

Assign, Audio, Clear, Data, Disconnect, Enumerate, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Throw,
Text (#PCDATA), Value, and Var

GVP Extensions

  • _url variable

  • _element variable

  • _line variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <property name="timeout" value="3s"/>
  <form>
    <field name="field1" type="boolean">
      <prompt> Don't say anything. </prompt>
      <noinput>
        You were quiet for 3 seconds.
        <exit/>
      </noinput>
      <filled>
        You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

None.


Nomatch

Standard VoiceXML > VoiceXML Tags

<nomatch>

This tag catches a nomatch event, which is thrown by the VoiceXML application or by the platform when, during an input context, the user inputs data that does not match any entry in the grammar (or grammars). The <nomatch> tag associates a nomatch handler with a document, dialog (form or menu), or form item. It contains executable content. It is a shorthand notation for <catch event="nomatch">.

Syntax

<nomatch
    count="Your count value"
    cond="Your ECMAScript expression">
   child tags
</nomatch>

Attributes

Attribute | Description
count | (Optional) This attribute allows you to handle different occurrences of the nomatch event differently. Each form, menu, and form item maintains a counter for the nomatch event while it is being visited. These counters are reset each time the menu or form item's form is re-entered. When more than one <nomatch> tag catches a nomatch event, the tag in the closest scope with the highest count that is less than or equal to the current counter will be selected. The default value is 1.
cond | (Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This <nomatch> tag will only catch the nomatch event if the expression evaluates to true. The default value is true.

Anonymous Variables

  • _event—Contains the name of the event that was thrown (for example, nomatch).

  • _message—Contains the message string from the corresponding <throw>, <choice>, <link>, or <return> tag, or a platform defined value for nomatch events thrown by the platform. If no message is specified, the value of this variable is ECMAScript undefined.

  • _element—Contains the name of the element that generated the event.

  • _line—Contains the line number of the start of the element that generated the event.

  • _url—Contains the url of the page where the error occurred.

Parent

Field, Form, Initial, Menu, Object, Record, Subdialog, Transfer, and Vxml

Child

Assign, Audio, Clear, Data, Disconnect, Enumerate, Exit, Foreach, Goto, If, Log, Prompt, Reprompt, Return, Script, Submit, Text (#PCDATA), Throw, Value, and Var

GVP Extensions

  • _element variable

  • _line variable

  • _url variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1">
      <dtmf> 1 </dtmf>
      <prompt> Please press 4. </prompt>
      <nomatch>
        I don't recognize that key.
        <exit/>
      </nomatch>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

None.


Object

Standard VoiceXML > VoiceXML Tags

<object>

This tag allows interaction with a custom extension. A VoiceXML platform may have platform-specific functionality that an application wants to use, such as speaker verification, native components, additional telephony, and so on. Such platform-specific objects are accessed using the <object> tag, which is analogous to the HTML <object> tag.

Syntax

<object
   archive="Your URI"
   classid="Your URI"
   codebase="Your URI"
   codetype="Your code type value"
   cond="Your ECMAScript expression"
   data="Your URI"
   expr="Your ECMAScript expression"
   fetchhint="prefetch"|"safe"
   fetchtimeout="Your timeout interval"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   name="Your name value"
   type="Your type value">
  child tags
</object>

Attributes

Attribute

Description

archive

(Optional) This attribute specifies a space-separated list of URIs for archives containing resources relevant to the object, which may include the resources specified by the classid and data attributes. URIs which are relative are interpreted relative to the codebase attribute.

classid

(Optional) This attribute specifies the URI for the location of the object's implementation.

codebase

(Optional) This attribute specifies the base path used to resolve relative URIs specified by classid, data, and archive.

The default value is the base URI of the current document.

codetype

(Optional) This attribute specifies the content type of the data expected when downloading the object specified by the classid.

The default value is the value of the type attribute.

cond

(Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This object will be visited only if the expression evaluates to true.

The default value is true.

data

(Optional) This attribute specifies the URI for the location of the object's data. If it is a relative URI, it is interpreted relative to the codebase attribute.

expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the initial value of this object. This object will be visited only if the expression evaluates to undefined.

The default value is undefined.

fetchhint

(Optional) This attribute defines when the object should be fetched. The valid values are:

  • Prefetch—the object may be downloaded when the page is loaded.

  • Safe—the object is only loaded when it is needed.

This attribute overrides the value of the objectfetchhint property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the object to be fetched before throwing an error.badfetch event.

This attribute overrides the value of the fetchtimeout property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxage

(Optional) This attribute indicates that this document will use a cached copy of the object if the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the objectmaxage property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the object that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute overrides the value of the objectmaxstale property (for details see the W3C Voice Extensible Markup Language 2.0 specification).

name

(Optional) This attribute specifies the name of this object. This variable can be referenced anywhere within the object's form.

The default value is an inaccessible internal variable.

type

(Optional) This attribute specifies the content type of the data specified by the data attribute.

Parent

Form

Child

Audio, Catch, Error, Filled, Help, Noinput, Nomatch, Param, Prompt, Property, Text (#PCDATA), and Value

GVP Extensions

None.

Known Issues and Recommendations

No GVP-specific objects are currently defined; therefore, any use of the <object> tag will result in an error.unsupported.object being thrown.


Option

Standard VoiceXML > VoiceXML Tags

<option>

This tag specifies an option in a <field>. It is a convenient way to specify a list of choices in a field without specifying a grammar. The grammar is generated automatically from the text contained in each <option> and the optionally specified DTMF sequence in each <option>.

Syntax

<option
   accept="exact"|"approximate"
   dtmf="Your DTMF sequence"
   value="Your value">
   text
</option>

Attributes

Attribute

Description

accept

(Optional) This attribute specifies how to generate the grammar for this <option> tag. The valid values are:

  • Exact—the text contained in the <option> tag defines the exact phrase to be recognized.

  • Approximate—the text contained in the <option> tag defines an approximate recognition phrase. A subset of the words in the phrase can be matched. For example, "hello world" can be matched with "hello world," "hello," or "world."

The default value is exact.

dtmf

(Optional) This attribute specifies the DTMF sequence required to select an option.

value

(Optional) This attribute specifies the string to assign to the field variable when this option is selected, either by speech or DTMF.

If this attribute is not specified, the default assignment is the CDATA content of the tag with leading and trailing white space removed. If this does not exist, then the DTMF sequence is used instead. If neither CDATA content nor a dtmf sequence is specified, then the default assignment is undefined and the field's form item variable is not filled.

Parent

Field

Child

Text (#PCDATA)

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="maincourse">
      <prompt>
        Please select either sword fish or roast beef.
      </prompt>
      <option dtmf="1"> sword fish </option>
      <option dtmf="2"> roast beef </option>
      <filled>
        Very good.
        I'll bring out your <value expr="maincourse"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The generated grammar is of the form application/srgs+xml. It is necessary to ensure that the ASR server being used supports this type of grammar.


Param

Standard VoiceXML > VoiceXML Tags

<param>

This tag specifies values that are passed into the <object> or <subdialog> tag. When <param> is contained in a <subdialog> tag, the values specified are used to initialize <var> declarations in the subdialog that is invoked. The initialization takes precedence over the expr attribute in <var>.

Note: The values passed into a <subdialog> (using <param>) can be strings or any ECMAScript values (for example, numbers, pointers, objects, arrays, and so on).

Syntax

<param
   name="Your name value"
   type="Your MIME type"
   expr="Your ECMAScript expression"
   value="Your value"
   valuetype="data"|"ref"
/>

Attributes

Either value or expr is required. If one of these attributes is not provided, the document containing the tag will generate a parsing error.

Attribute

Description

expr

This attribute specifies an ECMAScript expression to be evaluated as the parameter value.

name

This attribute specifies the name associated with the parameter.

type

(Optional) This attribute specifies the media type of the result provided by a URI if valuetype="ref".

This attribute is only relevant for uses of <param> in the <object> tag (for example, it is not used with <subdialog> tag.

value

This attribute specifies the string value of the parameter.

valuetype

(Optional) This attribute indicates the type of the value. The valid values are:

  • data—the value is actual data.

  • ref—the value is referenced by a URI.

This attribute is only relevant for uses of <param> in the <object> tag (for example, it is not used with the <subdialog> tag.

The default value is data.

Parent

Object and Subdialog

Child

None.

GVP Extensions

None.

Example

The following document calls the subdialog:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <subdialog name="result" src="subdialog.vxml">
      <param name="birthday" expr="'2000-02-10'"/>
      <param name="age" value="100"/>
    </subdialog>
  </form>
</vxml>

The following document contains the subdialog:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form id="getdriverslicense">
    <var name="birthday"/>
    <var name="age"/>
    <block>
      Hello, your birthday is <value expr="birthday"/>
      and you are <value expr="age"/> years old.
      <return/>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Prompt

Standard VoiceXML > VoiceXML Tags

<prompt>

This tag plays text-to-speech (TTS) to the user.

Prompts containing Speech Markup (SSML) will be passed into the TTS engine as an XML document. When the VoiceXML page is first parsed by the Interpreter, the prompts will be decoded. The Interpreter will then re-encode the prompt content into an XML document to pass to the TTS engine.

Syntax

<prompt
   bargein="true"|"false"
   bargeintype="speech"|"hotword"
   cond="Your ECMAScript expression"
   count="Your count integer value"
   timeout="Your timeout interval"
   xml:base="Your base URI"
   xml:lang="Your language code"
   gvp:langexpr="Your language expression"
   gvp:ttsengine="Your ttsengine value">
   child tags
</prompt>

Attributes

Attribute

Description

bargein

(Optional) This attribute controls whether user input can be collected before the prompt has finished playing. The valid values are:

  • true—any user input can barge in during the current prompt.

  • false—no user input can barge in during the current prompt.

If an invalid value is given, the platform throws an error.semantic event.

Each prompt fragment sent to the platform must have its own barge in value.

This attribute overrides the value of the bargein property.

The default value is true.

bargeintype

(Not supported) This attribute is ignored by the VoiceXML Interpreter. See the Known Issues and Limitations section.

cond

(Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This <prompt> will only be played if the expression evaluates to true.

The default value is true.

count

(Optional) Each field item maintains a counter of the number of times the item has been visited. The count attribute allows the application to play different prompts based on the counter. The prompt will be played when the counter reaches the count attribute.

The default value is 1.

timeout

(Optional) This attribute specifies the length of time to wait, if no speech occurs, before throwing a noinput event. This attribute overrides the value of the timeout property.

The default value is 10s.

xml:base

(Optional) This attribute declares the base URI from which relative URIs in the prompt are resolved. This base declaration has precedence over the <vxml> base URI declaration. If a local declaration is omitted, the value is inherited down the document hierarchy.

This attribute defaults to the xml:base attribute of the enclosing tags. It is used to resolve the relative references within the prompt (for example, in the <audio> and <lexicon> tags) when the prompt information is generated.

xml:lang

(Optional) This attribute specifies the language identifier of the prompt. If omitted, it defaults to the value specified in the <vxml> xml:lang attribute.

The list of supported values for this attribute depends on the TTS engine being used. The ttsengine property must always be used to specify the TTS language. With some vendors, the xml:lang is only required additionally when prompts contain SSML; with other vendors, the xml:lang must always match the TTS engine language. Refer to your TTS vendor documentation for support details.

Only one of xml:lang or gvp:langexpr or the page will fail to validate.

gvp:langexpr

(Optional) This attribute specifies the language identifier of the prompt.

Only one of xml:lang or gvp:langexpr, or the page will fail to validate.

This attribute will be evaluated when the prompt is queued, and it’s value will be used the same way that xml:lang is used.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:ttsengine

(Optional) This attribute specifies the name of the TTS (Text-to-Speech) engine to use (for example, the voice) when playing a prompt.

If this attribute is populated, it defines which TTS engine will be used. If this attribute is not populated (is an empty string—the default), the per call configuration value specified in the vxmli.tts.defaultengine option (see, the Genesys Voice Platform 8.1 Configuration Options Reference) defines which TTS engine will be used. The default value for vxmli.tts.defaultengine is default.

This attribute overrides the value of the ttsengine property.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Block, Catch, Error, Field, Filled, Foreach, Help, If, Initial, Menu, Noinput, Nomatch, Object, Record, Subdialog, and Transfer

Child

Audio, Enumerate, Foreach, Mark, Text (#PCDATA), and Value

GVP Extensions

  • langexpr attribute

  • ttsengine attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      <prompt> Hello, world! </prompt>
    </block>
  </form>
</vxml>

Known Issues and Recommendations

Due to a VoiceXML limitation, the bargeintype attribute is not supported.

To enable hotword:

  • Set the vrm.client.disablehotword option to false, in the Media Resource Control Protocol (MRCP) TTS Server configuration.

  • Specify <property name="bargeintype" value="hotword"/>, in the VoiceXML application.

When the Interpreter has completed execution with prompts remaining in the prompt queue, the prompt queue is flushed, and played before exiting. Any TTS errors encountered while the prompt queue is being flushed are ignored.


Property

Standard VoiceXML > VoiceXML Tags

<property>

This tag controls platform settings. Properties are used to set values that affect platform behavior, such as the recognition process, timeouts, caching policy, and so on. Refer to the Properties reference for a list of properties.

Syntax

<property
   name="Your name value"
   value="Your value"
   gvp:expr="Your ECMAScript expression"
/>

Attributes

Either expr or value is required; otherwise, an error.badfetch will be thrown.

Attribute | Description
name | This attribute sets the property name.
value | This attribute sets the string value of the property.
gvp:expr | This attribute may contain an ECMAScript expression that evaluates to a valid value attribute. If the expr evaluates to a value that would be illegal for the specified property (for example, timeout of foo), then an error.semantic is thrown. This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Field, Form, Initial, Menu, Object, Record, Subdialog, Transfer, and Vxml

Child

None.

GVP Extensions

  • See Properties for a list of GVP properties.

  • expr attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <property name="metricslevel" value="3"/>
  <form>
    <block>
      Hello, world!
    </block>
  </form>
</vxml>

Known Issues and Recommendations

Using the private attribute does not prevent sensitive data from being logged. If the VoiceXML application should not log certain data, Genesys recommends that the VoiceXML application use the post method (not the get method) to submit the data to the web server.


Receive

Standard VoiceXML > VoiceXML Tags

<receive>

This tag supports the receipt of external messages by a voice application. The application developer chooses to receive external messages synchronously or asynchronously.

Notes:

If messaging.enabled equals false, executing a <receive> will result in error.unsupported.receive being thrown.

If an error occurs, the application module returns error.badfetch.<error_reason> (the error_reason should have the format sip.<status_code>).

Syntax

<receive
   fetchaudio="Your audio URI"
   fetchaudioexpr="Your ECMAScript expression"
   maxtime="Your maxtime value"
   maxtimeexpr="Your ECMAScript expression">
   child tags
</receive>

Attributes

Attribute

Description

fetchaudio

This attribute specifies the URI of the audio to play while waiting for a document to be fetched. The default is to play no audio during fetch delays.

Only one of fetchaudio or fetchaudioexpr can be specified or the document containing the tag will generate a parsing error.

fetchaudioexpr

This attribute specifies an ECMAScript expression evaluating to the fetchaudio URI.

Only one of fetchaudio or fetchaudioexpr can be specified or the document containing the tag will generate a parsing error.

If evaluation of the expression fails, the Interpreter throws error.semantic.

maxtime

This attribute specifies the maximum amount of time the Interpreter will wait to receive an external message.

If maxtime elapses, then an error.badfetch must be thrown.

Only one of maxtime or maxtimeexpr can be specified or document containing the tag will generate a parsing error.

If the timeout is exceeded, the Interpreter throws an error.badfetch.

A value of none indicates that the Interpreter blocks indefinitely.

The default value is 0s.

maxtimeexpr

An ECMAScript expression evaluating to the maxtime value.

If the maxtimeexpr attribute evaluates to none, then no timer should be used (it may block indefinitely).

If evaluation of the expression fails, the Interpreter throws an error.semantic.

Only one of maxtime or maxtimeexpr can be specified or document containing the tag will generate a parsing error.

The default value is 0s.

When present, the attributes fetchaudioexpr and maxtimeexpr are evaluated when the <receive> tag is executed.

Shadow Variables

The <receive> tag processes external messages by populating the application.lastmessage$ ECMAScript object shadow variable as follows:

Variable | Description
content | This contains the message, or is set to ECMAScript undefined if no content is available.
contenttype | This contains the media type of the external message.
event | This contains the event name, or is set to ECMAScript undefined if no event name is available.
source | This is sip.
sourcetype | This is the From header of the sip info message (containing the external message).

The application.lastmessage$ variable is ECMAScript undefined at the start of the application. It is replaced whenever the <receive> tag processes a new external event message or whenever an external event is thrown as a VoiceXML event. For example:

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml"
xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
<form id="test1">
<property name="com.genesyslab.externalevents.enable" value="false"/>
<property name="com.genesyslab.externalevents.queue" value="true"/>
<block>
<log>
receiving message
</log>
<receive maxtime="10000ms"/>
<log>
x-header1:<value expr='application.lastmessage$.headers["xheader1"]'/>
</log>
</block>
<catch event="error.semantic">
<log>
<value expr="_event"/>
</log>
</catch>
</form>
</vxml>

Parent

Block, Catch, Error, Filled, Foreach, Form, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

  • content shadow variable

  • contenttype shadow variable

  • event shadow variable

  • source shadow variable

  • sourcetype shadow variable

Example

The following example demonstrates receiving an external message synchronously. In this example, the Interpreter blocks for up to 15 seconds waiting for an external message to arrive. If no external message is received during that interval, the Interpreter throws an error.badfetch. If a message is received, the Interpreter proceeds by executing the <log> tag.

<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml"
xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
<property name="externalevents.queue" value="true"/>
<form>
<catch event="error.badfetch">
<log>
timed out waiting for external message
</log>
</catch>
<block>
Hold on ...
<receive maxtime="15s"
fetchaudio="http://www.example.com/audio/fetching.wav"
/>
<log>
got <value expr="application.lastmessage$.content"/>
</log>
</block>
</form>
</vxml>

Known Issues and Recommendations

None.


Record

Standard VoiceXML > VoiceXML Tags

<record>

This tag collects a recording from the user. A reference to the recorded audio is stored in the form item variable, which can be played back or submitted to a server. The <record> tag can be used similarly to record a video file.

Syntax

<record
   beep="true"|"false"
   cond="Your ECMAScript expression"
   dtmfterm="true"|"false"
   expr="Your ECMAScript expression"
   finalsilence="Your finalsilence value"
   maxtime="Your maxtime interval value"
   modal="true"|"false"
   name="Your name value"
   type="Your MIME type"
   gvp:dest="Your URI"
   gvp:destexpr="Your ECMAScript expression"
   gvp:filename="Your filename location"
   gvp:filenameexpr="Your ECMAScript expression"
   gvp:mintime="Your mintime interval value"
   gvp:private="true|false"
   gvp:timeout="Your timeout value">
   child tags
</record>

Attributes

Attribute

Description

beep

(Optional) This attribute specifies whether a beep should be emitted immediately prior to recording. The valid values are:

  • True—the last fragment of the prompt queue sent to the platform for this <field> must be of type "endbeep"

  • False—a beep will not be played

If neither true nor false is used, an error.semantic is generated when the <record> tag is visited.

The beep is treated as any <audio> tag.

This defaults to the GVP extension com.genesyslab.endbeep property. If the property is not found, the default value is false.

To access the audio file, the location is specified by the record.start.beep.filename parameter in the Media Control Platform (MCP).

cond

(Optional) This attribute is an ECMAScript expression to be evaluated as the initial value of this record. This record will be visited only if the expression evaluates to undefined.

The default value is undefined.

dtmfterm

(Optional) This attribute specifies that any DTMF keypress not matched by an active grammar will be treated as a match of an active (anonymous) local DTMF grammar. The valid values are:

  • True— the Interpreter adds the grammar builtin:dtmf/digits?minlength=1;maxlength=1 to the set of DTMF grammars used for terminating a record, where this grammar has the highest precedence among all DTMF grammars

  • False—unmatched DTMF is ignored

Setting this attribute to true is equivalent to defining a grammar with the highest precedence among all DTMF grammars that matches any single DTMF key (to terminate recording). The DTMF tone will not be part of the recording.

The default value is true.

expr

(Optional) This attribute is an ECMAScript expression to be evaluated as the initial value of this record. This record will be visited only if the expression evaluates to undefined.

The default value is undefined.

finalsilence

(Optional) This attribute is the interval of silence that indicates end of speech, and is passed to the platform as part of the record request. The maximum value is the value of the maxtime attribute.

The default value is 4s.

maxtime

(Optional) This attribute is the maximum duration of the recording, and is passed to the platform as part of the record request. The valid range of values is:

  • The minimum value is 250ms. If the minimum value is set to a shorter duration, it will default to 250ms.

  • The maximum value is whatever the default is. If this value is set to a longer duration, it will be set to the default.

The default value is 600000ms (10 minutes) or the value of the com.genesyslab.maxrecordtime property.

modal

(Optional) This attribute specifies whether the non-local (grammars not defined as a child of the <record> tag) speech and DTMF grammars are active or not active while making the recording. The valid values are:

  • True—all non-local speech and DTMF grammars are not active while making the recording

  • False—non-local speech and DTMF grammars are active while making the recording

The default value is true.

name

(Optional) This attribute is the name of variable (private object) that holds the result of the record and can be referenced anywhere within the form of the record.

The variable can be:

  • Referenced as <audio expr="Your name value"/>; the recorded audio will be played back.

  • Used to submit audio data.

An error event may be thrown if a reserved ECMAScript word is used as the name.

type

(Optional) This attribute is the media format of the resulting recording. It is passed as a character string as part of the record request. The Interpreter does not validate this parameter.

  • If the platform does not support the media format, the platform returns an error code indicating an unsupported media format, and the Interpreter throws an error.semantic event.

  • If this parameter is not set, the Interpreter passes an empty string to the platform so that the platform can use a platform-specified default value.

The default value is audio/basic (see the Type Chart, below).

gvp:dest

(Optional) This attribute specifies the destination of the recording, relative to the directory that is configured for recordings (relative to the basepath). The destination is passed as a character string as part of the record request. If the platform determines that the recording destination is invalid, the platform returns an error code indicating an invalid destination, and the Interpreter throws an error.semantic event and sets the _event shadow variable to the event name. A more specific error message will be set to the _message shadow variable. If the destination string contains "../" or "..\" it is considered invalid.

At most, one of the dest, destexpr, filename, or filenameexpr attributes may be specified. If more than one is specified, a parse error is thrown. If dest or destexpr is specified, the filename of the recording is assigned by the platform. If none of dest, destexpr, filename, or filenameexpr is specified, the directory of the recording is the value of the GVP parameter vxmli.directories_savetempfiles, and the filename of the recording is assigned by the platform.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:destexpr

(Optional) This attribute contains an ECMAScript expression to be evaluated as the destination of the recording (relative to the basepath). The destination is passed as a character string as part of the record request. If the platform determines that the recording destination is invalid, the platform returns an error code indicating an invalid destination, and the Interpreter throws an error.semantic event and sets the _event shadow variable to the event name. A more specific error message will be set to the _message shadow variable. If the destination string contains "../" or "..\" it is considered invalid.

The provided destination is relative to the directory configured for recordings.

At most, one of the dest, destexpr, filename, or filenameexpr attributes may be specified. If more than one is specified, a parse error is thrown. If dest or destexpr is specified, the filename of the recording is assigned by the platform. If none of dest, destexpr, filename, or filenameexpr is specified, the directory of the recording is the value of the GVP parameter vxmli.directories_savetempfiles, and the filename of the recording is assigned by the platform.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:filename

(Optional) This attribute specifies the location, including the filename, to store the recording (relative to the basepath). If the platform determines that the recording destination is invalid, the platform returns an error code indicating an invalid destination, and the Interpreter throws an error.semantic event and sets the _event shadow variable to the event name. A more specific error message will be set to the _message shadow variable. If the destination string contains "../" or "..\" it is considered invalid.

At most, one of the dest, destexpr, filename, or filenameexpr attributes may be specified. If more than one is specified, a parse error is thrown. If none of dest, destexpr, filename, or filenameexpr is specified, the directory of the recording is the value of the GVP parameter vxmli.directories_savetempfiles, and the filename of the recording is assigned by the platform.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:filenameexpr

(Optional) This attribute contains an ECMAScript expression evaluating to the location (including the filename) to store the recordings (relative to the basepath). If the platform determines that the recording destination is invalid, the platform returns an error code indicating an invalid destination, and the Interpreter throws an error.semantic event and sets the _event shadow variable to the event name. A more specific error message will be set to the _message shadow variable. If the destination string contains "../" or "..\" it is considered invalid.

At most, one of the dest, destexpr, filename, or filenameexpr attributes may be specified. If more than one is specified, a parse error is thrown. If none of dest, destexpr, filename, or filenameexpr is specified, the directory of the recording is the value of the GVP parameter vxmli.directories_savetempfiles, and the filename of the recording is assigned by the platform.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:mintime

(Optional) This attribute defines the minimum amount of speech for a valid recording, and the value is passed to the platform as part of the record request.

  • If a recording is terminated (either by a DTMF match or by the endsilence) with too little speech, the record form item variable remains unfilled and a noinput.mintime event is thrown in the scope of the <record> tag.

The valid range of values is:

  • The minimum value is 250ms. If this value is defined as a shorter duration, it will be reset to 250ms.

  • The maximum value is the value of the maxtime attribute. If defined as a longer duration, it will be set to 250ms.

The default value is 250ms.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:private

(Optional) This attribute enables data masking for logged metrics (interaction-level messages that described call flow). This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:

  • True—data masking is enabled. The data that is masked includes:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • False—data masking is not enabled (no data is masked).

The default value is false. If an invalid value is used, the page will be rejected.

This attribute takes precedence over com.genesyslab.private.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:timeout

(Optional) This attribute is the time to wait for speech. If no speech occurs within the set time, a noinput event is thrown. The valid range of values:

  • The minimum value is 0ms.

  • The maximum value is the value of the maxtime attribute.

The default is set to the timeout value of the last prompt (if specified), otherwise the timeout property is used.

This attribute can be enabled/disabled by the property com.<vendor_name>.record.enabletimeout. When this property is set to false, begin silence detection will be disabled. This property is true by default.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Type Chart

This section provides the audio type chart. The supported recording formats are:

Type

Recorded File Format/Sample Size/Encoding

File Extension

audio/x-vox
audio/vox

  • Raw audio

  • 8-bit mono

  • u-law, a-law (depends on platform configuration)

.vox

audio/basic
audio/pcmu
audio/mulaw

  • Raw audio

  • 8-bit mono

  • u-law

.ulaw

audio/x-alaw-basic
audio/pcma
audio/alaw

  • Raw audio

  • 8-bit mono

  • a-law

.alaw

audio/x-g726-24

  • Raw audio

  • 24kbit/sec

  • ADPCM (g726)

.adpcm24

audio/x-g726
audio/g726-32
audio/x-g726-32
audio/g726
audio/x-adpcm
audio/adpcm
audio/x-adpcm8

  • Raw audio

  • 32kbit/sec

  • ADPCM (g726)

.adpcm

audio/x-g726-40

  • Raw audio

  • 40kbit/sec

  • ADPCM (g726)

.adpcm40

audio/L8

  • Raw audio

  • 8-bit unsigned mono

  • Linear PCM

.pcm8

audio/L16

  • Raw audio

  • 16-bit signed mono

  • Linear PCM

.pcm16

audio/x-wav
audio/wav

  • Audio with .wav header

  • 8-bit mono

  • u-law, a-law (depends on platform configuration)

.wav

audio/x-wav;codec=ulaw
audio/wav;codec=ulaw

  • Audio with .wav header

  • 8-bit mono

  • u-law

.wav

audio/x-wav;codec=alaw
audio/wav;codec=alaw

  • Audio with .wav header

  • 8-bit mono

  • a-law

.wav

audio/x-wav;codec=pcm
audio/wav;codec=pcm

  • Audio with .wav header

  • 8-bit unsigned mono

  • PCM

.wav

audio/x-wav;codec=pcm16
audio/wav;codec=pcm16

  • Audio with .wav header

  • 16-bit signed mono

  • PCM

.wav

audio/x-wav;codec=g726
audio/wav;codec=g726

  • Audio with .wav header

  • 32kbit/sec

  • ADPCM (g726)

.wav

audio/x-wav;codec=g726;rate=<rate>
audio/wav;codec=g726;rate=<rate>

  • Audio with .wav header

  • <rate> = 16kbps, 24kbps, 32kbps, or 40kbps

  • ADPCM of corresponding <rate> (g726)

.wav

audio/x-wav;codec=g729
audio/wav;codec=g729

  • Audio with .wav header

  • g729

.wav

audio/x-wav;codec=AMR
audio/wav;codec=AMR

  • Audio with .wav header

  • Variable rate

  • AMR

.wav

audio/x-wav;codec=AMR-WB
audio/wav;codec=AMR-WB

  • Audio with .wav header

  • Variable rate

  • AMR-WB (g722.2)

.wav

audio/x-g729

  • Raw audio

  • g729

.g729

audio/AMR

  • Raw audio

  • AMR

.amr

audio/AMR-WB

  • Raw audio

  • AMR-WB (g722.2)

.awb

video/h263

  • Raw video

  • h263

.263

video/h264

  • Raw video

  • h264

.264

video/avi[;codec=<audio_codec>;
rate=<g726_encoding_rate>;
videocodec=<video_codec>]

  • Audio/video stored in .avi container

  • Audio: u-law, a-law, PCM, ADPCM, G.726, G.722, G.729, AMR-WB (depends on file header information)

  • Video: h263

.avi

video/3gpp[;codec=<audio_codec>; videocodec=<video_codec>]

  • Audio/video stored in .3gp(p) container

  • Audio: AMR, AMR-WB (G.722.2) (depends on file header information)

  • Video: h263/h264

.3gp(p)

Notes:

  • AU and NIST file recording are not currently supported.

  • Only the 8000 Hz audio sampling rate is supported, except for AMR-WB and G722 which are 16000 Hz.

  • Only g726 ADPCM audio files are supported. Currently, the platform supports 24, 32, and 40 kbit/sec. 16 kbit/sec g726 will be supported in the future.

  • The preceding audio types are also supported for full-call recording.

Shadow Variables

For each <record> tag with the name attribute set to <Your name value>, there is a shadow variable
<Your name value>$ (in the same scope as the record name variable) containing the following properties:

Property | Description
<Your name value>$.duration | This property contains the duration of the recording in milliseconds.
<Your name value>$.markname | This property, new to VoiceXML 2.1, contains the name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. This is only meaningful when the <record> tags prompts contain at least one <mark>.
<Your name value>$.marktime | This property, new to VoiceXML 2.1, contains the number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. This is only meaningful when the <record> tags prompts contain <mark>s.
<Your name value>$.maxtime | Set to true if the recording was terminated because the maxtime duration was reached.
<Your name value>$.size | This property contains the size of the recording in bytes.
<Your name value>$.termchar | If the dtmfterm attribute is true, and the user terminates the recording by pressing a DTMF key, then this shadow variable is the key pressed (for example, #). Otherwise it is ECMAScript undefined.
<Your name value>$.dest | This property contains the location of the recording. This attribute is a GVP extension.
<Your name value>$.filetype | This property contains the media format of the recorded audio file. This attribute is a GVP extension.

When any shadow variable is not set, its value will be ECMAScript undefined.

Parent

Form

Child

Audio, Catch, Error, Filled, Grammar, Help, Noinput, Nomatch, Prompt, Property, Text #PCDATA and Value

GVP Extensions

  • dest attribute

  • destexpr attribute

  • filename attribute

  • filenameexpr attribute

  • mintime attribute

  • private attribute

  • timeout attribute

  • dest shadow variable

  • filetype shadow variable

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <record name="message" beep="true" maxtime="10s">
      <prompt>
        At the tone, please record your message.
      </prompt>
      <filled>
        You recorded <audio src="<Your URI>"/>.
      </filled>
    </record>
  </form>
</vxml>

Known Issues and Recommendations

Using the private attribute does not prevent sensitive data from being logged. If the VoiceXML application should not log certain data, Genesys recommends that the VoiceXML application use the post method to submit the data to the web server.

When recording very short phrases, it may be necessary to set the gvp:timeout and finalsilence attributes to avoid a noinput event.

In VoIP configurations, DTMF termination is performed using RFC4733 events. If the gateway does not convert inband DTMF to RFC4733 and/or filter inband DTMF properly, it is possible for the DTMF terminating tone to be part of the recording.

In VoIP configurations, the recording may appear to start early, before the prompt or beep tone is played, due to jitter buffer size on the VoIP client device and/or gateway.

When a recording is submitted with enctype="multipart/form-data", the Content-Type of the submitted data in the request is set to the actual MIME type associated with the audio file format of the recording.


Reprompt

Standard VoiceXML > VoiceXML Tags

<reprompt>

This tag replays previously played prompts. Typically, the Interpreter suppresses playing of prompts on the next form item after executing a <catch> tag. However, if a <reprompt> is executed in the catch, the Interpreter will perform normal prompt processing for the next form item (which includes selection of a prompt and incrementing the prompt counter).

Syntax

<reprompt/>

Attributes

None.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <property name="universals" value="help"/>
  <form>
    <field name="field1" type="boolean">
      <help>
        Please say yes or no.
        <reprompt/>
      </help>
      <prompt> Is that correct? </prompt>
      <filled>
        You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The <reprompt> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Return

Standard VoiceXML > VoiceXML Tags

<return>

This tag completes execution of <subdialog> and returns control and data to the calling dialog. The values returned from a <subdialog> can be any ECMAScript values (for example, strings, numbers, pointers, objects, arrays, and so on).

Syntax

<return
   event="Your event value"
   eventexpr="Your ECMAScript expression"
   message="Your message string"
   messageexpr="Your ECMAScript expression"
   namelist="var1 var2 ..."
/>

Attributes

Exactly one of event, eventexpr, or namelist may be specified; otherwise, a parse error is generated.

Attribute

Description

event

This attribute specifies the name of an event to be returned to the calling dialog and thrown.

eventexpr

This attribute specifies an ECMAScript expression to be evaluated as the name of an event to be returned to the calling dialog and thrown.

message

(Optional) This attribute specifies a message string providing additional context about the event being thrown. The message will be available as a variable within the scope of the <catch> tag.

This attribute can only be used if event or eventexpr is specified.

Only one of message or messageexpr can be specified. Otherwise, the document will generate a parse error.

messageexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the message string, as documented under message.

This attribute can only be used if event or eventexpr is specified.

Only one of message or messageexpr can be specified. Otherwise, the document will generate a parse error.

namelist

This attribute specifies a space-separated list of variables to be returned to the calling dialog. Each of the names and their corresponding values in the namelist will be assigned as a property to the <subdialog> form item variable object of the calling dialog.

This attribute value defaults to no variables.

If an undeclared variable is referenced in the namelist, then an error.semantic is thrown (in the <return> tag’s context).

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput,and Nomatch

Child

None.

GVP Extensions

None.

Example

First, the following document calls the subdialog:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <subdialog name="result" src="subdialog.vxml">
      <filled>
        Your account number is <value expr="result.acctnum"/>.
        Your phone number is <value expr="result.acctphone"/>.
      </filled>
    </subdialog>
  </form>
</vxml>

This document contains the subdialog:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="acctnum" type="digits">
      <prompt> What is your account number? </prompt>
    </field>
    <field name="acctphone" type="phone">
      <prompt> What is your home telephone number? </prompt>
      <filled>
        <return namelist="acctnum acctphone"/>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The <return> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Script

Standard VoiceXML > VoiceXML Tags

<script>

This tag includes a block of client-side ECMAScript.

  • If a <script> occurs as a child of <vxml>, it is evaluated just after the document is loaded, in document order.

  • If a <script> occurs as a child of a <form>, it is evaluated in document order each time execution moves into the <form> tag.

  • If a <script> occurs in executable content, it is evaluated as it is encountered.

Each <script> tag is executed in the scope of its containing tag; for example, it does not have its own scope. Variables defined in <script> are equivalent to variables defined using <var> within the same scope.

See the ECMAScript reference for details on both standard and GVP-defined features.

Syntax

<script
   charset="Your encoding value"
   fetchhint="prefetch"|"safe"
   fetchtimeout="Your timeout interval"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   src="Your URI"
   srcexpr="Your ECMAScript expression">
   script text
</script>

Attributes

An src, srcexpr, expr, or an inline script is required. If one of these attributes or an inline script is not provided, the document containing the tag will generate a parsing error. If this requirement is not provided on the initial page, the call will be rejected. A src, expr, or srcexpr attribute will be used even if they are empty strings, and an external script fetch will be attempted. The resulting absolute URI will likely be an invalid URI and this will result in an error.badfetch event being thrown.

Attribute

Description

charset

(Optional) This attribute specifies the character encoding of the script designated by src or srcexpr. This attribute may be overridden by the protocol headers. (for example, the Content-Encoding header of the HTTP protocol), but it could be useful for protocols which do not provide this information (for example, the file:// protocol).

The default value is UTF-8.

fetchhint

(Optional) This attribute defines when the script should be fetched. The valid value is:

  • safe—only loads the script when needed.

This attribute value overrides the value of the scriptfetchhint property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the script to be fetched before throwing an error.badfetch event.

This attribute value overrides the value of the fetchtimeout property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

maxage

(Optional) This attribute indicates that this document will use a cached copy of the script if the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute value overrides the value of the scriptmaxage property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the script that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute value overrides the value of the scriptmaxstale property (for details, see the W3C Voice Extensible Markup Language 2.0 specification).

src

(Optional) This attribute specifies the URI specifying the location of the script. The URI can be one of the following formats:

  • An external script file—The value is the URL of the script file.

  • A Local script file (that exists in GVP)—The value is: builtin:[<The path>/]<The filename>
    For example:
    /usr/local/phoneweb/script/[<The path>/]<The filename>
    C:\GVP\mp\script\[<The path>/]<The filename>

srcexpr

(Optional) This attribute, new in VoiceXML 2.1, specifies an ECMAScript expression evaluating to the URI of the script file, as documented under src.

If this attribute is provided, the <vxml> version attribute must equal 2.1. Otherwise, the document containing the tag will generate a parsing error.

The platform always throws an error.semantic event when ECMAScript errors are encountered within a <script>.

Parent

Block, Catch, Error, Filled, Foreach, Form, Help, If, Noinput, Nomatch, and Vxml

Child

Text (#PCDATA)

GVP Extensions

None.

Example

Put CDATA escapes around your scripts in order to avoid escaping XML reserved characters (for example, <, >, and &).

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <script>
      <![CDATA[
        var n = 5;
        function square(factor) {
          return factor*factor;
        }
      ]]>
    </script>
    <block>
      <value expr="n"/> squared is <value expr="square(n)"/>.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <script> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Send

Standard VoiceXML > VoiceXML Tags

<send>

This tag supports Sending External Messages by a voice application. The tag supports synchronous and asynchronous mode. In synchronous mode, the Interpreter waits for the response from the application before continuing. In asynchronous mode, the Interpreter resumes execution immediately.

Notes:

If messaging.enabled equals false, executing a <send> will result in error.unsupported.send being thrown.

If an error occurs, the application module returns error.badfetch.<error_reason> (the error_reason should have the format sip.<status_code>).

Syntax

<send
   async="true"|"false"
   asyncexpr="Your ECMAScript expression"
   body="Your message string"
   bodyexpr="Your ECMAScript expression"
   contenttype="Your media type"
   contenttypeexpr="Your ECMAScript expression"
   event="Your event-name to be sent"
   eventexpr="Your ECMAScript expression"
   fetchaudio="Your audio URI>"
   fetchaudioexpr="Your ECMAScript expression"
   header="Your ECMAScript expression"
   namelist="Your var name"
   target="Your target URI"
   targetexpr="Your ECMAScript expression">
child tags
</send>

Attributes

Attribute

Description

async

(Optional) This attribute controls the send mode (synchronous or asynchronous). The valid values are:

  • True—the send mode is asynchronous. Use async equals true if the application needs to ensure subsequent actions take place after a successful <send>. For example, if <send> must transfer information before a <transfer>. Otherwise, the transfer may completed before the send.

  • False—the send mode is synchronous. If the VoiceXML application is sending a large amount of data, Genesys recommends that this attribute to be set to false. Otherwise, subsequent requests from the VoiceXML Interpreter may return unexpected results. For example, <transfer> type=”blind” following an asynchronous <send> (with a large amount of UserData) can fail on the SIP Server.

If an invalid value is used, an error.badfetch is generated in the calling page.

Only one of async or asyncexpr can be specified or the document containing the tag will generate a parsing error.

The default value is true.

asyncexpr

(Optional) This attribute specifies an ECMAScript expression evaluating to the value of the async attribute.

Only one of async or asyncexpr can be specified or the document containing the tag will generate a parsing error.

If evaluation of the expression fails, the Interpreter throws error.semantic.

body

(Optional) This attribute specifies a string representing the data to be sent in the body of the message.

Only one of body, bodyexpr, namelist, event, or eventexpr must be specified or the document containing the tag will generate a parsing error.

bodyexpr

(Optional) This attribute specifies an ECMAScript expression evaluating to the body of the message to be sent.

Only one of body, bodyexpr, namelist, event, or eventexpr must be specified or the document containing the tag will generate a parsing error.

If evaluation of the expression fails, the Interpreter throws error.semantic.

contenttype

(Optional) This attribute specifies a string indicating the media type of the body being sent, if any. The set of content types may be limited by the underlying platform. If an unsupported media type is specified, the Interpreter throws error.badfetch.<protocol>.400. The Interpreter is not required to inspect the data specified in the body to validate that it conforms to the specified media type.

Only one of namelist, or contenttype and contenttypeexpr can be specified or the document containing the tag will generate a parsing error.

If namelist or contenttype are not specified, the default value is text/plain.

If namelist is specified, the default value is application/x-www-form-urlencoded.

contenttypeexpr

(Optional) This attribute specifies an ECMAScript expression evaluating to the media type of the body.

Only one of contenttype or contenttypeexpr can be specified or the document containing the tag will generate a parsing error.

If evaluation of the expression fails, the Interpreter throws error.semantic.

event

(Optional) This attribute specifies the name of the event to send. The value is a string which only includes alphanumeric characters and the dot character (.). The first character must be a letter.

Only one of event or eventexpr can be specified or the document containing the tag will generate a parsing error.

Only one of body, bodyexpr, namelist, event, or eventexpr must be specified or the document containing the tag will generate a parsing error.

If the value is invalid, then an error.badfetch event is thrown.

eventexpr

(Optional) This attribute specifies an ECMAScript expression evaluating to the name of the event to be sent.

Only one of event or eventexpr can be specified or the document containing the tag will generate a parsing error.

Only one of body, bodyexpr, namelist, event, or eventexpr must be specified or the document containing the tag will generate a parsing error.

If evaluation of the expression fails, the Interpreter throws error.semantic.

fetchaudio

(Optional) If the send mode is synchronous, this attribute specifies the URI of the audio to play while waiting for a document to be sent. The default is not to play any audio during fetch delays. There are no fetchaudio properties for audio, grammars, objects, and scripts. The fetching of the audio clip is governed by the audiofetchhint, audiomaxage, audiomaxstale, and fetchtimeout properties in effect at the time of the fetch. The playing of the audio clip is governed by the fetchaudiodelay, and fetchaudiominimum properties in effect at the time of the fetch.

Only one of fetchaudio or fetchaudioexpr can be specified or the document containing the tag will generate a parsing error.

This defaults to the fetchaudio property.

fetchaudioexpr

(Optional) This attribute specifies an ECMAScript expression evaluating to the fetchaudio URI.

Only one of fetchaudio or fetchaudioexpr can be specified or the document containing the tag will generate a parsing error.

If evaluation of the expression fails, the Interpreter throws an error.semantic.

header

(Optional) This attribute evaluates to an ECMAScript object with property names as the name of the header and property values as the value of the header to be passed to the sip info message. The property value can be another ECMAScript variable that evaluates to a string.

Any name that refers to an undeclared variable causes an error.semantic to be thrown when the <send> tag is executed.

namelist

(Optional) This attribute specifies a list of zero or more white-space-separated variable names to send. Values for these variables:

  • Are evaluated when the <send> tag is executed.

  • Must be submitted to the server with the same qualification used in the namelist.

  • Must be converted first into a string before being sent, when an ECMAscript variable is submitted to the server.

If the variable is an ECMAScript object, the mechanism by which it is submitted is platform-specific. Instead of submitting an ECMAScript object directly, the application developer can explicitly submit the individual properties of the object (for example, date.month date.year).

Each tag that is an object or an array is represented using JSON. The namelist is transmitted with url encoding. This is done as follows:

  • Encode each value using JSON.

  • Construct a name=value&name=value... string where each of name and value are URL encoded (to avoid potential issues that may result due to the ampersand delimiter).
    Note:     The current JSON encoding only supports English characters. UTF-8, UTF-16 or other encodings may not work as expected.

Only declared variables can be referenced. Otherwise, an error.semantic is thrown.

Only one of body, bodyexpr, namelist, event, or eventexpr must be specified or the document containing the tag will generate a parsing error.

By default, no variables are submitted.

If this tag is specified, the Content-Type header of the SIP INFO message will be application/x-www-form-urlencoded;charset=utf-8.

target

(Optional) In the current implementation, this attribute has no meaning and only provides compatibility with the W3C proposal on which this section is based. The reason the attribute has no meaning is that only SIP Info is a supported transport. Therefore, the context target is irrelevant.

This attribute specifies the URI to which the event is sent. If the attribute is not specified, the event is sent to the component which invoked the VoiceXML session.

Only one of target or targetexpr can be specified or the document containing the tag will generate a parsing error.

The default value sent to the application module is an empty string. The application module will replace it with a more appropriate value if necessary.

targetexpr

(Optional) In the current implementation, this attribute has no meaning and only provides compatibility with the W3C proposal on which this section is based. The reason the attribute has no meaning is that only SIP Info is a supported transport. Therefore, the context target is irrelevant.

This attribute specifies an ECMAScript expression evaluating to the target URI.
If evaluation of the expression fails, the Interpreter throws an error.semantic.

Only one of target or targetexpr can be specified or the document containing the tag will generate a parsing error.

When present, the attributes asyncexpr, bodyexpr, contenttypeexpr, eventexpr, fetchaudioexpr, and targetexpr are evaluated when the <send> tag is executed.

Parent

Block, Catch, Error, Filled, Foreach, Form, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

None.

Examples

Synchronous

<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form>
   <field name="user_id" type="digits">
      <prompt>
         please type your five digit id
      </prompt>
      <filled>
         <send async="false"
               bodyexpr="'&lt;userinfo&gt;&lt;id&gt;' + user_id + '&lt;/id&gt;&lt;/userinfo&gt;'"
               contenttype="text/xml"/>
         <goto next="mainmenu.vxml"/>
      </filled>
   </field>
</form>
</vxml>

If a synchronous <send> succeeds, execution proceeds according to the Form Interpretation Algorithm (FIA). If the <send> times out, the Interpreter throws error.badfetch to the application. If the Interpreter encounters an error upon sending the external message, the Interpreter throws error.badfetch.<protocol>.<status_code> to the application. If no status code is available, the Interpreter throws error.badfetch.<protocol>.

Asynchronous

<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form>
<var name="tasktarget"
expr="'http://www.example.com/taskman.pl'"/>
<var name="taskname" expr="'cc'"/>
<var name="taskstate"/>
<block>
<assign name="taskstate" expr="'start'"/>
<send async="true"
targetexpr="tasktarget"
namelist="taskname taskstate"
/>
</block>
<field name="ccnum"/>
<field name="expdate"/>
<block>
<assign name="taskstate" expr="'end'"/>
<gvp:send async="true"
targetexpr="tasktarget"
namelist="taskname taskstate"
/>
</block>
</form>
</vxml>

Upon executing an asynchronous <send>, the Interpreter continues execution of the voice application immediately and disregards the disposition of the message that was sent.

Custom SIP Header in <send>

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml" xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
<property name="com.genesyslab.externalevents.enable" value="false"/>
<property name="com.genesyslab.externalevents.queue" value="true"/>

     <form id="form1">
  <block>
       <var name="header_var" expr="new Object()"/>
       <var name="str_var" expr="'HeaderValue1'"/>
       <assign name="header_var.CustomizedHeader1" expr="str_var"/>
       <assign name="header_var['Customized-Header2']" expr="'HeaderValue2'"/>
       <send body="'CustomizedBodyContent'" headers="header_var"/>
  </block>
</form>
</vxml>

Known Issues and Recommendations

None.


Subdialog

Standard VoiceXML > VoiceXML Tags

<subdialog>

This tag invokes another dialog as a subdialog of the current one. The subdialog is a reusable dialog that allows values to be returned. The subdialog executes in a new execution context with all variables and execution state initialized. Values can be passed into the subdialog using <param> child tags. The subdialog must contain a <var> variable declaration for each parameter. The original dialog can continue execution only when the subdialog executes the <return> tag. Returned values are available as properties of the <subdialog> form item variable.

The values passed in and out of a subdialog (using <param> and <return>) can be strings or any ECMAScript values (for example, numbers, pointers, objects, arrays, and so on).

Syntax

<subdialog
   cond="Your ECMAScript expression"
   enctype="Your MIME type"
   expr="Your ECMAScript expression"
   fetchaudio="Your URI"
   fetchhint="safe"
   fetchtimeout="Your timeout interval"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   method="get"|"post"
   name="Your name value"
   namelist="var1 var2 ..."
   src="Your URI"
   srcexpr="Your ECMAScript expression"
   gvp:fetchaudiodelay="Your audio delay time interval"
   gvp:fetchaudiominimum="Your minimum time interval"
   gvp:private="true|false">
   child tags
</subdialog>

Attributes

Attribute

Description

cond

(Optional) This attribute specifies an ECMAScript expression to be evaluated as a boolean condition. This subdialog will be visited only if the expression evaluates to true.

The defaults value is true.

enctype

(Optional) If the method attribute equals post, this attribute specifies the MIME encoding of the submitted data. The following types are supported:

  • Application/x-www-form-urlencoded

  • Multipart/form-data

If an unsupported enctype is specified, an error.unsupported.subdialog is thrown.

The default value is application/x-www-form-urlencoded.

expr

(Optional) This attribute specifies an ECMAScript expression to be evaluated as the initial value of this subdialog. This subdialog will be visited only if the expression evaluates to undefined.

The default value is undefined.

fetchaudio

(Optional) This attribute specifies the URI of the audio to play while waiting for the document to be fetched.

This value overrides the value of the fetchaudio property.

fetchhint

(Optional) This attribute defines when the subdialog should be fetched. The valid value is:

  • safe—only loads the subdialog when needed

This attribute overrides the value of the documentfetchhint property.

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the subdialog to be fetched before throwing an error.badfetch event.

This attribute overrides the value of the fetchtimeout property.

maxage

(Optional) This attribute indicates that this document will use a cached copy of the subdialog only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the documentmaxage property.

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the subdialog that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute overrides the value of the documentmaxstale property.

method

(Optional) This attribute specifies the request method. The valid values are:

  • get

  • post

The default value is get.

name

(Optional) This attribute specifies the name of this subdialog variable. The variable can be referenced anywhere within the subdialog's form. The results returned from the subdialog can be retrieved as properties of the subdialog variable: <Your name value>.<returnVariable>.

The default value is an inaccessible internal variable.

An error event may be thrown if a reserved ECMAScript word is used as the name.

namelist

(Optional) This attribute specifies a space-separated list of variables to submit with the request. If the namelist attribute is missing, no namelist is submitted to the application server. If a namelist is supplied, it may contain individual variable references which are submitted with the same qualification used in the namelist. For http requests with get, the namelist and their values are appended to the request URI. For http requests with post, the namelist is included in the post body. For other types of requests, the namelist is ignored. Only declared VoiceXML and ECMAScript variables can be referenced. If the variable is an ECMAScript object, its value takes on the ECMAScript string ”r;[object]”.

An error.semantic event is thrown if an undeclared variable name is used in the namelist.

src

This attribute specifies the URI of the subdialog. This can be the URI of another document, a dialog in the same document, or a dialog in another document. If this attribute is empty (""), the current document will be used. The valid values are:

  • Absolute URL—starts with http:// or file://. If this type of URL is provided, the URI is fetched and the subdialog is found in the resulting document.

  • URL fragment—starts with a pound sign (#). If this type of URL is provided with a namelist, the URI is fetched and the subdialog is found in the resulting document. If this type of URL is provided without a namelist, there will not be a fetch and the compiled VoiceXML document is re-used to execute the subdialog.

  • Relative URL—any other URL than what is described for absolute or fragment. If this type of URL is provided, the URI is fetched and the subdialog is found in the resulting document.

Either src or srcexpr must be specified, otherwise, the document containing the tag will generate a parsing error.

srcexpr

This attribute specifies an ECMAScript expression to be evaluated as the URI of the subdialog. This can be the URI of another document, a dialog in the same document, or a dialog in another document. If this attribute is empty ("") or set to the empty string ("''"), the current document will be used.

Either src or srcexpr must be specified, otherwise, the document containing the tag will generate a parsing error.

gvp:fetchaudiodelay

(Optional) This attribute specifies the length of time to wait at the start of the fetch delay before playing fetchaudio.

This attribute overrides the value of the fetchaudiodelay property.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiominimum

(Optional) This attribute specifies the minimum length of time to play fetchaudio, once started, even if the document arrives in the meantime.

This attribute overrides the value of the fetchaudiominimum property.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:private

(Optional) This attribute enables data masking for logged metrics (interaction-level messages that described call flow). This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:

  • true—data masking is enabled. The data that is masked includes:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • false—data masking is not enabled (no data is masked).

The default value is false. If an invalid value is used, the page will be rejected.

This attribute takes precedence over com.genesyslab.private.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parent

Form

Child

Audio, Catch, Error, Filled, Help, Noinput, Nomatch, Param, Prompt, Property, Text (#PCDATA), and Value

GVP Extensions

  • fetchaudiodelay attribute

  • fetchaudiominimum attribute

  • private attribute

Example

First, the following document calls the subdialog:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <subdialog name="result" src="subdialog.vxml">
      <filled>
        Your account number is <value expr="result.acctnum"/>.
        Your phone number is <value expr="result.acctphone"/>.
      </filled>
    </subdialog>
  </form>
</vxml>

Then, this document contains the subdialog:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="acctnum" type="digits">
      <prompt> What is your account number? </prompt>
    </field>
    <field name="acctphone" type="phone">
      <prompt> What is your home telephone number? </prompt>
      <filled>
        <return namelist="acctnum acctphone"/>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The VoiceXML session is terminated when the number of subdialog levels has reached the value specified in the vxmli.max_subdialog_level (see the Genesys Voice Platform 8.1 Configuration Options Reference)parameter.

Using the private attribute does not prevent sensitive data from being logged. Therefore, if the VoiceXML application should not log certain data, Genesys recommends that the VoiceXML application use the post method not the get method to submit the data to the web server.

When submitting ECMAScript objects (not including recordings) in the namelist, it is recommended that the developer use the toSource() function.

The order in which the parameters are sent in an HTTP request may not be the same as the order specified in the namelist.

The use of post is recommended when submitting a long list of variables. If you use get (where the entire request is a single line), there may be a limit configured on the request length. Exceeding this limit will result in an error.badfetch. This limit may be configured by squid (on the platform), or it may be overridden by application server configuration.

When a recording is submitted with enctype="multipart/form-data", the Content-Type of the submitted data in the request is set to the actual MIME type associated with the audio file format of the recording.


Submit

Standard VoiceXML > VoiceXML Tags

<submit>

This tag submits values to the document server, and transitions to the document returned in the response. It is similar to <goto> in that it results in a new document being obtained, and transitions to that new document. Unlike <goto>, it includes a namelist to submit a list of variables to the document server using HTTP get or HTTP post. If you do not want to submit any variables, use <goto> instead.

Syntax

<submit
   enctype="Your MIME type"
   expr="Your ECMAScript value"
   fetchaudio="Your fetchaudio URI"
   fetchhint="safe"
   fetchtimeout="Your time out interval"
   maxage="Your maxage value"
   maxstale="Your maxstale value"
   method="get"|"post"
   namelist="var1 var2..."
   next="Your next URI"
   gvp:fetchaudiodelay="Your delay time value"
   gvp:fetchaudiominimum="Your minimum fetch value"
/>

Attributes

Attribute

Description

enctype

(Optional) If the method attribute equals post, this attribute specifies the MIME encoding of the submitted data. The case-sensitive valid values are:

  • application/x-www-form-urlencoded

  • multipart/form-data—When a recording is submitted with enctype="multipart/form-data", the Content-Type of the submitted data in the request is set to the actual MIME type associated with the audio file format of the recording.

The default value is application/x-www-form-urlencoded. Any other specified value causes an error.unsupported.submit event to be generated.

expr

This attribute specifies an ECMAScript expression to be evaluated as the URI of the submit request, as documented under next.

If there is an error while evaluating the expr attribute, an error.semantic is generated.

Either next or expr is required. If both attributes are specified, the document containing the tag will generate a parsing error.

fetchaudio

(Optional) This attribute specifies the URI of audio to play while waiting for the document to be fetched.

This attribute overrides the value of the fetchaudio property.

fetchhint

(Optional) This attribute defines when the next document should be fetched. the valid value is:

  • safe—only loads the next document when needed.

This attribute overrides the value of the documentfetchhint property.

fetchtimeout

(Optional) This attribute specifies the length of time to wait for the next document to be fetched before throwing an error.badfetch event.

This attribute overrides the value of the fetchtimeout property.

maxage

(Optional) This attribute indicates that this document will use a cached copy of the next document only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute.

This attribute overrides the value of the documentmaxage property.

maxstale

(Optional) This attribute indicates that this document will use a cached copy of the next document that has exceeded its expiration time by as much as the number of seconds specified by this attribute.

This attribute overrides the value of the documentmaxstale property.

method

(Optional) This attribute specifies the request method (the HTTP method used to submit the HTTP request to the HTTP server). The valid values are:

  • get

  • post

If an invalid value is specified for this attribute, an error.semantic event is generated.

The default value is get.

next

This attribute specifies the URI of the submit request. The application will transition to the document sent back in the response.

Either next or expr is required. If both attributes are specified, the document containing the tag will generate a parsing error.

namelist

(Optional) This attribute specifies a space-separated list of variables to submit with the request.

The default value includes all the named input item variables in the current form. An empty string is treated as the default.

An error.semantic event is thrown if an undeclared variable name is used in the namelist.

gvp:fetchaudiodelay

This attribute specifies the length of time to wait at the start of the fetch delay before playing fetchaudio.

This attribute overrides the value of the fetchaudiodelay property.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:fetchaudiominimum

(Optional) This attribute specifies the minimum length of time to play the fetchaudio, once started, even if the document arrives in the meantime.

This attribute overrides the value of the fetchaudiominimum property.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Parents

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Children

None.

GVP Extensions

  • fetchaudiodelay attribute

  • fetchaudiominimum attribute

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="boolean">
      <prompt> Please say yes or no. </prompt>
      <filled>
        You said <value expr="field1"/>.
        <submit next="process.cgi" method="post" namelist="field1"/>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

When submitting ECMAScript objects in the namelist, the object will be flattened (all the object's properties will be submitted separately). For example, if object o has two properties, p1 and p2, such that o.p1="value1" and o.p2="value2", and the following transition is made:
<submit next="test.jsp" namelist="o" ...>
the HTTP request will contain o.p1=value1&o.p2=value2. Remember to retrieve the properties separately (as o.p1 and o.p2) in the server-side code used to generate the next page.

The order in which the parameters are sent in an HTTP request may not be the same as the order specified in the namelist.

The use of post is recommended when submitting a long list of variables. If you use post (where the entire request is a single line), there may be a limit configured on the request length. Exceeding this limit will result in an error.badfetch. This limit may be configured by squid (on GVP), or may be overridden by application server configuration.

The <submit> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Throw

Standard VoiceXML > VoiceXML Tags

<throw>

This tag triggers an event that can be caught and handled with the <catch> tag. Either platform defined events (for example, nomatch) or user-defined events can be thrown using this tag.

Syntax

<throw
   event="Your event value"
   eventexpr="Your ECMAScript expression"
   message="Your message value"
   messageexpr="Your ECMAScript value"
/>

Attributes

Attribute

Description

event

This attribute specifies the name of the event to be thrown.

Either event or eventexpr is required. If both attributes are specified, the document containing the tag will generate a parsing error.

eventexpr

This attribute specifies an ECMAScript expression to be evaluated as the name of the event to be thrown.

Either event or eventexpr is required. If both attributes are specified, the document containing the tag will generate a parsing error.

message

(Optional) This attribute specifies a message string providing additional context about the event being thrown. For the pre-defined events thrown by the platform, the value of the message is platform-dependent. The message will be available as a variable within the scope of the <catch> tag.

Either message or messageexpr is required. If both attributes are specified, the document containing the tag will generate a parsing error.

messageexpr

(Optional) This attribute specifies an ECMAScript expression to be evaluated and used as a message string, as documented under message.

Either message or messageexpr is required. If both attributes are specified, the document containing the tag will generate a parsing error.

Parent

Block, Catch, Error, Filled, Foreach, Help, If, Noinput, and Nomatch

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <catch event="goodbye">
    Thank you for calling. Goodbye.
    <exit/>
  </catch>
  <form>
    <field name="field1" type="boolean">
      <dtmf> * </dtmf>
      <prompt>Please press the star.</prompt>
      <filled>
        <if cond="field1 == '*'">
          <throw event="goodbye"/>
        </if>
      </filled>
    </field>
  </form>
</vxml>

Known Issues and Recommendations

The <throw> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.


Transfer

Standard VoiceXML > VoiceXML Tags

<transfer>

This tag transfers the caller to another phone number. There are three types of transfer:

  • Bridge—The control is returned to the application depending on the result of the transfer. For example, if the agent is busy or does not answer, then the VoiceXML application can be designed in such a way that there is an announcement (prompt) that can be played to the caller. If the transfer is successful when the agent is answering the call and when the agent initiates a hang up, the application can be designed to play an announcement.

  • Blind—As soon as the transfer is initiated, the application is detached from the call, and has no way of knowing if the transfer attempt was successful or not. If the transfer is not initiated at all, due to errors, the caller remains in the application, where the errors can be handled.

  • Consultation—Once the transfer attempt finishes successfully, for example, the caller is connected to the third party, the application is detached from the call. If the transfer either is not initiated at all, due to errors, or does not finish successfully, the caller remains in the application, where the errors can be handled.

IMPORTANT: The developer platforms may not allow the use of <transfer>. Attempting to make a transfer may generate an error.

Syntax

<transfer
   aai="Your aai value"
   aaiexpr="Your ECMAScript expression"
   bridge="true"|"false"
   cond="Your ECMAScript expression"
   connecttimeout="Your time interval"
   dest="Your URI"
   destexpr="Your ECMAScript expression"
   expr="Your ECMAScript expression"
   maxtime="Your time interval"
   name="Your name value"
   transferaudio="Your URI"
   type="bridge"|"blind"|"consultation"
   gvp:analysis="true"|"false"
   gvp:authcode="Your string"
   gvp:connectwhen="answered"|"immediate"
   gvp:consultexpr="Your ECMAScript expression"
   gvp:disconnectonansweringmachine="true"|"false"
   gvp:method="HKF"|"REFER"|"BRIDGE"|"REFERJOIN"|"MEDIAREDIRECT"|"ATTCOURTESY"|"ATTCONSULT"|"ATTCONFERENCE"|"ATTOOBCOURTESY"|"ATTOOBCONSULT"|"ATTOOBCONFERENCE"|"NEC61ISDN"
   gvp:namelist="Your ECMAScript variable names separated by zero or more spaces"
   gvp:private="true|false"
   gvp:signalvar="Your ECMA object"
   gvp:userdata="Your ECMAScript expression">
  child tags
</transfer>

Attributes

Attribute

Description

aai

(Optional) This attribute contains the Application-to-Application Information (AAI) data to be sent to an application. For example:

  • If aai is included and the network configuration supports the transmission of AAI data, the AAI data string will be available in the session variable session.connection.aai of the called application.

AAI data is a string of limited length that is sent over the PSTN. If the intent is to have the called party access this string, they must have a device that is capable of retrieving the sent data. If you need to allow the called party to access application data (possibly by hearing a message or audio file), use the GVP call control features.

Either aai or aaiexpr may be specified (do not specify both attributes).

  • If both aai and aaiexpr are specified, the document containing the tag will generate a parsing error.

  • If neither aai nor aaiexpr is specified, GVP will send the AAI data from the inbound line (for example, session.connection.aai). If there is no data from the inbound line (for example, the session variable is undefined), then no AAI data is sent.

aaiexpr

(Optional) This attribute contains an ECMAScript expression that evaluates to the Application-to-Application Information (AAI) data string, to be sent to an application.

Either aai or aaiexpr may be specified (do not specify both attributes).

  • If both aai and aaiexpr are specified, the document containing the tag will generate a parsing error.

  • If neither aai nor aaiexpr is specified, GVP will send the aai data from the inbound line (for example,. session.connection.aai). If there is no data from the inbound line (for example, the session variable is undefined), then no AAI data is sent.

bridge

(Optional) This attribute determines what to do after the call is connected. The valid values are:

  • true—executes a bridged transfer.

  • false—executes either a blind or consultation transfer (depending on value of type attribute).

If neither bridge nor type is specified, the transfer-type default value is blind.

Either bridge or type may be specified. Do not specify both attributes, otherwise, a parse error is thrown.

cond

(Optional) This attribute contains an ECMAScript expression to be evaluated as a boolean condition. This transfer will be executed only if the expression evaluates to true.

The default value is true.

connecttimeout

(Optional) If the <transfer> tag's type attribute-value equals bridge or consultation, this attribute specifies the time to wait for a call to be connected, before it returns a noanswer condition.

This value is passed to the platform in the transfer-request, it is of type time-destination.

This attribute is not supported and ignored if the transfer method is refer.

The default value is 30s, and the minimum value is 5s. The default value can be configured in the GVP configuration.

dest

(Optional) This attribute specifies the URI of the destination phone. The destination is passed as a character string as part of the transfer request. If the platform determines that the transfer destination is invalid, the platform returns an error code indicating an invalid destination, and the Interpreter throws an error.semantic event.

In a VoIP environment, the format to call a phone number through an IP/PSTN gateway is:

  • tel:<Your number>

  • phone:<Your number>

  • sip:<Your number>@<Your gateway>[:<Your port>]

  • sips:<Your number>@<Your gateway>[:<Your port>]

In a VoIP environment, the format to call a VoIP endpoint device directly is:

  • sip:[<Your User name>@]<Your host>[:<Your port>]

  • sips:[<Your User name>@]<Your host>[:<Your port>]

In any of the above, forward slashes can optionally follow the protocol, although that is not standard for telephone URIs. For example, tel://..., phone://..., and so on.

In any of the above, <Your number> can be prefixed with +1. For example: tel:+14167360905.

Either dest or destexpr may be specified. Do not specify both attributes, otherwise, the document containing the tag will generate a parsing error.

destexpr

(Optional) This attribute contains an ECMAScript expression to be evaluated as the destination of the transfer. The destination is passed as a character string as part of the transfer request. If the platform determines that the transfer destination is invalid, the platform returns an error code indicating an invalid destination, and the Interpreter throws an error.semantic event.

Either dest or destexpr may be specified. Do not specify both attributes, otherwise, the document containing the tag will generate a parsing error.

expr

(Optional) This attribute contains an ECMAScript expression to be evaluated as the initial value of this transfer. The transfer will be executed only if the expression evaluates to undefined.

The default value is undefined.

maxtime

(Optional) If the <transfer> tag's type attribute-value equals bridge, this attribute specifies the maximum time that the call is allowed to last.

The default value is 0 (no limit).

name

(Optional) This attribute assigns a name to the transfer object. The object stores the result of the transfer, and can be referenced anywhere within the transfer's form.

The default value for this attribute is an inaccessible internal variable. The return values are:

  • Busy—The endpoint refused the call.

  • Noanswer—There was no answer within the time specified by the connecttimeout attribute.

  • Network_busy—Some intermediate network refused the call.

  • Near_end_disconnect—The call was completed and was terminated by the caller.

  • Far_end_disconnect—The call was completed and was terminated by the called party.

  • Network_disconnect—The call was completed and was terminated by the network.

  • Maxtime_disconnect—The call duration exceeded the value of the maxtime attribute and was terminated by the platform.

  • Rejected—This result is only possible with multiphase transfers (for example, when consultexpr is set). This result occurs when the child script exits without setting accepttransfer (or with it set to a value other than true).

  • Not_allowed—The document is not allowed to use the <transfer> tag.

  • Unknown—The outcome of the transfer is unknown.

If the transfer request is unacceptable and the transfer is not initiated at all, the transfer variable will not be set and the platform will throw an error.

An error event may be thrown if a reserved ECMAScript word is used as the name.

transferaudio

(Optional) If the <transfer> tag's type attribute-value equals bridge or consultation, this attribute specifies the URI of an audio file to be played while connecting the call. This value is passed to the platform in the transfer request. If this value is not defined, no transfer audio is played and the caller hears whatever is defined in the connectwhen attribute. For example, if connectwhen="immediate", network ringing will be heard.

type

(Optional) This attribute specifies the transfer behavior (from the VoiceXML application's perspective). The valid values are:

  • bridge—The application does not detach from the original inbound call unless the original caller disconnects. The control of the call will always return to the application when the transfer ends, regardless of the result. This type means bridge="true" (the application or default bridge setting will be overridden, if necessary).

  • blind—The application detaches from the original inbound call as soon as the transfer is initiated. That is, after the transfer request is made to the telephony network (assuming the request is acceptable), the platform throws a connection.disconnect.transfer or telephone.disconnect.transfer, and the application detaches from the call and is unable to detect the progress or outcome of the transfer attempt. However, if the transfer request is unacceptable and the transfer is not initiated at all, the application will retain control of the call, and error events (for example, error.connection.baddestination or error.telephone.baddestination) will be thrown. This type means bridge="false" (the application or default bridge setting will be overridden, if necessary).

  • consultation—The application detaches from the original inbound call only if the transfer attempt finishes successfully. That is, after the transfer request is made to the telephony network (assuming the request is acceptable), if the caller is successfully connected to the third party, the platform throws a connection.disconnect.transfer, and the application detaches from the call. If the transfer attempt fails, the application will retain control of the call, and the failure reason will be handled either by assigning a value to the transfer name variable or by throwing an event. If the transfer request is unacceptable and the transfer is not initiated at all, the application will retain control of the call, and error events (for example, error.connection.baddestination) will be thrown. This type means bridge="false" (the application or default bridge setting will be overridden, if necessary).

If bridge="true", this attribute defaults to bridge. If bridge="false", it defaults to blind. If neither bridge nor type is specified, the transfer type default value is blind.

If this attribute is used, the <vxml> version attribute must equal 2.1. Otherwise, the document containing the tag will generate a parsing error.

If the <vxml> version attribute is set to 2.1, both bridge and type attributes cannot be specified at the same time. The default value will be used for whichever attribute is not specified.

Either bridge or type may be specified. Do not specify both attributes, otherwise, a parse error will be thrown.

gvp:analysis

(Optional) This attribute specifies whether the platform is enabled to detect who or what answered the call. The valid values are true and false (any other value will cause the error.semantic event to be thrown when the tag is executed).

If this attribute is set to true and the call is answered, the behavior is as follows:

  • If the platform detects an answering machine, the behavior depends on the value of the detectansweringmachine attribute, below.

  • If the platform detects a fax machine, the transfer will be immediately disconnected, and the transfer variable will be set to far_end_fax.

  • If the platform detects that a human answered, the original caller will be connected to the called endpoint, and the transfer variable will be set when the call is disconnected (the value will depend on how the connection is terminated).

When this attribute is enabled, the CPA capability also needs to be enabled on the MCP. Otherwise, the transfer request fails. The MCP configuration option [cpa]outbound.method must be changed to enable CPA.

If this attribute is set to false, and the call is answered, the platform will not be able to differentiate between an answering machine, fax machine, or human. The original caller will be connected to the called endpoint in all three cases, and the transfer variable will be set when the call is disconnected (the value will depend on how the connection is terminated).

In some telephony environments, analysis must be set to true for the platform to be able to detect a busy tone. In other environments (for example, SIP), the platform will be able to detect a busy tone regardless of the analysis setting. For calls that are unsuccessful for other reasons, the platform will generally be able to report the failure reasons (for example, noanswer), regardless of the analysis setting.

The default value is false.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:authcode

(Optional) This attribute is a user-specified string, which is the transfer authorization code to be provided to the PSTN Connector. The Interpreter will not perform validation of this attribute. The value will be passed to the platform as part of the transfer request.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Note: The GVP 8.1.5 release does not contain the PSTN Connector component. Only GVP 8.1.2, 8.1.3, and 8.1.4 releases contain the PSTN Connector. See the Genesys Migration Guide for information about using PSTN Connector 8.1.4 with the GVP 8.1.5 release.

gvp:connectwhen

(Optional) This attribute controls when the media path of the original caller and the outbound call should be joined together in a bridged transfer. The valid values are:

  • answered—A connection is made after the call is picked up.

  • immediate—A connection is made immediately. The caller hears the ringing.

If one of the valid values is not specified, an error.semantic event is generated from the transfer scope.

If transferaudio is specified, the default value is answered. Otherwise, the default value is immediate. If connectwhen equals immediate, the value of the transferaudio is ignored and is not passed to the platform in the transfer request.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:consultexpr

(Optional) Using this attribute specifies that the transfer should be multiphase.

This attribute contains an ECMAScript expression evaluating to the URI (possibly including a #<Your form id> fragment) of the child VoiceXML page that will be played for the callee at the beginning of the multiphase transfer.

  • If this attribute is empty ("") or set to the empty string literal ("''"), the attribute will be ignored and the transfer will not be multiphase.

  • If this attribute is not empty and the expression evaluates to an empty string (''), then the current VoiceXML page will be used.

For a list of transfer methods that this feature is supported with, see the Genesys Voice Platform 8.1 Deployment Guide.

This attribute is not supported with SIP refer.

When performing a multiphase transfer with bridge="false", the type attribute should always be set to consultation. Setting the type to blind (or unsupervised) does not make sense.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:disconnectonansweringmachine

(Optional) This attribute manages behavior when the call is connected to an answering machine. The valid values are:

  • true—the transfer will be immediately disconnected on detecting an answering machine, and the transfer variable will be set to far_end_machine.

  • false—the original caller will be connected to the answering machine, and the transfer variable will be set when the call is disconnected. The transfer variable value will depend on how the connection is terminated.

This attribute is supported if analysis="true".

The default value is false.

If an invalid value is provided, an error.semantic event is generated from the transfer scope.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:method

(Optional) This attribute specifies the transfer method to be used by the Media Control Platform (MCP) at the telephony layer. Typically, this attribute is not used because the default MCP configuration that ships with GVP is sufficient. The default value depends on sip.defaultblindxfer, sip.defaultconsultxfer and sip.defaultbridgexfer configuration parameters for the respective transfer type. However, where the default MCP configuration is not sufficient this attribute is available. The valid values are:

  • HKF

  • REFER

  • BRIDGE

  • REFERJOIN

  • MEDIAREDIRECT

  • ATTCOURTESY

  • ATTCONSULT

  • ATTCONFERENCE

  • ATTOOBCOURTESY

  • ATTOOBCONSULT

  • ATTOOBCONFERENCE

  • NEC61ISDN

For details about these values, see the Genesys Voice Platform 8.1 Deployment Guide.

All platforms support the bridge method. If additional methods are supported (and configured), they will be listed under the sip.transfermethods in the MCP.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

MCP does not support sip:URL in the transfer tag with the gvp:method attribute for HKF, ATTCOURTESY, ATTCONSULT, and ATTCONFERENCE).  tel:URL is supported.

gvp:namelist

This attribute is a list of ECMAScript variable names separated by zero or more spaces. Any name that refers to an undeclared variable causes an error.semantic to be thrown when the <transfer> element is visited.

The Interpreter passes these variables to GVP, to be used as user data, as part of the Transfer request . Each variable that is an object or an array is represented using JSON.

To indicate that the content is user data, the value specified in the vxmli.userdata.prefix GVP configuration parameter will prefix each variable name in the namelist.

For example:

var
 myVar = new Object();
myVar["name"] = "Michael";
myVar["phone"] = "5678";
var email = new Array();
email.push("mwong@sf.com");
email.push("mwong@yahoo.com");
<transfer gvp:namelist=”myVar email” ...>

In the transfer SIP request header, the myVar and email variables are presented as:

[userdata prefix]myVar: {"name":"Michael", "phone":"5678"}
[userdata prefix]email: ["mwong@sf.com","mwong@yahoo.com"]

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Only one of the userdata and namelist attributes can be specified in a <transfer> element. If both are specified, error.badfetch will be thrown.

gvp:private

(Optional) This attribute enables data masking for logged metrics (interaction-level messages that described call flow). This means that private data like credit card numbers, social insurance numbers, and so on are converted to asterisks (for example, 123 would be converted to ***). The valid values are:

  • true—data masking is enabled. The data that is masked includes:
    - asr_trace (result)
    - dtmf (digit)
    - input_end (phrase)
    - prompt _play (all)
    - subdialog_start (param_value and URL query string)
    - eval_cond
    - eval_expr (expression and value)
    - eval_var (expression and value)
    - submit (namelist and URL query string)
    - link (URL query string)
    - parse_error (URL query string)
    - wf_arrived (URL query string)
    - wf_lookup (URL query string)
    - event_handler_enter (URL query string)
    - filling (value)
    - filled_enter (namelist)

  • false—data masking is not enabled (no data is masked).

The default value is false. If an invalid value is used, the page will be rejected.

This attribute takes precedence over com.genesyslab.private.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

gvp:signalvar

(Optional) This attribute is an ECMAScript expression evaluating to an ECMAScript object and it contains a variable number of parameters associated with the call request. The Interpreter must pass this object to the platform as part of the transfer request.

To make use of these outgoing signaling variables, the called party must have a switch that is capable of delivering the information.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Note: You can configure MCP to set outgoing SIP INVITE or REFER requests’ URI parameters, headers, and parameters of any headers (limitations) using this variable. The Media Control Platform can also be configured to set outgoing SIP INVITE or REFER requests’ URI’s parameters, headers, and parameters of any headers (limitations) using signaling variables from the VXML application. Below is an example VoiceXML page that will perform this configuration, using signalvar:

<?xml
 version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml"
xmlns:gvp="http://www.anexample.com/1111/vxml21-extension">
<property name="com.genesyslab.externalevents.enable" value="false"/>
<property name="com.genesyslab.externalevents.queue" value="true"/>
<var name="This_page" expr="'MCP.SIP.VAR.17.1.vxml'"
 />
<form id="form1">
<var name="callvars" expr="new
 Object()"/>
<block>
<assign name="callvars['sip.invite.requesturi.parama']"
 expr="'valueA'"/>
<assign name="callvars['sip.invite.requesturi.paramb']"
 expr="'valueB'"/>
<assign name="callvars['sip.invite.headerc']"
 expr="'valueC'"/>
</block>
<transfer destexpr="'sip:9090@127.0.0.1:5060'"
 bridge="true" gvp:signalvar="callvars">
<filled>
<log> #QA#<value
 expr="This_page"/>#PASS# </log>
<exit expr="'PASS'"/>
</filled>
</transfer>
</form>
</vxml>

gvp:userdata

This attribute is an ECMAScript expression evaluating to an ECMAScript object, and it contains a variable number of parameters to associate with the call request. The Interpreter passes this object to the platform as part of the transfer request to be used as userdata. To indicate that the content is userdata, the first value specified in the parameter vxmli.userdata.prefix will prefix each specified property of the userdata object. For details, see the Genesys 8.1 Voice Platform Solution Integration Guide.

This attribute is a GVP extension and must be qualified by the GVP-namespace when used in the tag.

Shadow Variables

For each <transfer> whose name attribute is set to <Your name value>, there is a shadow variable
<Your name value>$ (in the same scope as the transfer name variable) that contains the following properties after the transfer completes. When any shadow variable is not set, its value will be ECMAScript undefined.

Property

Description

<Your name value>$.duration

This property contains the duration of the call in seconds. The duration is 0 if a call attempt was terminated by the caller (using a voice or DTMF command) prior to being answered. In the case where the caller hangs up before the transfer is connected, the duration is timed from when the transfer request was made, and therefore will be greater than 0.

<Your name value>$.inputmode

This property contains the input mode (voice or dtmf), if input terminated the transfer; otherwise, undefined (if the input was not terminated by a grammar match).

<Your name value>$.disconnectreason

This property contains the Reason header value of the SIP BYE message of the callee. It is only applicable if the transfer form item variable is set to far_end_disconnect.

This property is a GVP extension.

<Your name value>$.markname

This property contains the name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. This is only meaningful when the <transfer>'s prompts contain <mark>s.

This property is a GVP extension.

<Your name value>$.marktime

This property contains the number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is undefined. This is only meaningful when the <transfer>'s prompts contain <mark>s.

This property is a GVP extension.

<Your name value>$.recording

This property contains a reference to the recording, or the value undefined if no audio is collected.

This variable is available if the recordutterance property is set to true and the transfer was terminated by speech input.

This property is a GVP extension.

<Your name value>$.recordingduration

This property contains the duration of the recording in milliseconds (if <your name value>$.recording was assigned a value), or the value undefined.

This property is a GVP extension.

<Your name value>$.recordingsize

This property contains the byte-size of the recording (if <your name value>$.recording was assigned a value), or the value undefined.

This property is a GVP extension.

<Your name value>$.result.<vari>

These properties only exist with multiphase transfers (for example, when consultexpr is set). They are used to access any variables returned from the child script by <exit namelist="<var1> <var1> .../>.

This property is a GVP extension.

<Your name value>$.utterance

This property contains:

  • The utterance text (if transfer was terminated by speech recognition input)

  • The DTMF result (if the transfer was terminated by DTMF input),

  • The value undefined, for other scenarios.

This property is a GVP extension.

Transfer Variable

After a transfer attempt has been made, the following table shows what might be filled into the transfer form item variable in certain situations. Each of these reasons is indicated by the platform.

Value of transfer variable | Reason
busy | The callee was busy.
network_busy | An intermediate network refused the call.
noanswer | There was no answer within the time that is specified by the connecttimeout attribute.
unknown | The transfer ended, but the reason is not known.
far_end_fax | A fax machine was detected.
modem | A modem was detected.
far_end_modem | A modem was detected.
nodialtone | No dial tone was detected.
noringback | No ring back was detected.
far_end_machine | An answering machine was detected.
sit_reorder | SIT reorder was detected.
sit_vacant_circuit | SIT vacant circuit was detected.
sit_no_circuit | SIT no circuit was detected.
sit_ineffective_other | SIT ineffective other was detected.
sit_operator_intercept | SIT operator intercept was detected.

Events Thrown

The following events can be thrown during the execution of the <transfer> tag:

  • error.connection.baddestination

  • error.connection.noauthorization

  • error.connection.nolicense
    This is a GVP extension.

  • error.connection.noresource

  • error.connection.noroute

  • error.connection.<protocol>.<nnn>

  • connection.disconnect.hangup

  • connection.disconnect.transfer

  • error.unsupported.transfer.blind

  • error.unsupported.transfer.bridge

  • error.unsupported.transfer.consultation

  • error.unsupported.uri

Parent

Form

Child

Audio, Catch, Error, Filled, Grammar, Help, Noinput, Nomatch, Prompt, Property, Text (#PCDATA), and Value

GVP Extensions

  • analysis attribute

  • authcode attribute

  • connectwhen attribute

  • consultexpr attribute

  • detectansweringmachine attribute

  • disconnectonansweringmachine attribute

  • method attribute

  • private attribute

  • signalvar attribute

  • userdata attribute

  • disconnect_reason shadow variable

  • markname shadow variable

  • marktime shadow variable

  • recording shadow variable

  • recordingduration shadow variable

  • recordingsize shadow variable

  • result shadow variable

  • utterance shadow variable

  • error.connection.nolicense event

Example

The developer platforms may not allow the use of <transfer>, and running the example below on those platforms will generate an error.

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <transfer name="newcall" dest="tel:4167360905x111" bridge="true">
      <filled>
        Your call lasted <value expr="newcall$.duration"/> seconds.
        <if cond="newcall == 'busy'">
          All our customer care agents are currently busy.
          Please call back later.
        </if>
      </filled>
    </transfer>
  </form>
</vxml>

Known Issues and Recommendations

Using the private attribute does not prevent sensitive data from being logged. Therefore, if the VoiceXML application should not log certain data, Genesys recommends that the VoiceXML application use the post method not the get method to submit the data to the web server.

The developer platforms might not allow the use of <transfer>. Attempting to make a transfer may generate an error.

All recognition in transfer is done using hotword mode.

VoIP support:

  • Support for extension dialing depends on the IP/PSTN gateway used.

  • The pause feature (adding pauses during dialing) is not supported.

  • Non-bridged transfers are only supported if the initial calling device supports them.

  • The analysis attribute is not supported.

Blind transfers:

  • Extension dialing is generally not supported with blind transfers. Adding extra pauses to the dial string (for example, <Your number value>,,,<Your extension value>) as a workaround to dial extensions will only work for hookflash transfers.

  • transferaudio will not play in the case of blind transfers.

Some transfer methods may not be supported for all transfer types, due to the mechanisms of the transfer methods. For more details see the Genesys 8.1 Voice Platform Solution Integration Guide.


Value

Standard VoiceXML > VoiceXML Tags

<value>

This tag is used to insert the value of an expression into a prompt.

Syntax

<value
    expr="Your ECMAScript expression"
/>

Attributes

Attribute | Description
expr | This attribute contains the ECMAScript expression to be evaluated and inserted into the prompt. If the ECMAScript cannot be evaluated, an error.semantic is generated. If this attribute is not included, a parse error is generated.

Parent

Audio, Block, Catch, Choice, Enumerate, Error, Field, Filled, Foreach, Help, If, Initial, Log, Menu, Noinput, Nomatch, Object, Prompt, Record, Speech Markup (SSML) Tags, Subdialog, and Transfer

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <var name="var1" expr="'first'"/>
  <form>
    <block>
      The initial value is <value expr="var1"/>.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Var

Standard VoiceXML > VoiceXML Tags

<var>

This tag declares a variable in the scope of its parent tag.

  • If the <var> occurs in executable content, the declaration is made only when the <var> tag is executed.

  • If the <var> occurs as a child of a <form>, the declaration is made during the form's initialization phase.

  • If the <var> occurs as a child of <vxml>, the declaration is made when the document is initialized (in document order).

  • If the variable is already defined in the current scope, further declarations are treated as value assignments.

Syntax

<var
   expr="Your ECMAScript experession"
   name="Your name value"
/>

Attributes

Attribute

Description

expr

(Optional) An ECMAScript expression to be evaluated as the initial value assigned to the variable. If this attribute is not provided, the variable retains its current value, if any.

The default value is undefined.

name

This attribute is the name of the variable that will hold the result. If the name contains a scope or object prefix, an error.semantic event is thrown at the time the <var> is executed.

If this attribute is not included, the document containing the <var> tag will generate a parse error.

Parent

Block, Catch, Error, Filled, Foreach, Form, Help, If, Noinput, Nomatch, and Vxml

Child

None.

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <var name="var1" expr="'first'"/>
  <form>
    <block>
      The initial value is <value expr="var1"/>.
    </block>
  </form>
</vxml>

Known Issues and Recommendations

The <var> tag cannot be used as a child of <foreach> when <foreach> is a child of <prompt>, and the vxmli conformance.disallow_exec_content_within_prompts parameter is set to true. See the Genesys Voice Platform 8.1 Configuration Options Reference for details about the parameter.

Variables declared in the name attribute must not:

  • Start with the underscore character (_).

  • End with the dollar sign character ($).

  • Contain a dot (for example x.y).

If one of the above characters is included, the error.semantic event is thrown when the tag is executed.


Vxml

Standard VoiceXML > VoiceXML Tags

<vxml>

This tag identifies a VoiceXML document.

Syntax

<vxml
   application="Your URI"
   version="Your version"
   xmlns="http://www.w3.org/2001/vxml"
   xml:base="Your URI"
   xml:lang="Your language value">
   child tags
</vxml>

Attributes

Attribute

Description

application

(Optional) This attribute provides the URI of this document's application-root document.

If the root document specified by the page cannot be found, or if the root document refers to another root document, the document containing the tag will generate a fetch error.

version

This attribute specifies the VoiceXML version number. The platform supports 2.0 and 2.1. The valid values are:

  • 2.0

  • 2.1

If this attribute is not set to either 2.0 or 2.1, the document containing the tag will generate a parsing error.

If this attribute is omitted, the document containing the tag will generate a parsing error.

xmlns

This attribute is the VoiceXML specification. It designates the namespace for VoiceXML. The VoiceXML must declare the VoiceXML namespace "http://www.w3.org/2001/vxml" in the top-level <vxml> tag. The valid values are:

  • <vxml xmlns="http://www.w3.org/2001/vxml" …/>
    Use this value if the top-level vxml tag is not qualified with any prefixes and the xmlns attribute is present in the <vxml> tag.

  • <n1:vxml xmlns:n1="http://www.w3.org/2001/vxml" …/>
    Use this value if the top-level <vxml> tag is qualified with a namespace prefix and the namespace prefix references the above namespace.
    In this case, all VoiceXML elements defined must be prefixed by the same prefix as the <vxml> tag.

If this attribute is o mitted, the document containing the tag will generate a parsing error.

xml:base

(Optional) This attribute is the base URI of this document. Relative references in this document use this URI as the base URI.

xml:lang

This attribute provides the application-wide language identifier for the document. It is used as the language for:

  • Implicit grammars (for example, universal grammars, and <choice>/<option> grammars)

  • Multi-language grammars

  • Prompts

If this attribute is not provided, the default value comes from the com.genesyslab.defaultlanguage property of the default root page. If the com.genesyslab.defaultlanguage property is not provided, the default value is provided in the Interpreter configuration.

The default value is platform-specific.

Parent

None.

Child

Catch, Data, Error, Form, Help, Link, Menu, Meta, Noinput, Nomatch, Property, Script, and Var

GVP Extensions

None.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <block>
      Hello, world!
    </block>
  </form>
</vxml>

Known Issues and Recommendations

None.


Debugging

Overview

The following topics will help you with debugging your applications:

  • Saving Temp Files

  • Document Sizes

  • Maintainer E-mail

  • Logging Content Definition/Log()

  • __GetProperty()


Debugging

Saving Temp Files

This feature enables the NGI to save various information to disk for later use. The information saved can be items such as prompts and VoiceXML pages. Three properties control the behavior of this feature:

  • com.genesyslab.savetmpfiles

  • com.genesyslab.savetmpfilesmode

  • com.genesyslab.onexit.keeptmpfiles

com.genesyslab.savetmpfiles

This property specifies what types of files are saved. The valid values include: all, none, prompts, inputs, pages, and recordings.

Note: Multiple valid values may be provided.

Values

Description

all

All file types will be saved. Note that com.genesyslab.savetmpfiles="all" is the same as
com.genesyslab.savetmpfiles= "prompts inputs pages recordings".

inputs

The following items will be saved:

  • Recognition/transfer/record/object requests

  • Recognition/transfer/record/object results

  • Content of the inline/generated grammars and the fetched DTMF grammars (together with the HTTP request/response to fetch the grammars)

The parameter values saved are internal values, and are not necessarily the same values provided by the VoiceXML application. For example, if the parameter value ranges from 0–1 in the VoiceXML page, it may be represented in the saved file as having a value ranging from 0–100 (for example, Confidence, Sensitivity, SpeedVsAccuracy).

none

Nothing will be saved. This value is the default.

pages

The following items will be saved:

  • VoiceXML pages

  • External JS scripts

  • External <data> fetches

  • HTTP request/response headers

prompts

The following items will be saved:

  • Prompt queue

  • Fetched prompts

  • HTTP request/response used to generate the prompts

The prompt queue may have been built across a sequence of pages, but only the <property> tag that is in effect when the prompt queue is flushed is included.

Some prompts may not be saved (for example, rtsp:// or prompts played by a third-party media server).

recordings

The recording from the <record> tag will be saved.

com.genesyslab.savetmpfilesmode

You can use this property to specify when the temp files will be written. The disposition of temp files is determined at session end by:

  • The com.genesyslab.onexit.keeptmpfiles property value.

  • The <exit> tag keeptmpfiles attribute (if it is specified).

Values | Description
immediate | The files will be written to disk immediately. This value is the default value.
delayed | The files will be stored in memory.

com.genesyslab.onexit.keeptmpfiles

This property specifies whether to keep temp files when the VoiceXML session ends. At least one temp file must have been saved.

Values | Description
true | All temp files on disk will be kept, and files in memory will be flushed to disk.
false | All temp files on the disk will be erased, and any files in memory will be discarded.

The saved temp files can be limited by using the GVP vxmli.safetmpfiles.max_bytes parameter.

Examples

Example 1

In this example, savetmpfiles equals all at the application-root page level (root.vxml). The result is that temp files:

  • Are enabled at the leaf pages.

  • Are saved for the session (all types of temp files).

  • Are written to disk immediately (default behavior).

  • Are not erased at the end of the session.

<vxml version="2.1" xmlns="...">
    <property name="com.genesyslab.savetmpfiles" value="all"/>
    ...
</vxml>

Example 2

In this example, page1.vxml would not be saved to disk (because savetmpfiles is set to none), while page2.vxml would be saved to disk (because the document-scope property is set to pages).

page1.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="none"/>
    <form id="a">
        <block>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

page2.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="pages"/>
    ...
</vxml>

Example 3

In this example, page1.vxml is saved to disk (because the document-scope property is set to all), while page2.vxml would also be saved to disk (because the savetmpfile property is set to all in the <goto> tag scope).

page1.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="all"/>
    <form id="a">
        <block>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

page2.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="none"/>
    ...
</vxml>

Example 4

In this example, when the application enters field f1 on page2.vxml, it will not perform any savetmpfiles for the input or the prompts. This is because when it enters the <field>, the property in that scope has been set to none. When you queue welcome.wav, the property is set to savetmpfiles, but since you would take the property at queue flush time, NGI will not save the prompts.

page1.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="all"/>
    <form id="a">
        <block>
            <prompt>
                <audio src="welcome.wav"/>
            </prompt>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

page2.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="all"/>
    <form id="a">
        <field name="f1" type="boolean">
            <property name= "com.genesyslab.savetmpfiles" value="none"/>
            <prompt>
                <audio src="please_say_your_name.wav"/>
            </prompt>
        </field>
    </form>
</vxml>

Example 5

In this example, when the application enters the field f1 on page2.vxml, it performs savetmpfiles for the prompts, but not the input parameters. This is because when it enters the <field>, the savetmpfiles property in that scope has been set to prompts.

page1.vxml

<vxml version= "2.1" xmlns="...">
    <property name="com.genesyslab.savetmpfiles" value="all"/>
    <form id="a">
        <block>
            <prompt>
                <audio src="welcome.wav"/>
            </prompt>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

page2.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="input"/>
    <form>
        <field name="f1" type="boolean">
            <property name= "com.genesyslab.savetmpfiles" value="prompts"/>
            <prompt>
                <audio src="please_say_your_name.wav"/>
            </prompt>
        </field>
    </form>
</vxml>

Example 6

In this example, both page1.vxml and page2.vxml are saved as a temp file. When page1.vxml is saved, it is saved to memory without writing to disk. When page2.vxml is saved, it is written to disk. When the application exits, because neither the property com.genesyslab.onexit.keeptmpfiles or the keeptmpfiles attribute is set, it takes on the default value of true, and page1.vxml is written to disk at that time.

page1.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="pages"/>
    <property name="com.genesyslab.savetmpfilesmode" value="delayed" />
    <form id="a">
        <block>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

page2.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="pages"/>
    <property name="com.genesyslab.savetmpfilesmode" value="delayed" />
    <form id="a">
        <block>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

Example 7

In this example, both page1.vxml and page2.vxml are saved as a temp file. When page1.vxml is saved, it is saved to memory without writing to disk. When page2.vxml is saved, it is written to disk. When the application exits, because the keeptmpfiles attribute of <exit> is set to false, page1.vxml is not written to disk, and page2.vxml is erased from disk.

page1.vxml

<vxml version= "2.1" xmlns="...">
    <property name= "com.genesyslab.savetmpfiles" value="pages"/>
    <property name="com.genesyslab.savetmpfilesmode" value="delayed" />
    <form id="a">
        <block>
            <goto next="page2.vxml"/>
        </block>
    </form>
</vxml>

page2.vxml

<vxml version= "2.1" xmlns="..." xmlns:vg="...">
    <property name= "com.genesyslab.savetmpfiles" value="pages"/>
    <property name="com.genesyslab.savetmpfilesmode" value="immediate"/>
    <form id="a">
        <block>
            Application exited successfully. Goodbye.
            <exit vg:keeptmpfiles="false"/>
        </block>
    </form>
</vxml>


Debugging

Document Sizes

The Interpreter offers a limit on VoiceXML pages, script files, and data source document sizes to allow for the prevention of rogue applications that may cause unacceptable memory use for large documents. When the limit is reached, the call will be rejected. The MCP parameters are:

  • vxmli.max_size.vxml_page

  • vxmli.max_size.script_file

  • vxmli.max_size.xml_data

For more information on these parameters, see the Genesys Voice Platform 8.1 Configuration Options Reference.


Maintainer Email

Debugging

Maintainer E-mail

This section explains how to e-mail log files to the Maintainer. This is one way to track what is happening with your VoiceXML application. To enable this feature, add the following to your VoiceXML page:

<meta name="MAINTAINER" content="yourname@yourserver.com"/>
<property name="com.genesyslab.maintainer.sendwhen" value="always"/>

If the MAINTAINER meta tag is defined at least once in your application, it will be used. If it is defined more than once, the value used will be the first one processed by the Interpreter. The content for the MAINTAINER meta tag should be the e-mail address that you want the information sent to.

On Windows installations, the Interpreter needs to be configured to use a local or remote SMTP server in order to be able to send maintainer e-mails. The SMTP server needs to be configured to allow relaying of messages for the Interpreter machine.

The e-mail contains the following information:

  • Logs generated from the <log> tag with destination maintainer.

  • Warnings and errors generated by the Interpreter.

  • Thrown events with a base of error. This feature is controlled by the configuration value specified by vxmli.maintainer.log_message.on_error, which defaults to true.

  • Metrics.

  • VoiceXML pages.

When the VoiceXML session ends, either implicitly or because of an <exit>, the property com.genesyslab.maintainer.sendwhen is examined:

  • always—Indicates that the Maintainer e-mail should be sent regardless of its contents.

  • never—Indicates that the Maintainer e-mail should not be sent.

  • on_message—Indicates the Maintainer e-mail should be sent if at least one <log> message has been added to the maintainer message lists, or a that vxml error occurred.

Notes:

  • At most, one e-mail is sent per session.

  • An e-mail will only be sent if a maintainer e-mail address has been specified at some point in the application.

  • The session ID will be logged in maintainer e-mail to identify the session that generated the log information.

  • The From address is specified by the platform configuration.


Debugging

Logging Content Definition

Logging provides the means to trace an application's functionality (for debugging) and performance. Logging can be setup with either the:

  • <Log> tag

  • __Log() function

__Log()

The Log() function allows the application to generate messages for debugging. The message will be logged to one or more files for viewing and to the Maintainer e-mail (if applicable).

Note: This function provides the same functionality as the <log> tag.

Signatures

There are two functions. The signatures are:

__Log( message, label, dest)

__Log( message)

Parameters

The parameters are the same as the <log> tag attributes.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form>
<block>
<script>
<!-- Should generate two messages:
- This is a log message
- This is a second log message
-->
var a = "This is a log message";
__Log( a );
__Log( "This is a second log message", "lbl_second_message", "metrics" );
</script>
</block>
</form>
</vxml>


_GetProperty() Function

Debugging

__GetProperty() Function

The __GetProperty() function enables the application to query the value of a property. The returned value is the value of the property that is in scope when the function executes, based on the VoiceXML rules of property scoping.

If this function is used to access a property that uses the expr attribute, it results in an infinite loop and an error.semantic is thrown.

Signature

string __GetProperty("Your property name")

Parameters

Parameter | Description
Your property name | This parameter specifies the property name to be retrieved.

Return Value

The function returns the value of Your property name.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Audio Tag"/>
<property name="bargein" value="true"/>
<property name="confidencelevel" value="0.45"/>
<form>
<property name="bargein" value="false"/>
<block>
Welcome to the Audio Example brought to you by Genesys.
<!-- should return false -->
<log>
The bargein value is
<value expr="__GetProperty("bargein")"/>
</log>
</block>
<block>
Playing a previously recorded sound.
<audio src="http://developer.gensyslab.com/libraries/audio/misc/wolfhowl.vox"/>
<goto next="#part2"/>
</block>
</form>
<form id="#part2">
<block>
Alternate Text can be played if the clip cannot be found.
<audio src="thankyou.vox" fetchtimeout="1s">
Sorry I couldn't find the audio file so I'm using
text to thank you instead.
</audio>
<!-- should return true -->
<log>
The bargein value is
<value expr="__GetProperty( "bargein" )" />
</log>
</block>
</form>
</vxml>


GVP Features

Overview

The following is a list of GVP VoiceXML features:

  • ASR Session Release

  • Call Progress Analysis

  • CTI Connector

  • Disallowing Transfer

  • Full-Call Recording

  • GVP Extensions

  • HTTP Cookies

  • PSTN Connector

  • Receiving External Messages

  • Recognizing Recorded Utterance

  • Sending External Messages

  • Vendor-Specific TTS Property Support

  • _GetInfo()

  • __ReleaseEngine()


GVP Features

ASR Session Release

The Next Generation Interpreter (NGI) supports automatic speech recognition (ASR) session release in two ways:

  • Implicitly

  • Manually

Implicit ASR Session Release

The NGI will release all open ASR sessions after a successful transfer where no speech grammars are loaded, if the asr.release_on_transfer option equals true. For details about the asr.release_on_transfer option, see the Genesys Voice Platform 8.1 Configuration Options Reference.

Manual ASR Session Release

The NGI will release an open ASR session when the ECMAScript function __ReleaseEngine() is called.


GVP Features

Call Progress Analysis

GVP, with the NGI, supports Call Progress Analysis (CPA) for outbound calls by using the Supplementary Services Gateway component and the PSTN Connector. Application developers can design their application to perform different actions, based on the CPA result. For example, when an answering machine is detected, the application can leave a voice message after the beep. To use this functionality, the com.genesyslab.externalevents.enable property must equal true. If this property equals true, CPA results are exposed to the application by using an extension to the NGI external messaging capabilities.

In an application, CPA results are received as VoiceXML events in the same way that external messages are received (specifically, by using the <send> and <receive> tags). The event name is externalmessage.cpa.xxxxx, where xxxxx is one of the supported results that are listed in the following table.

Notes:

  • Detection of voice (that is, a person has answered) does not generate an event. This means that the VoiceXML application should be authored with the assumption that it is interacting with a person.

  • The GVP 8.1.5 release does not contain the PSTN Connector component. Only GVP 8.1.2, 8.1.3, and 8.1.4 releases contain the PSTN Connector. See the Genesys Migration Guide for information about using PSTN Connector 8.1.4 with the GVP 8.1.5 release.

Event Name | Description | Supported by AudioCodes Media Gateway | Supported by Genesys Media Server | Supported by Genesys PSTN Connector using Dialogic | Supported by Genesys PSTN Connector using CPD Library
externalmessage.cpa.beep | Beep | No | Yes | No | No
externalmessage.cpa.busy | Busy | Yes | Yes | Yes | Yes
externalmessage.cpa.cadence | Cadence | No | No | Yes | Yes
externalmessage.cpa.fax.ced | Terminating fax | Yes | Yes | Yes | Yes
externalmessage.cpa.fax.cng | Originating fax | Yes | Yes | Yes | Yes
externalmessage.cpa.loopcurrent | Loop current | No | No | Yes | Yes
externalmessage.cpa.machine | Answering machine | Yes | Yes | Yes | Yes
externalmessage.cpa.modem | Modem | Yes | No | No | No
externalmessage.cpa.noanswer | No Answer | No | Yes | Yes | Yes
externalmessage.cpa.nodialtone | No dial tone | No | No | Yes | Yes
externalmessage.cpa.noringback | No ring back | No | No | Yes | Yes
externalmessage.cpa.ptt.voice.end | Push to talk end | Yes | No | No | No
externalmessage.cpa.ptt.voice.start | Push to talk start | Yes | No | No | No
externalmessage.cpa.silence | Silence | Yes | Yes | No | No
externalmessage.cpa.sit.general | Special Information Tones (SITs) indicate network conditions encountered in both the Local Exchange Carrier (LEC) and Inter-Exchange Carrier (IXC) networks. The tones alert the caller that a machine-generated announcement follows (this announcement describes the network condition). | Yes | Yes | No | Yes
externalmessage.cpa.sit.nocircuit | No circuit available | No | Yes | No | No
externalmessage.cpa.sit.notinservice | Not in service | No | No | No | Yes
externalmessage.cpa.sit.operatorintercept | Call intercepted by an operator | No | Yes | Yes | Yes
externalmessage.cpa.sit.reorder | Reorder (fast busy) tone indicates that the local switching paths to the calling office or equipment serving the customer are busy, or that a toll circuit is not available. | Yes | Yes | Yes | Yes
externalmessage.cpa.sit.unallocatednumber | Unallocated | No | No | No | Yes
externalmessage.cpa.sit.vacantcircuit | Circuit is vacant | No | Yes | Yes | Yes
externalmessage.cpa.unknown | Unknown | Yes | No | Yes | Yes

Notes:

  • Currently, the MCP only supports the AudioCodes media gateway as an external provider of CPA.

  • The Paraxip CPA has been tested only with CCXML.

The following sample VoiceXML shows usage:

Note: If a root page is to be used, the two <property> lines (line 5 and 6 in the example below) must be placed in the root page.

<?xml version="1.0"?>
<vxml Version="2.0" xmlns="http://www.w3.org/2001/vxml"
   xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
   <form id="test1">
      <property name="com.genesyslab.externalevents.enable" value="true"/>
      <property name="com.genesyslab.externalevents.queue" value="false"/>
      <catch event="externalmessage.cpa">
         <if cond="_event==’externalmessage.cpa.machine’>
            <goto nextitem="machine"/>
         <else/>
            <goto nextitem="failure"/>
         </ if>
      </catch>
      <field name="greeting" type="boolean">
         Hello. This is ABC Power calling for John Smith. Are you John Smith?
         <filled>
            <if cond="greeting">
               <goto nextitem="deliver_message"/>
            <else/>
               Thank you. Goodbye.
            <exit/>
            </if>
         </filled>
      </field>
      <block name="machine">
         This message is for John Smith.
      </block>
      <block name="deliver_message">
         Your account 123456789 is past due.
         The balance is $100.00.
         Please make a payment within 48 hours to avoid service interruption.
         Have a nice day.
         Goodbye.
         <exit/>
      </block>
      <block name="failure">
         <exit/>
      </block>
   </form>
</vxml>

Note: An environment with a CPA provider is required for this sample to work.


GVP Features

CTI Connector

GVP includes a CTI Connector component that exposes computer-telephony integration (CTI) functionality. This functionality provides access to call data during:

  • Call setup

  • Mid-call

  • Initiate transfer

  • Treatments (post initiate transfer)

  • Transfer complete

VoiceXML applications that access this functionality can be developed using:

  • Genesys Composer Voice (8.0.1 and later).

  • Third-party VoiceXML development tools.

For details, see the Sample VoiceXML Applications.


GVP Features

Disallowing Transfer

The GVP disallow transfer functionality is a feature that you may want to use if your application will be executing VoiceXML pages from an untrusted source.

The ability to perform a transfer is controlled by a hidden variable. Initially, this hidden variable is set to true. It can be set to false using platform configuration. The following ECMAScript functions are available for accessing and manipulating the hidden variable:

  • session.com.genesyslab.getTransferAllowed()—This function returns the value of the hidden variable (either true or false). If the value is true, transfers are enabled for the session. If the value is false, transfers are not enabled for the remainder of the session.

  • session.com.genesyslab.setTransferAllowed(false)—This function sets the value of the hidden variable. The only valid value is false. When the value is false, transfers are not allowed for the remainder of the session.

Note: Once transfer is disabled, it cannot be enabled (reset to true) for the remainder of the call.


GVP Features

Full-Call Recording

Full-Call Recording (FCR) provides advanced VoiceXML application-data and call-audio recording (logging). Logs are important for application analysis and debugging. With this functionality you can log:

  • ASR-performance data (see Debugging)

  • Call-flow data (see Debugging)

  • Call-audio data

To implement FCR, the following GVP features are required:

  • Support for multiple audio-channel recording

  • Support for multiple simultaneous recording

Multiple Audio-Channel Recording

To record the entire interaction between the user and the application, the platform must be able to mix the input and output audio channels into a single audio file. The GVP's recording functionality has been extended to record:

  • User-input

  • Application-output

  • User-input and application-output

Multiple Simultaneous Recording

The GVP recording functionality has been extended to allow simultaneous recording, so the user can make an application-level recording at the same time that the platform records the entire call. FCR takes place in the background, while a VoiceXML page is executing. If the VoiceXML page includes the <record> tag, the platform must be able to make multiple simultaneous recordings.

Usage

To implement FCR, the <log> tag was extended. This tag allows the developer to control the background recording within executable content. Because <log> is not a form input item, it does not require the complete recording to be collected before moving on to the following VoiceXML tag. Therefore, <log> can be used to start a recording, and then execution of subsequent VoiceXML can continue (and be recorded) until another <log> terminates the background recording or the call is disconnected.

Format

Recorded files are named based on the call ID of a call, in the format callrec.<call ID>.<timestamp in YYMMDDhhmmss format>.<file extension>. Recorded files are stored in a subdirectory of the directory specified by the directory directive described below. The subdirectory is also named based on the call ID in form callrec.<call ID>. Note that the creation of this subdirectory can be overridden using the absolute parameter to the directory directive.

Syntax

To control FCR within a VoiceXML application, set the dest attribute of the <log> tag to calllog, anywhere that executable content is allowed. This value tells the platform that the contents of the <log> tag are commands, rather than text that should be logged. In the body of the tag, list the desired commands, separated by newlines/linefeeds. For example:

<log dest="calllog">
   <Your command>
   [commands;]
</log>

where <Your command> may be one of the following:

  • directory <Your local-directory name> [absolute];

  • enable callrec [recsrc=<in|out|mixed>] [type=<Your MIME-type>];

  • disable callrec;

  • keep-files <true|false>;

directory <Your local-directory name>;

This command specifies the directory in which the call recordings will be collected. If used, this command must appear in the first instance of a <log> tag with dest="calllog". Otherwise, it will be ignored because files cannot be moved after they have already been created (see Known Issues and Recommendations).

<Your local-directory name> specifies the relative path to the full-call recording root path that is configured with the calllog.directory parameter. By default, calllog.directory is set to $InstallationRoot$\callrec\<call id>.

The given directory will be treated as a root directory. A subdirectory, with a name based on the session ID of each call, will be created and used to store actual files for each call. If it is desired that files be placed in the root directory without the use of a subdirectory, specify absolute as the last token on the directory line.

Note: If this command is not given, the default local directory, which is defined by the calllog.directory parameter in the MCP configuration, will be used.

enable callrec [recsrc=<in | out | mixed>] [type=<Your MIME-type>];

This command enables call recording, or restarts call recording (in a new recording file) if it has already been started. All audio data on the call from this point forward will be recorded into the newly opened recording file. This will continue until the call terminates, or a subsequent enable callrec command is issued, or until a disable callrec command is issued.

If recsrc=<in|out|mixed> is specified, it forces call recording to record the specified audio paths:

  • in (from user)

  • out (to user)

  • mixed (combination of audio going from and to user)

Notes:

  • The default value is mixed.

  • If outbound calls are made, audio paths continue to be collected from and/or to the user (the original caller) only, regardless of the paths that are actually joined and interacting. If recsrc=in, only the original caller is recorded, even if a callee and the platform are joined and interacting, and the original caller is not joined. In this case, only audio from the original caller (breathing, humming, and so on) will be recorded. If recsrc=out, the only audio recorded is what the original caller hears, which will be silence if only the callee and the platform are joined and interacting. Similarly, if recsrc=mixed, only the original caller and the audio heard by the original caller will be recorded.

  • If type=<Your MIME-type> is used, the given MIME-type will be used to determine the file type used for the recording. The list of MIME-types supported is the same as defined for the <record> tag.

disable callrec;

This command disables call recording and terminates recordings in progress. Audio will be recorded until the point that this command is executed.

keep-files <true | false>;

This command controls whether files on the GVP server are maintained after the call is terminated. If set to true, files will be maintained, otherwise, they will be deleted.

Note: The default value is true. This command may be issued at any time while a call is active. The purpose of this capability is to keep files only if the call ends in an error condition. For example, if a call is disconnected due to excessive <nomatch> events, the <nomatch> event handler can perform a <log gvp:dest="calllog">keep-files true;</log> to retain temporary files on the server.

Example

In the following example, call recording (of both caller and platform) is turned on, with the directory and MIME-type specified. This will record the call during field1. After that, the call recording is turned off, so field2 will not be recorded.

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml" xmlns:gvp=http://www.genesyslab.com/2006/vxml21-extension>
<form>
<!-- This turns on call recording.
Any input/output in the next field will be recorded
Note: For W2K, use directory /GVP/mp/callrec instead
-->
<block>
<log gvp:dest="calllog">
directory /usr/local/phoneweb/callrec;
enable callrec recsrc=mixed type=audio/basic;
</log>
</block>
<field name="field1" type="boolean">
<prompt>
Say yes or no.
</prompt>
<filled>
You said <value expr="field1"/>.
</filled>
</field>
<!-- This turns off call recording -->
<!-- No input/output in the next field will be recorded -->
<block>
<log gvp:dest="calllog">
disable callrec;
</log>
</block>
<field name="field2" type="boolean">
<prompt>
Say yes or no.
</prompt>
<filled>
You said <value expr="field2"/>.
</filled>
</field>
</form>
</vxml>

Known Issues and Recommendations

It is not valid to have multiple commands on a single line, delimited by a semicolon. The semi-colon is not a valid command delimiter; only a line break is a valid command delimiter. The following example shows invalid syntax:

<log gvp:dest="calllog">
directory /usr/local/phoneweb/callrec;enable callrec recsrc=mixed type=audio/x-wav;keep-files true;
</log>

The following example shows valid syntax:

<log gvp:dest="calllog">
directory /usr/local/phoneweb/callrec
enable callrec recsrc=mixed type=audio/x-wav
keep-files true
</log>

If the <value> tag is used to insert variables to specify a FCR directory, the behavior may not be correct. For example:

<block>
<var name="path" expr="'/usr/local/phoneweb/test'"/>
<log gvp:dest="calllog">
enable callrec recsrc=mixed type=audio/basic;
directory <value expr="path"/> absolute;
</log>
</block>

If this is executed, the user expects the recorded file to be saved in /usr/local/phoneweb/test. However, since spaces around the <value> tag are stripped, the second command is currently evaluated to directory/usr/local/phoneweb/testabsolute, and the recorded file is saved in /usr/local/phoneweb/testabsolute. As a work around, make sure that a space is specified within the <value> expression, either at the end of the directory path variable, or at the beginning of any information that follows the directory path. For example:

<block>
<var name="path" expr="'/usr/local/phoneweb/test'+' '"/>
<log gvp:dest="calllog">
enable callrec recsrc=mixed type=audio/basic;
directory <value expr="path"/> absolute;
</log>
</block>
...
<block>
<var name="path" expr="'/usr/local/phoneweb/test'"/>
<var name="absolute" expr="' absolute'"/>
<log gvp:dest="calllog">
enable callrec recsrc=mixed type=audio/basic;
directory <value expr="path"/> <value expr="absolute"/>;
</log>
</block>

Because of prompt queueing, multiple FCR commands will be processed together before processing the prompts in between. This may lead to unexpected results. For example:

<block>
<log gvp:dest="calllog">
enable callrec recsrc=mixed type=audio/x-wav;
directory /usr/local/phoneweb/test/;
</log>
Thank you for calling.
<log gvp:dest="calllog">
disable callrec;
</log>
<log gvp:dest="calllog">
enable callrec recsrc=mixed type=audio/basic;
directory /usr/local/phoneweb/test/;
</log>
</block>

If this is executed, the three log tags are processed first, and then the prompt is played. Therefore, the recording from the first log tag will be very short and will contain no audio. The prompt Thank you for calling will actually be recorded in the third log tag. The reason for this behavior is that prompts are queued until the next input collection or until the page exits.

Currently, setting recsrc=out is not supported. The current behavior for this setting is the same as for recsrc=mixed.

If it is necessary to enable FCR regardless of whether the loglevel property is set, the use of the level attribute of <log> is recommended. For example:

<log gvp:dest="calllog" level="0">
enable callrec recsrc=mixed type=audio/basic;
directory /usr/local/phoneweb/test/;
</log>

If any outbound calls occur during a call that is being recorded, the recording will continue to mix the audio from the original caller and the platform output, with any callees ignored.

FCR may not work properly in the Talk and Listen Toggling (TLT) connection scenario.

The input/output mixing that is required for FCR will have performance implications. However, since FCR is generally used on either prototype systems or in a limited (spot check) fashion on production systems, this performance impact will likely be acceptable.

In future releases, additional calllog commands will be added to provide the developer greater application-level control over call event collection, including enabling/disabling collection of logging information, billing information, application-level recordings, and so on, on a call-by-call basis. Collected information will be stored in a separate directory for each call.

Typically, the prompts and audio files that are prior to the enable callrec command are recorded. This is due to the processing order of the <log> tag within the prompt-queuing feature. It is possible to avoid recording prompts and audiofile before the <log> tag. The following code shows a workaround that is available in VP-VADS for disabling the prompt queuing feature.

Note: When a dummy field is used, the prompts are not queued (they are played to the user immediately).

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml"
xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension" >
<property name="bargein" value="false"/>
<form>
<block>
<prompt>
This is to test Genesys
</prompt>
</block>
<field name="ImmediatePlaybackTmpField" type="number">
<property name="inputmodes" value="dtmf"/>
<property name="timeout" value="0s"/>
<filled>
<goto next="#test" />
</filled>
</field>
<catch event="nomatch noinput">
<goto next="#test" />
</catch>
</form>
<form id="test">
<block>
<log gvp:dest="calllog">
enable callrec recsrc=mixed type=audio/wav;
directory C:\testing\fcr absolute;
</log>
</block>
<field name="field1" type="boolean">
<prompt>
Say yes or no
</prompt>
<filled>
You said this <value expr="field1"/
</filled>
</field>
<field name="field2" type="boolean">
<prompt>
Say yes or no
</prompt>
<filled>
You said this <value expr="field2"/>
</filled>
</field>
<block>
<log gvp:dest="calllog">
disable callrec
</log>
</block>
</form>
</vxml>

If disable callrec is used with the prompt-queuing feature enabled, the last prompts may not get recorded. This is due to the processing order of the <log> tag within the prompt-queuing feature.

You cannot use ../ as part of the relative path.

When the Full-Call Recording <log> command is encountered after a call is finished, the Interpreter generates an error.semantic event. The _message associated with this situation is ”call previously disconnected; FCR command ignored”. The VoiceXML code in the error.semantic handler can check the value of the _message shadow variable to handle the different types of error.semantic events accordingly.


Getting Started with GVP Extensions

GVP Features

GVP Extensions

Specifying the GVP Namespace

To use GVP extensions in your applications, your VoiceXML pages must declare the GVP extension namespace as follows:

<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml"
 xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension"
>

The xmlns:gvp references the GVP namespace, and stating that any tag with gvp: in front of it is from the GVP namespace as shown below:

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml"
      xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
<var name="a" expr = "1"/>
<var name="formName" expr = "'form3'"/>
<form id="form1">
   <var name="b" expr="'block5'"/>
   <block name = "block1">
      <log>testing goto</log>
      <prompt>
         Good morning GVP!
      </prompt>
      <goto next="SomeOtherPage.vxml"
               gvp:fetchaudiominimum="5s"
               fetchtimeout="100s"
               fetchaudio="audio/brahms2.wav"/>
   </block>
</form>
</vxml>


ECMAScript Functions

GVP Features

HTTP Cookies

The NGI supports ECMAScript functions to enable VoiceXML applications to set and get HTTP cookies. The NGI relies on the Fetching Module to manage HTTP cookies that belong to a session object. Since the Fetching Module is also used in other parts of the MCP, any HTTP fetches initiated through the Fetching Module that belong to the same call session will share the same cookie jar. Therefore, the cookie retrieved from HTTP requests made outside of the NGI (for example, media files and grammar) will also be available to the VoiceXML session.

__SetCookie( 'cookie_value' )

This function belongs to the session object, and enables the user to set HTTP cookies to the cookie jar of the current session object. The cookies will be used in subsequent HTTP requests according to RFC 2109.

The cookie_value must be in the format of <cookie 1>, <cookie 2>, ..., <cookie n>, where the format of cookie is <name>=<value>; [Version=<version>] [; Comment=<comment>]; Domain=<domain> [; Expires=<expires>][; Max-Age=<max-age>][; Secure] ; Path=<path>.

The following attributes are mandatory (attributes are defined in RFC 2109):

  • Cookie name and value

  • Domain

  • Path

When called, the cookies are loaded to the session’s cookie jar. Since the cookies are provided by the user and are not associated to a particular HTTP response, the NGI will not reject cookies based on the domain and path.

__GetCookie()

This function belongs to the session object, and enables the user to obtain the HTTP cookies in the cookie jar of the current session object. The string returned by this function can be provided to the GVP.setCookie () function.

The format of the returned string is <cookie 1>, <cookie 2>, ..., <cookie n>, where the format of cookie being <name>=<value>; [Version=<version>] [; Comment=<comment>]; Domain=<domain> [; Expires=<expires>][; Max-Age=<max-age>][; Secure] ; Path=<path>.

The attributes are defined in RFC 2109.

When called, the contents of the cookie jar of the current session will be returned to the user.

Example use case:

  1. Alice calls into GVP, and the call is handled by the VoiceXML application. The HTTP servers involved in the call return a number of cookies.

  2. Alice hangs up. The VoiceXML application uses the __GetCookie() function to retrieve all cookies that belong to Alice, and stores the returned cookie string to a database.

  3. Alice calls into GVP again. When the VoiceXML application identifies Alice, it retrieves the previously stored cookie string and uses the __SetCookie() function to restore them to the current call session.

Notes:

If the original Set-Cookie header in the HTTP response does not specify the Domain or the Path attributes, they will be given a default value. The Domain defaults to the request-host, and the Path defaults to the request URL that generated the Set-Cookie response, up to, but not including the right most /. This is done according to RFC 2109.

The __GetCookie() function does not return the Max-Age attribute in the cookie string. If the Max-Age attribute is specified in the original Set-Cookie header, it will be converted into an Expiry attribute, which allows proper cookie expiry handling when the cookie string is used in __SetCookie().


GVP Features

PSTN Connector

GVP 8.1.2, 8.1.3, and 8.1.4 includes a PSTN Connector component that supports PSTN cards (for example, Dialogic boards). The GVP 8.1.5 release does not contain the PSTN Connector component. See the Genesys Migration Guide for information about using PSTN Connector 8.1.4 with the GVP 8.1.5 release.

For more information about the PSTN Connector, see the Genesys Voice Platform 8.1 Deployment Guide.

The PSTN Connector provides the following functionality with NGI:

Passing Redirecting Number

PSTN Connector provides the redirecting number by using the SIP History-Info header. NGI exposes it by using the session.connection.redirect.array session variable as defined in RFC5552.

Passing UUI Data

NGI exposes UUI data from the PSTN Connector by using the session.connection.aai session variable. The aai and aaiexpr attributes of the VoiceXML <transfer> element are also supported with the PSTN Connector to pass UUI data to the callee.

Passing Screening/Information/Presentation Indicator

PSTN Connector provides the indicator by using the SIP remote-party-ID header as defined in the draft-ietf-si-privacy-o4.txt specification. NGI exposes it by using the session.connection.protocol.sip.headers["remote-party-id"] session variable. For example:

Remote-Party-ID: <sip:9059683348@138.120.84.32>;party=calling;privacy=off;screen=yes;screen-ind=1;npi=1;ton=2

Where:

sip:9059683348@138.120.84.32 is the calling party number (must be the same as in the FROM: header).
privacy is set based on the presentation indicator.
screen is set based on the screening indicator.
screenind is the screening indicator value for the calling party number.
npi is the numbering plan identification value for calling party number.
ton is the type of number value for calling party number.

Note: The URI value sip:9059683348@138.120.84.32 must have the value of the FROM: header.

Transfers

This table lists transfers supported by the PSTN connector and the NGI, and the attributes of the transfer tag at the VXML application level in order to execute the transfer.

PSTN Connector Transfer | gvp:method attribute | type attribute | gvp:connectwhen attribute | whisper transfer support | UUI support
Bridge | BRIDGE | blind/consultation/bridge | immediate/answered | Yes | Yes
AT&T Courtesy Transfer (inband) | ATTCOURTESY | blind | Not applicable | No | Yes
AT&T Consult and Transfer (inband) | ATTCONSULT | blind/consultation | Not applicable | No | No
AT&T Conference and Transfer (inband) | ATTCONFERENCE | blind/consultation/bridge | Not applicable | Yes | No
AT&T Courtesy Transfer (out-of-band) | ATTOOBCOURTESY | blind | Not applicable | No | Yes
AT&T Consult and Transfer (out-of-band) | ATTOOBCONSULT | blind/consultation | Not applicable | No | Yes
AT&T Conference and Transfer (out-of-band) | ATTOOBCONFERENCE | blind/consultation | Not applicable | Yes | Yes
Single B channel blind transfer over ISDN for NEC NEAX 61 switch | NEC61ISDN | blind | Not applicable | No | Yes
Two B-Channel Transfer (TBCT) | REFERJOIN | blind/consultation | immediate/answered | Yes | Yes
Release Link Trunk Transfer (RLT) | REFERJOIN | blind/consultation | immediate/answered | Yes | Yes
Explicit Call Transfer (ECT) | REFERJOIN | blind/consultation | immediate/answered | Yes | Yes
Hookflash Transfer | REFERJOIN | blind/consultation | Not applicable | Yes | Yes
Q.SIG Call Transfer and Path Replacement | REFERJOIN | blind/consultation | immediate/answered | Yes | Yes

Notes:

  • REFERJOIN is "REFER with Replaces".

  • For TBCT/RLT/ECT/QSIG transfers that use REFERJOIN:

    • When type=blind and connectwhen=immediate, the REFER is sent after the outbound call receives alerting.

    • For any other combination, REFER with Replaces is sent after the outbound call receives connected.


GVP Features

Receiving External Messages

GVP supports receipt of external messages by a voice application using the <receive> tag. With this tag, a VoiceXML application can be configured to:

  • Receive external messages asynchronously or synchronously. For details on configuring this functionality, see the com.genesyslab.externalevents.enable property.

  • Queue or discard external messages. For details on configuring this functionality, see the com.genesyslab.externalevents.queue property.

Receiving External Messages Asynchronously

To receive external messages asynchronously, an application requires an externalmessage event handler. The event handler must be declared within the appropriate scope. The user-defined <catch> tag handler is selected using the algorithm described in the Voice Extensible Markup Language (VoiceXML) Version 2.0 specification.

If the payload of an external message includes an event name, the name is appended to the name of the event that is thrown to the application, separated by a period (for example, externalmessage.ready). This allows applications to handle external messages using different event handlers.

Asynchronous external messages are processed in the same manner that a disconnect event is handled in the VoiceXML Version 2.0 specification. Events are dispatched to the application serially. Since the NGI only reflects the data associated with a single external message at a time, it is the application's responsibility to manage the data associated with each external message once that message has been delivered. The following example demonstrates asynchronous receipt of an external message. The catch handler copies the reflected external message into an array at application scope.

<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <property name="com.genesyslab.externalevents.enable" value="true"/>
   <var name="myMessages" expr="new Array()" />
   <catch event="externalmessage">
      <var name="lm" expr="application.lastmessage$"/>
      <if cond="lm.contenttype == 'text/xml' || lm.contenttype == 'application/xml'">
         <log>received XML with root document element
            <value expr="lm.content.documentElement.nodeName"/>
         </log>
         <elseif cond="typeof lm.content == 'string'"/>
            <log>received
              <value expr="lm.content"/>
            </log>
         <else/>
            <log>received unknown external message type
               <value expr="typeof lm.content"/>
            </log>
      </if>
      <script>
         myMessages.push({'content' : lm.content, 'ctype' : lm.contenttype});
      </script>
   </catch>
   <form>
      <field name="num" type="digits">
         <prompt>
            pick a number any number
         </prompt>
         <catch event="noinput nomatch">
            sorry. didn't get that.
            <reprompt/>
         </catch>
         <filled>
            you said <value expr="num"/>
            <clear/>
         </filled>
      </field>
   </form>
</vxml>

Receiving External Messages Synchronously

To receive external message synchronously, set the com.genesyslab.externalevents.enable property to false and the com.genesyslab.externalevents.queue property to true, and use the <receive> tag to pull messages from the queue.

Note: <receive> blocks until an external message is received or the timeout specified by the maxtime attribute is exceeded.


GVP Features

Recognizing Recorded Utterance

GVP enables VoiceXML applications to be run using recorded audio as speech input. Two examples for this feature are tuning applications, and running maintenance checks on a deployed application.

Tuning Applications

To tune an application to improve recognition accuracy, you must assess performance before and after various tuning adjustments. However, to be sure that any changes in performance come from the adjustments, it is important that all other factors are held constant—including the input utterances. Using this feature, you can reuse a set of utterances (either recorded by testers from a call script, or recordings of actual callers) as input to the application while you make changes to the grammars and properties.

Running Maintenance Checks

Once an application is deployed, you do not want to wait for negative feedback from your users to find out something is not working properly. Using this feature, you can create test scripts that periodically call the application. You can check the results of these calls, to make sure that the ASR and your grammars are correctly accepting speech input.

Getting Started

For each <field> in your application, if you want the recognizer to use recorded audio as speech input, specify the audio source with the audioinexpr attribute. Otherwise, the recognizer will wait for speech input to come from the caller, as usual.

This attribute should specify one of the following sources:

  • The URI of an audio file (see supported audio formats for this feature).

  • The name of a <record> variable, if one was recorded earlier in the application.

  • The shadow variable $.utteranceaudio from an earlier <field>, if saveutterance is enabled.

Note: You can put audio files on the GVP platform and reference them with audioinexpr="'file:///<The file path>'". Or, if you put the audio files in GVP's built-in audio directory (or any subdirectory of audio), you can reference them with audioinexpr="'builtin:<Your file path>,<Your relative to audio directory>'".

Usage

The following three examples that show <field>s receiving their input from different sources of recorded audio.

Note: A caller will not be able to hear the recorded audio input.

Example 1—Speech input from an audio file

The recognition results are sent to a script that processes them, so the application's recognition performance can be assessed. This example is only to illustrate the use of this feature; no implementation is given for stats.jsp.

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <meta name="maintainer" content="<yourname>@<yourserver>.com"/>
   <meta name="application" content="Recorded Audio Input 1"/>
   <property name="bargein" value="false"/>
   <form>
      <!-- The caller will not hear the input -->
      <field name="field1" audioinexpr="'http://developer.gvp.com/libraries/audio/
                                         common/goodbye.vox'">
         <prompt>
            Please say goodbye.
         </prompt>
         <grammar xml:lang="en-US" version="1.0" root="ROOT"
                  xmlns="http://www.w3.org/2001/06/grammar" type="application/srgs+xml">
            <rule id="ROOT" scope="public">
               <item> goodbye </item>
            </rule>
         </grammar>
         <nomatch>
            <var name="field1" expr="'nomatch'"/>
            <submit next="stats.jsp" namelist="field1"/>
         </nomatch>
         <noinput>
            <var name="field1" expr="'noinput'"/>
            <submit next="stats.jsp" namelist="field1"/>
         </noinput>
         <filled>
            <var name="confidence" expr="field1$.confidence"/>
            <submit next="stats.jsp" namelist="field1 confidence"/>
         </filled>
      </field>
   </form>
</vxml>

Example 2—Speech input from the result of an earlier <record>

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <meta name="maintainer" content="<yourname>@<yourserver.com>"/>
   <meta name="application" content="Recorded Audio Input 2"/>
   <property name="bargein" value="false"/>
   <form>
      <record name="recordaudio" beep="true" dtmfterm="true">
         <prompt>
            At the tone, please say goodbye, then press the pound key.
         </prompt>
      </record>
      <!-- Use recording from above as input here -->
      <!-- The caller will not hear the input -->
      <field name="field1" audioinexpr="recordaudio">
         <prompt>
            Please say goodbye.
         </prompt>
         <grammar xml:lang="en-US" version="1.0" root="ROOT"
                  xmlns="http://www.w3.org/2001/06/grammar" type="application/srgs+xml">
            <rule id="ROOT" scope="public">
               <item> goodbye </item>
            </rule>
         </grammar>
         <nomatch>
            I didn't understand your recording.
            <exit/>
         </nomatch>
         <noinput>
            I didn't hear your recording.
            <exit/>
         </noinput>
         <filled>
            I heard your recording say <value expr="field1"/>.
         </filled>
      </field>
   </form>
</vxml>

Example 3—Speech input from the recording of the caller's earlier input

This example uses the tag format that is supported by OSR (<tag>command='goodbye';</tag>). If you want to run this example with a different ASR engine, confirm the format supported by that engine, and modify the below tag content if necessary.

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <meta name="maintainer" content="<yourname>@<yourserver.com>"/>
   <meta name="application" content="Recorded Audio Input 3"/>
   <property name="ASRENGINE" value="SPEECHWORKS"/>
   <property name="bargein" value="false"/>
   <form>
      <grammar xml:lang="en-US" version="1.0" root="ROOT"
               xmlns="http://www.w3.org/2001/06/grammar" type="application/srgs+xml">
         <rule id="ROOT" scope="public">
            <item> goodbye <tag>command='goodbye';</tag> </item>
         </rule>
      </grammar>
      <field name="field1" saveutterance="true" slot="command">
         <prompt>
            Please say goodbye.
         </prompt>
         <catch event="nomatch noinput">
            Try again.
            <reprompt/>
         </catch>
         <filled>
            I recognized goodbye with a confidence of
            <value expr="field1$.confidence"/>.
            Let's make sure I'm a consistent recognizer.
         </filled>
      </field>
      <!-- Use recording of caller's last input as input here -->
      <!-- The caller will not hear the input -->
      <field name="field2" audioinexpr="field1$.utteranceaudio" slot="command">
         <prompt>
            Please say goodbye.
         </prompt>
         <filled>
            I recognized goodbye with a confidence of
            <value expr="field2$.confidence"/>.
            <if cond="field1$.confidence == field2$.confidence">
               See, I am a consistent recognizer!
            <else/>
               <!-- This should not happen -->
               I guess I'm not a consistent recognizer.
            </if>
         </filled>
      </field>
   </form>
</vxml>

Notes:

  • A caller will not be able to hear the recorded audio input.

  • Any speech/background noise coming into the phone will be ignored.

  • If the attribute is empty or contains an empty expression, it will be ignored and the recognizer will listen for input from the caller.

  • If the recorded audio input cannot be recognized, the appropriate event will be thrown (nomatch or noinput). The application is responsible for providing logic in the <nomatch> and <noinput> handlers to leave the field in this case, by hanging up or exiting, by transitioning to another field/form/document, by setting the field variable or cond attribute, and so on. If no such logic is provided (for example, if the handlers simply prompt to retry recognition), an infinite loop occurs, since the same input will be used each time.

    See Examples 1 and 2 for an illustration of leaving the field if a nomatch or noinput occurs, to prevent infinite looping. In Example 3, a nomatch or noinput will never occur in the field that uses RRU, since the input is the recognized utterance from the first field. Therefore, there is no need for nomatch or noinput handlers in that field.

    If you would like to collect input from the live caller if the RRU is unsuccessful, you may try something similar to this:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
<property name="bargein" value="false"/>
<form>
   <var name="autoinput" expr="'http://developer.genesyslab.com/libraries/audio
        /horoscopes/zodiacs.vox'"/>
   <field name="input" audioinexpr="autoinput">
      <prompt>
         Please say test.
      </prompt>
      <grammar xml:lang="en-US" version="1.0" root="ROOT"
         xmlns="http://www.w3.org/2001/06/grammar"
         type="application/srgs+xml">
         <rule id="ROOT" scope="public">
            test
         </rule>
      </grammar>
      <nomatch>
      <assign name="autoinput" expr=""/>
      Sorry, I didn't understand the automated input.
      Now I'll listen to the live caller.
      <reprompt/>
      </nomatch>
      <filled>
         You said <value expr="input"/>.
      </filled>
   </field>
</form>
</vxml>

This feature works both with bargein enabled and disabled, but Genesys recommends that bargein be disabled to ensure that all queued prompts are played properly.

Summary

The following is the <field> attribute that is used to indicate that speech input is coming from recorded audio, and what the source of that audio is:

Attribute

Possible Values

audioinexpr

Full http URI, for example:
audioinexpr="'http://blah.com/audio/utterance.vox'"
Full file URI (audio on the platform), for example:
audioinexpr="'file:///usr/local/phoneweb/blah/utterance.vox'"
Relative URI, for example:
audioinexpr="'audio/utterance.vox'"
Reference to builtin audio on the platform, for example:
audioinexpr="'builtin:test1/utterance.vox'"
<record> field variable, for example:
audioinexpr="recording1"
$.utteranceaudio shadow variable, for example:
audioinexpr="field1$.utteranceaudio"


GVP Features

Sending External Messages

GVP supports sending external messages by a voice application using the <send> tag. External messages can be sent:

  • Synchronously

  • Asynchronously

This feature is implemented using SIP INFO messages.


Vendor Specific TTS Property Support

GVP Features

Vendor-Specific TTS Property Support

Next-Generation Interpreter (NGI) supports vendor-specific text-to-speech (TTS) properties, as follows:

  • When TTS is queued for playback, all properties that are prefixed with com.<your vendor name>.tts are available.

  • The properties are passed to the platform when the prompt is played.

Refer to the particular vendor documentation for a list of TTS properties.


GVP Features

_GetInfo()

This function belongs to the session object, and it returns session and platform information. For example, it can return the host IP address, the host name, or the URL of currently running page.

Signature

_GetInfo('host_ip' | 'host_name' | 'running_uri')

Parameters

One of host_ip, host_name, or running_uri is required. If one of these parameters is not provided, an error.semantic will be thrown.

Parameter | Description
host_ip | The return value is the platform IP address that was determined at system startup. If the system has multiple IP addresses, the return value will be one of these addresses, but it will not be 127.0.0.1.
host_name | The return value is the platform hostname that was determined at system startup. The return value may be either the simple hostname or the fully qualified domain name (FQDN).
running_uri | The return value is the URI of the current VoiceXML page. If the original URI was redirected, the result will reflect the redirected value.


__ReleaseEngine

GVP Features

__ReleaseEngine()

This function belongs to the session object, and it is used to release an automatic speech recognition (ASR) session or sessions. It is useful if:

  • You have fewer ASR engines than you have IVR ports.

  • You know that you can release the ASR engine because it is no longer being used, but the call is not over. For example, after all voice input has been collected, the ASR engine is no longer required. Leaving the ASR engine session open is not resource efficient.

Signature

__ReleaseEngine('engine_name')

Parameters

Parameter

Description

engine_name

(Optional) If this parameter is included, it provides the ASR engine_name to be released. The parameter can be:

  • A string—That is the ASR engine name (for example, abc_engine).

  • A variable—That contains the ASR engine name (for example, var_ASREngineName).

If this parameter is not provided (for example, the function is called as __ReleaseEngine()), all open ASR engines are released.

If the specified engine_name is not open or is not valid, the request is ignored.

Known Issues and Recommendations

If a request to release an ASR session is not complete and a request for speech resources is made, multiple ASR licenses may be consumed. To minimize this, code the application to perform tasks that give the release time to complete before another recognition begins. For example, before another fetch (goto, submit, data), or before flushing the prompt queue.

This function can have the effect of freeing the associated ASR license on the MRCP Server. Check with your MRCP ASR vendor for details on how licenses are freed and whether this is compliant with the vendor license agreements.


Best Practices

Best Practices Overview

The following topics summarize some of the techniques that can be used to develop efficient VoiceXML applications.

  • Careful Caching of Resources.

  • Reduce the number of page transitions (that do not collect any caller inputs).

  • Reduce the number of ECMAScripts used.

  • Reduce the number of global variables.

  • Reduce the usage of inline ECMAScripts.

  • Reduce the time required to compile the VoiceXML page.

  • Production deployment.

  • Ensure that Expires header is present for all external grammars used by the ASR server.

  • Pre-compile grammars when possible.

  • Avoid frequently changing the application root.

  • Avoid keeping audio files on the GVP servers.

  • Adjust timeout to a reasonable duration depending upon the data being collected.

  • Resolve ambiguity—ideally one call input should match only one grammar.

  • Avoid using the <break> tag for pause between audio prompts.

  • Avoid interleaving of small TTS prompts with audio prompts.

  • Understand prompt queuing.

  • Use of grammars inside transfers.

  • Tune grammars and prompts for speech applications.

  • Load test applications before going live.

Certain techniques will be more effective than others depending upon the nature of the application being developed. Genesys highly recommends that early benchmarking of smaller representative applications be conducted, which will indicate the kind of performance improvements that can be achieved.


Best Practices

Careful Caching of Resources

VoiceXML provides flexible control of the caching of static pages and ancillary files, as well as control over when ancillary files are fetched from the application web server. This behavior is controlled by using VoiceXML properties and attributes. Default behavior is set by the Interpreter itself (in the case of NGI, by the defaults.vxml file), and it can be modified using VoiceXML's rules for scoping (that is, within an application, document, or block) using property tags, and controlled for particular ancillary files (for example, grammars and audio files) by using an attribute for the relevant tag.

Caching Summary with NGI

The application server maintainer/content provider can provide guidelines for content expiry using the Cache-Control or Expires HTTP response headers. The Cache-Control header will override the Expires header if both are provided.

If an object is "fresh", it is given directly to the client. If it is "stale", the Fetching Module will make an 'If-Modified-Since' request for it.

The application developer can deterministically control the caching behavior of application resources using the maxage and maxstale attributes for each URI-related VoiceXML tag. These values are passed in the Cache-Control request header.

Using Maxage/Maxstale

VoiceXML allows the author to control this caching policy for each use of each resource. Caching is governed by the following properties and related attributes, which replace the caching property/attributes from VoiceXML 1.0. They determine how to fetch the resource: from the local cache, or from the remote server.

  • the audiomaxage/audiomaxstale properties, or the maxage/maxstale attributes of <audio>

  • the datamaxage/datamaxstale properties, or the maxage/maxstale attributes of <data>

  • the documentmaxage/documentmaxstale properties, or the maxage/maxstale attributes of <choice>, <goto>, <link>, <subdialog>, or <submit>

  • the grammarmaxage/grammarmaxstale properties, or the maxage/maxstale attributes of <grammar>

  • the objectmaxage/objectmaxstale properties, or the maxage/maxstale attributes of <object>

  • the scriptmaxage/scriptmaxstale properties, or the maxage/maxstale attributes of <script>

Maxage indicates that the document is not willing to use cached content whose age is greater than the specified time in seconds. Setting maxage to a non-zero value can be used to get a fresh copy of a resource that may not have expired in the cache yet. A fresh copy can be unconditionally requested by setting maxage to zero.

Maxstale indicates that the document is willing to use cached content that has exceeded its expiration time by as much as the specified time in seconds. Using maxstale enables the author to state that an expired copy of a resource, that is not too stale (according to the rules of HTTP 1.1), may still be used. For example, an author who does not have direct server-side control of the expiration dates of large static files can avoid unnecessary fetching by allowing cached copies to be used after expiration.

Rules for Caching

The caching policy used by the NGI adheres to the cache correctness rules of HTTP 1.1. In particular, the Expires and Cache-Control headers are honored. The following is a summary of the caching rules:

If the resource is not present in the cache, perform HTTP GET, where the full content of the resource is fetched.

If the resource is in the cache, use one of the following rules (depending on which of maxage and maxstale have been specified):

Maxage or Maxstale Provided | Rule
Neither provided. | If the cached resource is unexpired, use the cached copy; Otherwise, perform HTTP GET*.
Only Maxage provided. | If the age of the cached resource <= maxage and the resource is unexpired, use the cached copy; Otherwise, perform HTTP GET*.
Only Maxstale provided. | If: the cached resource has exceeded its expiration time by no more than maxstale seconds, or the resource is unexpired, use the cached copy; Otherwise, perform HTTP GET*.
Both provided. | If: the age of the cached resource <= maxage and the resource has exceeded its expiration time by no more than maxstale seconds, or the age of the cached resource <= maxage and the resource is unexpired, use the cached copy; Otherwise, perform HTTP GET*.

*Note: As an optimization, GVP performs an HTTP GET-IF-MODIFIED, rather than an HTTP GET, on documents still present in the cache when the policy requires a fetch from the server. In this case, the request includes an 'If-Modified-Since' (IMS) header, and the full content is returned only if it has changed more recently than the timestamp passed to the web server.

Examples

  1. To achieve the same behavior as setting caching="safe" in VoiceXML 1.0, use maxage="0" [and maxstale="0"].

<audio src="http://examples.com/audio.vox" maxage="0"/>

or

<audio src="http://examples.com/audio.vox" maxage="0" maxstale="0"/>

  2. To achieve the same behavior as setting caching="fast" in VoiceXML 1.0, use maxstale="0" [and maxage="large_value"].

<property name="documentmaxstale" value="0"/>

or

<property name="documentmaxage" value="large_value"/>

<property name="documentmaxstale" value="0"/>


Best Practices

Reduce Number of Page Transitions

Each time a VoiceXML page is received by the VoiceXML Interpreter, it is compiled and transformed into a state machine representation before it can be interpreted. It is important to avoid unnecessary page transitions, especially if the pages do not collect any inputs from the caller.

For example, consider the following VoiceXML page:

<?xml version="1.0"?>

<vxml version="2.0">

<form id="menu">

<block>

<submit next= "http://1.2.3.4:8080/app/jsp/aLocal.jsp?key1= val1&key2=val2&key3=val3"/>

</block>

</form>

</vxml>

It may be possible to invoke the aLocal.jsp page on the application server instead of delivering the page to the VoiceXML Interpreter, having it compile the VoiceXML page and then eventually do a HTTP submit request. This not only saves valuable system resources on the GVP VoiceXML platform, but it also reduces the latencies experienced by the caller.


Best Practices

Reduce Number of ECMAScripts

Although the ability to use ECMAScripts inside VoiceXML is appropriate for executing data driven application logic without leaving the VoiceXML browser, it does create overhead because GVP uses a third-party ECMAScript engine. Minimize the number of ECMAScripts used in an application, as overuse of ECMAScripts can adversely affect the application performance.

There is no ECMAScript overhead when a VoiceXML page is compiled; however, at run-time, each individual request to execute ECMAScript (either as a condition, as an expression, or as an actual script) is sent to the ECMAScript engine for processing. The ECMAScript engine does not maintain an internal cache of its own, and the script is compiled and executed each time it is invoked. For example, if an expression is executed more than once in an application flow, the expression will be evaluated each time.

When using ECMAScripts to evaluate the same expression multiple times, Genesys recommends that local variables be defined to hold the expression results. Use functions for commonly used operations instead of using inline scripts.

When generating VoiceXML pages dynamically on the application server, consider replacing ECMAScript (which must be executed on the VoiceXML platform) with server-side logic where possible.


Best Practices

Reduce Number of Global Variables

All VoiceXML variables are ECMAScript definitions defined inside the ECMAScript engine. Memory is consumed for each variable created. Each time a variable is created, or a new value is assigned to it, ECMAScript overhead is incurred. Too many global variables defined in the application root increases the memory requirements, which impacts application performance, and the total number of concurrent calls that GVP can handle.


Best Practices

Reduce Usage of Inline ECMAScripts

Internal and external ECMAScripts are executed in the same way. However, using external ECMAScript files, along with suitable use of caching (using the HTTP Expires: header) allows fetched dynamic VoiceXML pages to be smaller, and allows the ECMAScript itself to be cached.


Best Practices

Reduce Time Required to Compile VoiceXML Page

When a VoiceXML page is fetched, the entire page is compiled even if a single line of a ten thousand line page is executed. Therefore, avoid having multiple forms within the same page as they may not all be used. However, having forms on separate pages can introduce fetch delays. Genesys recommends that the maximum size of VoiceXML pages be under 100K for optimal performance of the platform.

The following code snippets compare an inefficiently designed application with a more efficiently designed application.

Inefficient Application

There are six forms on the same page, but only three will be used in a call. The rest are compiled, which results in wasted CPU time.

<?xml version="1.0"?>

<vxml version="2.0">

<form id="menu">

<field name="course">

<prompt>

Pick a course for its description.

Example CS 100.

</prompt>

<grammar>

CS 100 {course:cs100} | CS 121 {course:cs121} |

CS 122 {course:cs122} | CS 123 {course:cs123} |

CS 124 {course:cs124}

</grammar>

<filled>

<goto expr="'#'+course"/>

</filled>

</field>

</form>

<form id="cs100">

<block>

CS 100.

Introduction to Computer Usage. This course gives an introduction

to using personal computer hardware and software...

<!-- loop back -->

<goto next="#menu"/>

</block>

</form>

<form id="cs121">

<block>

CS 121.

Introduction to Object-Oriented Programming. This course teaches

the fundamental concepts of problem solving using a computer...

</block>

</form>

<form id="cs122">

<block>

CS 122.

Principles of Program Design. This course teaches the fundamental

concepts of object-oriented analysis and design...

</block>

</form>

<form id="cs123">

<block>

CS 123.

Developing Programming Principles. This course gives a review of

fundamental programming concepts and their application in Java...

</block>

</form>

<form id="cs124">

<block>

CS 124.

Introduction to Software Development. This course is an introduction

to basic concepts of computer science, including the paradigms of

theory, abstraction, and design...

</block>

</form>

</vxml>

Efficient Application

Move each form into its own page, so that a form will only be compiled if it is going to be executed. The other unused forms will not be compiled, eliminating unnecessary CPU cycles.

It is more efficient to use <subdialog> and <return> tags rather than <goto> tags. With <goto>, a transition back to the main menu will result in a page recompilation (and possibly a page fetch). With a <subdialog>, the main menu page context is preserved, and upon return from the <subdialog>, will not be recompiled.

<?xml version="1.0"?>

<vxml version="2.0">

<form id="menu">

<field name="course">

<prompt>

Pick a course for its description.

Example CS 100.

</prompt>

<grammar>

CS 100 {course:cs100} | CS 121 {course:cs121} |

CS 122 {course:cs122} | CS 123 {course:cs123} |

CS 124 {course:cs124}

</grammar>

<filled>

<if cond="course=='cs100'">

<goto nextitem="loop"/>

<else/>

<goto expr="course+'.vxml'"/>

</if>

</filled>

</field>

<subdialog name="loop" src="cs100.vxml">

<filled>

<clear/>

<goto next="#menu"/>

</filled>

</subdialog>

</form>

</vxml>

[ cs100.vxml ]

<?xml version="1.0"?>

<vxml version="2.0">

<form id="cs100">

<block>

CS 100.

Introduction to Computer Usage. This course gives an introduction

to using personal computer hardware and software...

<!-- loop back -->

<return/>

</block>

</form>

</vxml>

[ cs121.vxml ]

<?xml version="1.0"?>

<vxml version="2.0">

<form id="cs121">

<block>

CS 121.

Introduction to Object-Oriented Programming. This course teaches

the fundamental concepts of problem solving using a computer...

</block>

</form>

</vxml>


Best Practices

Production Deployment

Normally during development, platform and application logging levels are configured to provide the most detailed information for debugging. In a production environment, the performance impact of those logging levels could be considered unacceptable, as large amounts of data are written to files.

Genesys recommends that the <log> tag be used minimally in production, and turned on for collecting speech tuning metrics only. In addition, the platform logging levels must be kept at the minimum level; no greater than Standard during normal operations of a live deployment (the default level is Interaction).

Sometimes, detailed logging is required for debugging, tuning, monitoring, or for other reasons. When using higher log levels, try to localize their use, rather than enabling them globally throughout an entire application. When using full-duplex recording for monitoring, use in a limited (spot check) fashion. In any case, collected files should be deleted when they are no longer required, or moved to another server as soon as possible if they need to be archived.

In a production environment, the following is also recommended to avoid use of significant system resources that may adversely affect system performance:

  • Disable ASR utterance capture, or only enable for a subset of interactions.

  • Use full call recording with caution.

If it is necessary to use these features on a broader scale as part of your application, Genesys highly recommends detailed load-testing prior to production deployment.

For more information on the platform logging levels, see the Genesys Voice Platform 8.1 User's Guide.


Best Practices

Ensure that Expires Header is Present

ASR engines are responsible for fetching all of the external grammars. They maintain their own cache and depend on the Expires header to determine how long to use the cached copy. If the Expires header is not set, or set incorrectly, the ASR engine will continue to re-fetch the external grammar causing unnecessary use of system and network resources.


Precompile Grammars When Possible

Best Practices

Pre-compile Grammars When Possible

Before a grammar can be executed, the ASR engine first fetches the grammar, then compiles the grammar to an internal form, and caches the results for subsequent requests for that grammar. Most ASR engines also provide an option for pre-compiling the grammar files. If the application is using large static grammar files, it is better to pre-compile the grammars and place the pre-compiled version on the web server. This will help speed up the response time from the ASR engine when the calls are made, by avoiding the compilation phase of the grammar fetch.

Do not generate unnecessary dynamic grammars. If a grammar will not change, develop it as a static grammar (and pre-compile the grammar if large or frequently used).


Avoid Frequent Modification of Application Root Document

Best Practices

Avoid Frequent Switching of Application Root Document

When the application root document of a VoiceXML dialog is modified, a new application context is created. To reduce the overhead of repeatedly creating this context, switch the application root document only when absolutely required (for example, when a subdialog is created or when control is transferred from one application to another).

If the application is designed to use a root document, ensure that it is applied consistently to all pages. A compilation penalty occurs if the application switches among pages that have application root documents, and pages that do not.


Best Practices

Avoid Keeping Audio Files on GVP Servers

GVP does not offer a performance improvement when the audio files are kept locally on the GVP platform. GVP uses HTTP to fetch the audio files—fetching audio files from the same GVP machine will place additional burden on the platform due to processor resource competition.


Adjust Timeout to a Reasonable Amount Depending on Data Being Collected

Best Practices

Adjust Timeout to a Reasonable Duration Depending on Data Being Collected

It may be necessary to allow callers extra time to say long input strings, such as credit card numbers. It is a good practice to use a different timeout value for such cases. Make sure that the timeout is not set to zero for user input fields, as the caller will not be able to enter user input at all. This could make it difficult to troubleshoot problems, especially for speech applications.


Best Practices

Resolve Grammar Ambiguity

The ASR engine will work efficiently if the grammars are designed in a manner where there is no ambiguity, that is, a caller utterance matches only one item in the active grammar at any given point in time. This will also simplify the VoiceXML application since it does not have to handle any ambiguous recognition results.


Avoid Using

Best Practices

Avoid Using <break> Tag for Pause Between Audio Prompts

The <break> tag is used for introducing pauses in prompts. The Interpreter attempts to execute the <break> tag without using the TTS engine. If the <break> tag is interspersed within distinct TTS fragments, each prompt is sent as a separate request to the TTS engine while the <break> is handled by the Interpreter, and this increases the processing overhead. Enclose the TTS prompts and the <break> tag in an SSML element (for example, <paragraph> or <sentence>), which combines the TTS prompts into a single request to the TTS engine.

The following is an example of a non-efficient application:

<block>

<prompt>

<audio src="TransactionHistory.vox"/>

Credit 500 dollars on Jan 20, 2007.

<break/>

Debit 400 dollars on Jan 21, 2007.

<break/>

Debit 700 dollars on Jan 22, 2007.

<break/>

Credit 345 dollars on Jan 25, 2007.

</prompt>

</block>

The following is an example of a more efficient application:

<block>

<prompt>

<audio src="TransactionHistory.vox"/>

<paragraph>

Credit 500 dollars on Jan 20, 2007.

<break/>

Debit 400 dollars on Jan 21, 2007.

<break/>

Debit 700 dollars on Jan 22, 2007.

<break/>

Credit 345 dollars on Jan 25, 2007.

</paragraph>

</prompt>

</block>


Best Practices

Avoid Interleaving of Small TTS Prompts with Audio Prompts

SSML tags inside a <prompt> tag are batched and sent to the TTS engine. If a prompt or set of consecutive prompts contain interleaving of SSML and an <audio> tag for playing pre-recorded audio files, each section of SSML is sent to the TTS engine separately. This will result in processing latencies. Avoid intermixing small TTS and pre-recorded audio prompts.

The following is an example of a non-efficient application. In this case, each SSML snippet (for example, 700 dollars and Jan 25, 2007) is sent as a separate request to the TTS engine. Eight TTS licenses are used for converting text to audio for playback.

<?xml version="1.0"?>

<vxml version="2.0">

<block>

<prompt>

<audio src="TransactionHistory.vox"/>

<audio src="credit.vox"/>

500 dollars

<audio src="on.vox"/>

Jan 20, 2007.

<audio src="debit.vox"/>

400 dollars

<audio src="on.vox"/>

Jan 21, 2007.

<audio src="debit.vox"/>

700 dollars

<audio src="on.vox"/>

Jan 22, 2007.

<audio src="credit.vox"/>

345 dollars

<audio src="on.vox"/>

Jan 25, 2007.

</prompt>

</block>

</vxml>

The following is an example of a more efficient application:

<?xml version="1.0"?>

<vxml version="2.0">

<block>

<prompt>

<audio src="TransactionHistory.vox"/>

Credit 500 dollars on Jan 20, 2007.

Debit 400 dollars on Jan 21, 2007.

Debit 700 dollars on Jan 22, 2007.

Credit 345 dollars on Jan 25, 2007.

</prompt>

</block>

</vxml>


Best Practices

Understand Prompt Queuing

At any given time, the VoiceXML Interpreter is in one of two states, waiting for input in a field item, or transitioning between field items in response to an input. The Interpreter is in the transitioning state during a <block>, <catch>, <filled> or other non-field element as well as while it is transitioning between elements (even across pages).

Prompts are queued while the Interpreter is in the transitioning state. The types of queued prompts are:

  • PromptAndCollect&emdash;when the Interpreter reaches the next waiting state (for example, a <field>, <initial>, or <choice>/<menu>), at which point all queued prompts are played and the Interpreter listens for input simultaneously.

  • PromptOnly&emdash;when the Interpreter reaches an <exit>, <transfer>, <record>, or <object>, at which point all queued prompts are played before the element is executed.

  • PromptOnly and then the fetchaudio is played until the fetch completes&emdash;when the Interpreter begins fetching a resource (such as a document) using <submit>, <goto>, or <subdialog>, with fetchaudio specified. In this case, all queued prompts are played.

Note: In the PromptOnly state, no speech input is accepted. DTMF input is allowed, provided that prompt barge-in is enabled.

If multiple prompts are queued before a field input, the timeout or bargein type of the last prompt is used.


Best Practices

Use of Grammars Inside Transfers

GVP supports DTMF and ASR recognition during bridged call transfers only. If the call transfer does not bridge media through GVP (for example, if the method attribute or platform transfer configuration are not set to bridge), DTMF and ASR recognition are not available once the call transfer begins.


Best Practices

Tune Grammars and Prompts for Speech Applications

Compared to DTMF applications, speech applications are considerably more complex and require different techniques. For successful voice applications, grammar tuning is essential after representative call data has been collected. If the grammars are not properly tuned, it can result in poor customer experience with high opt-out or drop rates. Use utterance capture recording for the call data capture to identify application areas with high amounts of misrecognitions. The utterances may uncover input that callers are frequently saying but are not covered in the grammars. You may also have to take caller accents into account and add alternative pronunciations for some grammar items. Additionally, confidence levels may need to be adjusted to reduce both false recognitions and high rejection rates.

Similarly, prompts also need to be well designed so that they guide the callers to say the correct input. If callers are getting stuck in the call-flow, causing high misrecognition rates, evaluate the prompts to make sure they are intuitively directing the callers to speak the words as expected by the grammar.


Best Practices

Load Test Applications Before Production Operations

A GVP server is configured to service a calculated number of concurrent callers. This server specification, application characteristics, and many other factors affect the number of ports that can be serviced concurrently by a single server before callers perceive unacceptable latency or the expected duration of the call lengthens. As caller-perceived latency and average call length increase, the ability of the platform to deliver the expected call processing capacity decreases, as does the quality of the customer experience.

  • The port calculations take into consideration the application design, GVP component distribution, platform characteristics, web-server performance and other external dependencies. Each of these variables can impact the number of concurrent calls supported by an individual GVP server.

  • All calculations are theory and produce theoretical results. There is no replacement for evaluating the performance of the solution through load testing. Use a bulk call generation testing service, such as Empirix, that will exercise both the GVP and the Web server application design and configuration.

  • Monitor the memory and CPU utilization on the GVP platform, web server, and if implemented, the speech server. For most applications, you will have to tune the web server for performance. Typically, you will have to tune the worker threads/process pool, memory size, session timeout, connection recycle time. Consult the documentation for your selected application server for details.

  • If the application is experiencing memory leaks, consider recycling the threads/processors of the web server at periodic intervals. Do not enable excessive log levels on the web server side as that will impact overall performance of the web server. For logging, if possible, write the logs on a separate disk to reduce overall impact on disk I/O for the primary disk from which the web server pages will be served. When using Tomcat with Apache, take special care to tune the Apache Tomcat Connector (mod_jk or AJP) as the default settings for the connector do not perform well under load. Refer to the third-party web server documentation for details on performance tuning aspects.

  • If using databases or backend enterprise services, consider the performance of the database and Enterprise servers under load. Typically, you will have to tune the connection pool size for the databases. If the database requests are taking a long time, consider SQL query and database indexing optimizations. Work with your database administrator for these changes.

  • In addition to the automated load tests, perform actual human load tests with live people making simultaneous calls or do both. This will help in identifying areas in the application where caller perceived latencies are high and pin point locations that need to be optimized.

  • Prepare for load testing early in your development cycle. This allows for early detection of configuration problems, performance issues, memory leaks, synchronization issues, or other stability issues.

  • Run the load test for an extended period of time (several days) to understand resource usage trends. It is common for memory usage to increase over time and then to level off as the server reaches a steady state.


Tutorials

Overview

The VoiceXML tutorials include the following:

  • General VoiceXML Concepts

  • Advanced VoiceXML Concepts


General VoiceXML Concepts

Tutorials > General VoiceXML Concepts

Overview

Many of the tutorials include sample code. Be aware that the code is intended to shows concepts—it has not been tested. Do not expect that these code samples are working models for your applications.

Tutorial Name | Level | Description
Audio and Video Format Support | Intermediate | Explains how to use pre-recorded media in your applications, and describes the types of pre-recorded audio/video supported on the platform.
Audio Tag Part 1 | Beginner | Explains the <audio> tag and some of its attributes. The audio tag plays back a pre-recorded audio file.
Audio Tag Part 2 | Beginner | Explains all the attributes of the <audio> tag, and what happens when an audio file cannot be found.
DTMF Buffering | Intermediate | Explains how DTMF input is buffered in VoiceXML.
Event and Error Handling in GVP | Intermediate | Explains how to design and interpret error messages on the Genesys Voice Platform.
Events In VoiceXML | Beginner | Explains VoiceXML events, such as noinput and nomatch, and how to use them in your applications.
Form Tag | Beginner | Uses a restaurant ordering application to demonstrate the usage of the <form> tag.
Prompt Control In VoiceXML | Intermediate | Explains how prompt queueing, selection, bargein, timeout, bargeintype, and reprompts work in VoiceXML.
VoiceXML Tips | Intermediate | Explains many tips and techniques to avoid common VoiceXML pitfalls.


Audio Video Format Support

Tutorials > General VoiceXML Concepts

Audio and Video Format Support

This topic describes how to play back pre-recorded media in your applications and describes the types of pre-recorded audio/video supported by Genesys Voice Platform (GVP).

Overview

Audio File Characteristics

Supported Audio/Video Formats

Generating Different Audio Formats

Generating Video Content

  • Notes about Video Format

  • Note about using ffmpeg to process video files recorded by GVP

Practical Matters

Troubleshooting

Overview

VoiceXML makes use of pre-recorded audio when providing prompts to the caller, in order to guide them through the application. Well-engineered speech applications take advantage of as much pre-recorded audio as possible. Although TTS engines are very good and continue to improve, pre-recorded audio continues to remain the choice for delivering static content to the user wherever practical. It is therefore important to have a proper understanding of how to make use of pre-recorded audio in your application.

Applications are often developed in stages, using prompts as follows:

  • TTS prompts; usually done by the developer for testing purposes;

  • Locally recorded audio prompts (in-house talent);

  • Professionally recorded prompts (in-house or third party talent).

Note: You should always use alternative audio to provide a backup for pre-recorded audio.

The GVP VoiceXML platform also includes support for playing back pre-recorded video files. With this support, VoiceXML applications can use the <audio> tag to play video (or mixed audio and video) content, as long as the caller is using a SIP phone/device that enables them to view the video content. (GVP's support for video applications also includes video recording and video transfer. These functions are not detailed in this tutorial.)

The GVP VoiceXML platform supports a number of pre-recorded audio and video formats. Selection of a pre-recorded media format will depend on a number of factors:

  • Availability of pre-existing audio and video.

  • Formats available from third-party content providers.

  • Tools and resources available for media file manipulation.

Audio File Characteristics

Audio data can typically be characterized using a small number of parameters:

  • Sample Rate

  • Sample Encoding

  • Number of channels

Sample Rate

The sample rate refers to the number of audio samples per second. The telephony network makes use of an 8KHz sample rate, or 8000 samples per second. This is the only sample rate that is currently supported.

Sample Encoding

Audio samples may be encoded in a particular way. This typically is done to provide compression or dynamic range advantages. For example, u-law encoding allows about 16 bits of dynamic range to be represented with 8 bits of data. Differential encoders record the difference between two samples rather than the samples themselves. GVP supports the encoding types listed below:

Supported Audio Encoding Table

Encoding | Characteristics | Typical Usage
u-law | 64kbps @ 8000Hz | North American Telephony
a-law | 64kbps @ 8000Hz | European, Australian Telephony
Linear PCM | 64/128kbps @ 8000Hz | Voice-mail systems
Adaptive Differential PCM (g726) | 24, 32, 40kbps @ 8000Hz | Compressed Voice-mail systems
G.729 | 8kbps @ 8000Hz | VoIP Applications
AMR | 12.20/10.20/7.95/7.40/6.70/5.90/5.15/4.75/1.80kbps @ 8000Hz (Adaptive multi-rate) | Mobile Network
AMR-WB | 6.60/8.85/12.65/14.25/15.85/18.25/19.85/23.05/23.85kbps @ 16000Hz (Adaptive multi-rate) | Mobile Network

* g726 3, 4, and 5 bit formats are also known as g726 24 kbps, 32 kbps, and 40 kbps formats, respectively.

Number of Channels

Audio files may contain more than one channel. The most frequent occurrence will be in the case of mono and stereo data, referring to one and two channels of data respectively. Of course, your audio data may have more channels, depending on how it was recorded. Data that will be delivered to the VoiceXML Gateway for playback should be converted to mono or single channel format.

Supported Audio/Video File Formats

The most portable file format remains a raw audio file containing data encoded as in CCITT G.711 u-law format, single-channel, with a sample rate of 8000 samples per second and 8 bits per sample. The European equivalent uses G.711 a-law encoding rather than G.711 u-law. These files typically have a .vox extension. It is important for Web servers to recognize the .vox type and send GVP a file with a MIME content type of audio/x-vox. This usually requires some manual configuration on the part of the HTTP server administrator.

In general, all supported audio and video codecs can be stored in raw format. The table below summarizes the expected file extension and required mime type to be returned from the HTTP server.

It is also permissible to refer to files with a .wav extension, which can use the same encoding but also include a RIFF header. In this case, the web server must deliver a MIME content type of audio/x-wav. These files can contain data with G.711 u-law, G.711 a-law, Linear PCM, or G.726 ADPCM encoding, and sample rates of 8000 Hz.

It is also permissible to refer to files of NIST SPHERE format, and Next/Sun AU format. In the case of NIST format files, which include a NIST header, the web server must deliver a MIME content type of audio/x-wav. These files can have an extension of either .nist or .wav. In the case of AU format files, which include an AU header, the web server must deliver a MIME content type of audio/basic. These files must have an extension of .au. NIST format files can contain data with G.711 ulaw or G.711 a-law encoding. AU format files can contain data with G.711 ulaw, G.711 a-law, Linear PCM, or G.726 ADPCM encoding. These files typically have a .263 extension. It is important to configure the Web server to recognize the .263 type and send GVP a file with a MIME content type type of video/h263 or video/x-h263.

For playing back audio/video content, GVP supports the avi file container format. These files can contain audio data with G.711 u-law, G.711 a-law, Linear PCM, or G.726 ADPCM encoding, mixed with h263 video data.

The table below summarizes the media formats supported by GVP.

Supported Pre-recorded Media Formats

Expected File Extension

Mime-type

Sample Rate

File Format/
Sample Size/
Encoding

.vox

audio/x-vox
audio/vox
audio/basic

8000 Hz

  • Raw audio

  • 8-bit (mono)

  • G.711u-law, G.711 a-law (depends on platform configuration)

.au

audio/basic

8000 Hz

  • Audio with .au header

  • 8-bit mono

  • G.711 u-law, G.711 a-law,
    PCM, ADPCM (depends on file header information)

.ulaw

audio/basic
audio/PCMU
audio/mulaw

8000 Hz

  • Raw audio

  • 8-bit mono

  • G.711 u-law

.alaw

audio/x-alaw-basic
audio/PCMA
audio/alaw

8000 Hz

  • Raw audio

  • 8-bit mono

  • G.711 a-law

.g729

audio/g729

8000 Hz

  • Raw audio

  • G.729

.adpcm24

audio/x-g726-24
audio/g726-24

8000 Hz

  • raw audio

  • 24kbit/sec

  • ADPCM (G.726)

.adpcm

audio/x-g726
audio/x-adpcm
audio/adpcm
audio/x-adpcm8
audio/g726
audio/g726-32
audio/x-g726-32

8000 Hz

  • Raw audio

  • 32kbit/sec

  • ADPCM (G.726)

.adpcm40

audio/x-g726-40
audio/g726-40

8000 Hz

  • Raw audio

  • 40kbit/sec

  • ADPCM (G.726)

.pcm8

audio/L8
audio/pcm8
audio/x-pcm8

8000 Hz

  • Raw audio

  • 8-bit unsigned mono

  • Linear PCM

.pcm16

audio/L16

8000 Hz

  • Raw audio

  • 16-bit signed mono

  • Linear PCM

.wav

audio/wav
audio/x-wav

8000/16000 Hz

  • Audio with RIFF header

  • Audio (8000Hz): g.711 u-law, G.711 a-law, PCM, PCM16, G.726, G.722, G.729, AMR (depends on file header information)

  • Audio (16000Hz): PCM16, AMR-WB

.nist

audio/wav
audio/x-wav

8000 Hz

  • Audio with NIST header

  • 8-bit mono

  • G.711 u-law, G.711 a-law (depends on file header information)

.amr

audio/amr

8000 Hz

  • Raw audio

  • AMR

.awb

audio/amr-wb

16000 Hz

  • Raw audio

  • AMR-WB

.3gp

audio/3gpp

8000 Hz (AMR)

16000 Hz (AMR-WB)

  • Audio stored in 3GP container

  • AMR

  • AMR-WB

.263

video/h263
video/x-h263

30 fps (recommended)

  • Raw video

  • h263

.263

video/h263-1998

30 fps (recommended)

  • Raw video

  • h263-1998

.264

video/h264

30 fps (recommended)

  • Raw video

  • h264

.avi

video/avi
video/x-avi

8000/16000 Hz
30 fps (recommended for video)

  • Audio/video stored in AVI container

  • Audio (8000Hz): G.711 u-law, G.711 a-law, PCM, PCM16, G.726, G.722, G.729, AMR (depends on file header information)

  • Audio (16000Hz): PCM16, AMR-WB

  • Video: h263, h263-1998 (depends on file header information)

Note: H264 is not supported with AVI container.

.3gp

video/3gpp

8000 Hz
30 fps (recommended for video)

  • Audio/video stored in G3P container

  • Audio: AMR, AMR-WB

  • Video: h263, h263-1998 (depends on file header information)

  • Video: h264

Notes:

  • GVP examines the audio data to determine whether an audio/basic file is actually of .au format or is .vox format.

  • Only 8000Hz audio sampling rate is supported, except for AMR-WB and G722 which are 16000Hz.

  • If non-8000 Hz audio file is detected, the prompt will not play and a warning message will be issued.

Generating Different Audio Formats

You may wish to request one of the above formats from your recording service provider (or pick one of the above formats when making your own recordings), so that the audio files can be played by GVP without changes. Otherwise, if recordings are made in an unsupported format, you will need to use a tool to convert/prepare the recordings before they can be played by GVP. For example, Goldwave can be used to produce .vox or .wav files from almost anything.

The key to getting things to work is to generate one of the above formats that GVP can play. Here is a sequence of steps to follow:

  1. Record the file in a high-fidelity format. For example, you can record at a sampling rate of 44 KHz and 16-bit resolution.

  2. Perform any processing on this data. For example, if you want to normalize the sound level (-3 dB is a good level for applications), trim silence, and so on.

  3. Downsample to 8-bit mono u-law with an 8 KHz sample rate.

Here are some audio manipulation tools:

  • GoldWave

  • SoX

  • Awave Audio

  • WavePad

GoldWave

GoldWave is a popular tool for audio data manipulation. This section shows how to use GoldWave to generate files in a format that will play on the GVP VoiceXML Gateway.

After opening or recording your audio data, you can follow these steps to save the data as a suitable VOX file.

Trim the Audio Data

This removes leading and trailing silence. Select the beginning of your data with the left mouse button, and then select the right edge using the right mouse button. Then select Edit->Trim to crop the data.

Adjust the Sample Rate & Type

Resample the data using Edit->Resample. Then select 8000 from the drop-down list or using the slider. All other conversions are done when saving the file.

Save the New File

To save your newly converted data, do the following:

  1. Select File->Save As.

  2. Choose Dialogic (*.vox) from the Save as type drop-down menu.

  3. Choose u-law, mono from the File Attributes drop-down menu.

  4. Click Save.

GoldWave also supports these compatible file types:

  • Dialogic (*.vox) (u-law, a-law, ADPCM)

  • Wave (*.wav) (8-bit mono unsigned, u-law mono, a-law mono, various ADPCM)

  • Next/Sun (*.au, *.snd) u-law 8-bit mono, a-law 8-bit mono, linear PCM

When opening a .vox file, select Telephony, 8000 Hz sample rate. See the format and encoding in the status bar at the bottom of the GoldWave window. You can download GoldWave from http://www.goldwave.com.

SoX

SoX is a UNIX tool that is easily used to transform audio files from one format to another. There is also a Windows version available. You can convert a .wav file with SoX using a command line something like:

sox -t wav foo.wav -t ul bar.vox

This will generate an 8-bit u-law VOX file as output, or to convert the other way:

sox -t ul bar.vox -t wav -U foo.wav

You may need to resample the data:

sox -t wav foo.wav -r 8000 -t ul bar.vox

Or perhaps to convert to a single channel:

sox -t wav foo.wav -c 1 -t ul bar.vox

SoX is available from: http://sox.sourceforge.net

Awave Audio

The Awave Audio tool may also be useful for converting audio formats. You can download Awave Audio from www.fmjsoft.com for a free limited trial.

Note: Make sure that you download Awave Audio, not Awave Studio.

Genesys has not assessed this tool for general use. However, it has been used for certain specific conversions, such as converting from G.726 back to playable audio.

WavePad

WavePad is a free tool, available from www.nch.com.au/wavepad/index.html. It has a simple and straightforward interface, and provides many basic features, such as:

  • Plays a variety of audio formats, such as:

  • Vox (select G711 uLaw as the audio type when opening the file).

  • Audio/L8 (rename from .pcm8 to .raw and set properties to 8bit-unsigned, 8000, 1-Mono).

  • Audio/L16 (rename from .pcm16 to .raw and set properties to 16bit PCM (LE), 8000, 1-Mono).

  • Converts between a variety of audio formats.

  • Amplify, normalize, high-pass filter, very simple equalizer, echo, reverb, fade in, fade out, noise reduction.

Note: WavePad cannot be used to load/play G.726 files. Genesys has not tested this tool extensively. It is noted in this section because it is a free tool (rather than a limited free trial).

Generating Video Content

Genesys recommends the SUPER tool for converting/generating video (http://www.erightsoft.com/SUPER.html). SUPER is a GUI tool built on top of several decoding/encoding programs, which allows you to convert a wide range of video to the H.263/PCM16 AVI format. It exposes the most commonly-used functionality in a design that is easy to use. However, it does not expose 100% of the functionality of the underlying programs.

In order to use any functionality that is not exposed in the SUPER interface, the desired underlying programs need to be run manually, from the Windows command-line, as follows:

  1. Log on to the same Windows machine that SUPER is installed on.

  2. Open a command prompt (select Start, Run, and type cmd).

  3. Change to the folder where SUPER is installed (cd <path>).

  4. Run the desired program, with any necessary options (./<program> [<options>]). The SUPER website has links to documentation for each of the underlying programs.

Note: There may be Linux versions of the programs as well. In that case, the programs would be run from the Linux command-line instead.

One particular use for the above approach is to convert the sampling rate of the audio portion of an .avi file. Remember that GVP can only play .avi files where the audio sampling rate is 8000 Hz (see supported formats). However, there is currently no way to specify an audio sampling rate of 8000 Hz through the SUPER interface. The sampling rate can only be set to 8000 Hz by manually running an underlying program from the command-line.

Therefore, two steps are required to convert a video file to the format that is supported by GVP:

Step 1

Use SUPER to create an .avi file with a video codec of H.263. At this point, the format of the audio part does not matter. The audio sampling rate (also called "sampling frequency") can be set to 16000 Hz and the audio codec can be set to PCM16.

Note: The following instructions are based on SUPER version 2007.build.22 (Mar 14, 2007). If another version is being used, some of the labels/values might vary slightly.

  1. Where it says Select the Output Container at the top, select avi.

  2. Where it says You may select ffmpeg OR MEncoder at the top, select ffmpeg as the underlying program to use for the encoding.

  3. Use the following settings for the video part of the file:

    • Where it says Select the Output Video Codec at the top, select H.263.

    • In the VIDEO section, set Video Scale Size to desired value (recommended setting is 176:144). When the video scale size is changed, the Aspect setting will be adjusted automatically to an appropriate corresponding value.

    • In the VIDEO section, set Frame/Sec to desired value (recommended setting is 30).

    • The other settings in the VIDEO section can be left untouched.

  4. Use the following settings for the audio part of the file:

  • Where it says Select the Output Audio Codec at the top, select WAV-(pcm 16 little-endian). This can be changed in Step 2, if it is not the desired codec.

  • In the AUDIO section, set Sampling Freq to 16000 (regardless of the original sampling rate). This will be changed in Step 2.

  • In the AUDIO section, set Channels to 1.

  • The other settings in the AUDIO section can be left untouched.

  5. Drag and drop the original video file (from Windows Explorer) into the box at the bottom of the tool. In the resulting file listing, make sure the Active box (at the left-hand side) is checked off. Do the encoding by pressing the button under the box, that says Encode (Active Files). A window might pop up, asking to choose I263 or H263. If that happens, you must choose H263.

Optionally, if there are additional desired audio or video settings that are configurable through SUPER, they could be selected in this step as well, before encoding the file.

Step 2

Take the file that was created in Step 1, and use the underlying program called ffmpeg.exe (or ffmpeg, if it is the Linux version) to manually convert the audio part of the .avi file to have the desired codec and a sampling rate of 8000 Hz. (The audio options are italics in the following command.)

  ffmpeg.exe -i <in.avi> -acodec <desired_codec> -ar 8000 -ac 1 -vcodec h263 -maxrate 384000 -bufsize 200000 <out.avi>

-i specifies the original avi file to be converted (change <in.avi> to the name of the file created in Step 1).

-acodec sets the audio codec in the resulting file to <desired_codec> (see Note below for possible values to use).

-ar specifies the sampling rate of audio in the resulting file.

-ac specifies the number of audio channels in the resulting file.

-vcodec specifies the video codec in the resulting file.

-maxrate specifies the max bitrate tolerance of video in resulting file.

-bufsize specifies the rate control buffer size of video in resulting file.

<out.avi> specifies the resulting converted avi file (change <out.avi> to the desired file name)

Note: There are three possible values for the -acodec option. For u-law, use pcm_mulaw, for a-law, use pcm_alaw, and for PCM, use pcm_s16le (PCM16 signed little endian). There is no value to convert to an ADPCM codec that GVP can play.

Note: Genesys recommends that the command in Step 2 be run with all the options and values specified above, even if some of the values were already set in Step 1. The command provides the configurations for generating the optimal audio+video file supported by GVP, so it is always best to run the entire command just in case any values were not already set. For values that were already set, the options will simply have no further effect.

Optionally, if there are additional desired audio or video changes that were not configurable through SUPER, they can be made at this point, through subsequent command-line invocations of ffmpeg, or the other underlying programs.

For more details and examples of ffmpeg commands, run ./ffmpeg.exe (or ./ffmpeg, for the Linux version) without any options, to see the manual page. Or for more extensive documentation, check the ffmpeg website (http://ffmpeg.mplayerhq.hu/documentation.html, which then links to FFmpeg program documentation where all the options are defined).

Notes about Video Format

  • One other characteristic of a video file's format is its clock rate (which is not the same thing as "frame rate"). GVP's officially supported clock rate is 90000 Hz.

SUPER/ffmpeg should always set the clock rate to 90000 Hz automatically (there is no explicit setting or option for clock rate). So if you follow the above steps for generating/converting video, there should be no problem with the clock rate. However, if you use another tool to generate/convert video, note that the clock rate could be set to something other than 90000 Hz, which may or may not allow the video file to be played back properly.

When GVP is requested to play a video file with a clock rate other than 90000 Hz, the behavior will depend on the value of the MCP configuration parameter mpc.mediamgr.strictsamplingrate. If the parameter is enabled (set to 1), GVP will not play the video file at all. If the parameter is disabled (set to 0), GVP will play the video file, but will log a warning similar to the following:

2008-02-26/12:36:50.854 WARN 0002007C-108C9D09 0006 08500BC0 VIDEO sampling rate unsupported: Clockrate of 10 Hz
has been found in VIDEO track.  The track may not be played correctly.

If the video file appeared correct during playback, the warning can simply be ignored. But if the video file did not look right, it should be modified to have the officially supported clock rate of 90000 Hz.

  • To verify the format of existing video files, try using the MediaInfo tool (available at http://mediainfo.sourceforge.net/en). For example, let's say a particular 3gp video file (named video1.3gp) is improperly formatted, containing more than one video stream. The MediaInfo tool will show something like the following (note the three video streams, in italics):

General #0
Complete name          : C:\video1.3gp
Format                 : 3GPP (MPEG-4) / 3GPP
Family                 : MPEG-4
File size              : 57.0 KiB
PlayTime               : 17s 500ms
Bit rate               : 27 Kbps
Video #0
Codec                  : H.263
Video #1
Video #2
Codec                  : H.263
Info                   : H.263 (3GPP)
PlayTime               : 17s 500ms
Bit rate               : 11 Kbps
Width                  : 176
Height                 : 144
Aspect ratio           : 1.222
Frame rate             : 10 fps
Bits/(Pixel*Frame)     : 0.044
Channel(s)             : 24600
Audio #0
Codec                  : AMR-NB
Info                   : AMR narrow band (3GPP)
PlayTime               : 17s 400ms
Bit rate               : 13 Kbps
Channel(s)             : 1 channel
Sampling rate          : 8 KHz
StreamSize             : 27840

Note about using ffmpeg to process video files recorded by GVP

GVP can record video, using something like <record type="video/avi" ...> (see <record> tag for details). In addition to being accessible for playback in the VoiceXML application, video recordings can also be saved as files for use after the call has ended.

If you have saved video files that were recorded by GVP, the file format is already appropriate for playback in a VoiceXML application, so there is no need to run the above SUPER/ffmpeg steps for generating/converting a video file to be playable by GVP. But some customers might want to do SUPER/ffmpeg processing of a GVP-recorded video file for other reasons (for example, to change the video encoding or quality for use in a non-VoiceXML application, to reduce the size before storing in a file archive, and so on). GVP has no recommendations or limitations for such processing.

However, when a GVP-recorded video file is used as ffmpeg input, ffmpeg might display unexpected duration and bitrate values for the input file. For example, it could display something like the following (note the values in italics):

C:\Program Files\eRightSoft\SUPER>ffmpeg.exe -i recording.0002007C-1000032C-0001.1.20080226.182234.avi ...
...
Input #0, avi, from 'recording.0002007C-1000032C-0001.1.20080226.182234.avi':
  Duration: 00:00:00.0, start: 0.000000, bitrate: -2147483 kb/s
...

Note that this is only a display issue (related to proprietary ffmpeg interpretation of the video content). It does not indicate any problem with the GVP recording file format itself; the real duration and bitrate of the video content are fine. The GVP recording should still be properly playable, and other third-party tools (such as MediaInfo) will not indicate any problem with the file format. So the unexpected values can safely be ignored.

After using an ffmpeg command to perform any processing on the GVP-recorded video file, the output file does not have the same problem (the duration/bitrate should be reasonable values). For example, let's say the above ffmpeg command takes a GVP-recorded video file as input, and creates a new video file named recording2.avi. (Note that some of that command's parameters will be redundant if the input recording already has the properties, but it doesn't hurt to specify them.) Then, if recording2.avi is subsequently used as ffmpeg input, it should display something like the following:

C:\Program Files\eRightSoft\SUPER>ffmpeg.exe -i recording2.avi ...
...
Input #0, avi, from 'recording2.avi':
  Duration: 00:00:10.3, start: 0.000000, bitrate: 273 kb/s
...

Practical Matters

How do I use Nuance WAV format files?

Nuance applications include audio files with the extension .wav. However, they are not Microsoft Wave files, but NIST SPHERE format files. These can be used by stripping the header off the files, and presenting the remainder of the data as regular 8-bit mono u-law data.

How about recorded data?

When recording, the audio data is sent to the web server in the format defined in the <record> tag (usually either audio/x-vox or audio/x-wav). Once decoded on the server side, your server-side application can write out the raw binary data. In this event, the file will be either VOX or WAV, whichever is specified. This file will contain either an RIFF header and the raw audio data (in the case of a WAV file), or just the raw audio data itself (in the case of a VOX file ). The raw audio data will typically be 8-bit mono (ulaw) encoded audio samples, with a sample rate of 8000 Hz.

Troubleshooting

If you are having trouble getting your audio file to play, consider the following tips:

  • If an audio file cannot be found/played and there is no alternate content, the <audio> tag is ignored. No error is thrown in that case.

  • If you are using Apache Tomcat, there is a bug that could affect audio file fetching.

  • There may be cases where wav audio files have large (~ 4000 bytes) blank "padded" areas (filled with 0's) in the header. You can check this by opening the audio file in a text editor. There is a known limitation that the GVP platform cannot parse wav headers over a certain size. When such audio is referenced, an error will be thrown.

Resaving the file in Goldwave will solve the problem, because Goldwave eliminates the padded header area. Although the raw audio data will be exactly the same, the removal of the padded header area will result in a smaller file overall. This method is recommended; it solves the problem and is space efficient.


Tutorials > General VoiceXML Concepts

Audio Tag Part 1

This tutorial describes how the <audio> tag works. The sample application plays an audio message when you call it. A basic audio tag looks like:

<audio src="URI" />

Where the source is any URI that you want to code into your application.

Note: The <form> and <block> tags, they are not the focus of this tutorial.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Audio Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <form>
      <block>
         Welcome to the Audio Example brought to you by GVP.
         Playing a previously recorded sound.
         <audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
      </block>
   </form>
</vxml>

The maintainer meta tag is used to e-mail errors to the specified e-mail address. This may be useful when debugging your application. The application meta tag will log your application name in the call logs. This makes it easy to see what application ran in a certain phone call. The property tags set up the GVP server for bargein and confidencelevel.


Tutorials > General VoiceXML Concepts

Audio Tag Part 2

This tutorial is designed to show you additional features of the <audio> tag. The attributes are:

  • src="URI"

  • fetchtimeout= <Your timeout value> (with the units s or ms)

Fetching

The fetchtimeout is a useful feature (fetchtimeout=number of seconds or milliseconds). While GVP has a default wait time for loading a clip, you may want to specify your own wait time for loading the audio clip.

Alternate Text or Audio

If the audio clip is not found when the application plays, you can supply alternate media. For example, you can nest in another audio clip or you can provide a text-based version of the clip to be played by the TTS (Text to Speech) engine.

<audio src="thankyou.vox">
   Thank You
</audio>
<audio src="thankyou.vox">
<audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
</audio>

Improved Audio Example

Using the example from the Audio Tag Part 1 tutorial, the following steps improve it so that it is more interesting and so that it will demonstrate some of the preceding techniques.

Step 1

First, lay out the template for the VoiceXML file. This takes care of the <meta> and <property> tags and sets up the initial form to hold the application.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Audio Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <form>
   </form>
</vxml>

Step 2

This step places you at the point of Audio Tag Part 1. There is a little reorganization, but overall it is the same application.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Audio Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <form>
      <block>
         Welcome to the Audio Example brought to you by GVP.
      </block>
      <block>
         Playing a previously recorded sound.
         <audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
      </block>
   </form>
</vxml>

Step 3

Add some alternate text for an audio clip that does not play, and include a fetchtimeout for the audio file before it goes to the alternate text.

<block>
   Alternate Text can be played if the clip cannot be found.
   <audio src="thankyou.vox" fetchtimeout="1s">
      Sorry I couldn't find the audio file so I'm using
      text to thank you instead.
   </audio>
</block>

Adding the fetchtimeout attribute makes GVP wait for a second before it decides it cannot find the audio file, and then it goes on to the TTS instead. Whatever text is placed between the start and end tags will be played.

By placing the code block in the example, you get:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Audio Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <form>
      <block>
         Welcome to the Audio Example brought to you by GVP.
      </block>
      <block>
         Playing a previously recorded sound.
         <audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
      </block>
      <block>
         Alternate Text can be played if the clip cannot be found.
         <audio src="thankyou.vox" fetchtimeout="1s">
            Sorry I couldn't find the audio file so I'm using
            text to thank you instead.
         </audio>
      </block>
   </form>
</vxml>

Step 4

Add alternate audio in case the original clip cannot be played.

<block>
   Alternate audio can be played if the clip can't be found.
   <audio src="thankyou.vox">
      <audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
   </audio>
   Instead of hearing the "thank you" audio file, which could not be found, you heard
   the wolf once again.
</block>

Now, the example becomes:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Audio Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <form>
      <block>
         Welcome to the Audio Example brought to you by GVP.
      </block>
      <block>
         Playing a previously recorded sound.
         <audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
      </block>
      <block>
         Alternate Text can be played if the clip cannot be found.
         <audio src="thankyou.vox" fetchtimeout="1s">
            Sorry I couldn't find the audio file so I'm using text to thank you instead.
         </audio>
      </block>
      <block>
         Alternate audio can be played if the clip can't be found.
         <audio src="thankyou.vox">
            <audio src="http://developer.genesyslab.com/libraries/audio/misc/wolfhowl.vox" />
         </audio>
         Instead of hearing the "thank you" audio file, which could not be found, you
        heard the wolf once again.
      </block>
      <block>
         Thank you for using the Audio Example brought to you by GVP.
         Good-bye.
      </block>
   </form>
</vxml>


Tutorials > General VoiceXML Concepts

DTMF Buffering

  • What is DTMF Buffering?

  • Rules For Buffering DTMF Input

  • Rules For Clearing the DTMF Buffer

  • Summary

What is DTMF Buffering?

Some situations occur where the Interpreter cannot accept DTMF keypresses immediately as input. In these situations, the keypresses are stored in the DTMF input buffer for possible later use as input. Throughout the execution of the application, the Interpreter must decide whether to save the current contents of the DTMF input buffer (and use them at the next input state) or to discard them.

Rules For Buffering DTMF Input

Buffering DTMF input can be useful in allowing typeahead, where users input DTMF for multiple fields rapidly, separated by the termchar. Whatever input is left after the first termchar may be used in subsequent fields, meaning that the user does not have to wait to hear each prompt.

Here are the rules used in GVP that determine when DTMF input should be buffered:

  1. When in an input item, such as a <field>,

    • After the termchar key is pressed, any DTMF input that occurs is buffered.

    • If the termtimeout property is set to 0s, DTMF keys that are pressed after an ungrammatical sequence are buffered, since the Interpreter has already detected a nomatch, and processes the result, without waiting for any other input.

For example, if a <field> has the following grammar:

         <grammar type="application/srgs+xml" version="1.0" root="root">
            <rule id="root">
               <item>1</item>
               <item>2</item>
            </rule>
         </grammar>

the termtimeout is 0s, and the user inputs "3 2 1", the Interpreter will throw a nomatch immediately after the "3" (since no match is possible starting with "3"), and will not wait for further input. "2 1" will be buffered (although the buffer will be cleared when the nomatch event is thrown—see rule #3 in the section on clearing the buffer).

    • If the termtimeout property is set to a very small value (for example, >0s), DTMF keys that are pressed after a grammatical sequence are buffered, since the Interpreter finds an exact match with the prefix and processes the result without waiting for any other input.

For example, if a <field> with termtimeout set to 0s has the following grammar:

         <grammar type="application/srgs+xml" version="1.0" root="root">
            <rule id="root">
               <one-of>
                  <rule id="first">
                     <item>1</item>
                     <item>2</item>
                  </rule>
                  <rule id="second">
                     <item>1</item>
                     <item>2</item>
                     <item>3</item>
                     <item>4</item>
                  </rule>
                </one-of>
             </rule>
         </grammar>

and the user inputs "1 2 3 4" or "1 2 8 9" (beginning with "1 2" match, regardless of whether the entire input matches), the Interpreter matches "1 2", and will not wait for further input. "3 4" or "8 9" will be buffered and may be used in the next <field>.

  2. When in a PromptOnly state (for example, where queued prompts are flushed but no speech input is accepted) and bargein is enabled:

    • If the first key pressed is the termchar, it will stop the prompts and then be discarded.

    • Any other DTMF input that occurs will stop the prompts and be buffered.

Rules for Clearing the DTMF Buffer

Clearing the DTMF buffer means that any DTMF currently in the buffer is discarded. When collecting input, any uncleared DTMF in the buffer will be used. GVP uses the following rules to determine whether the DTMF buffer should be cleared:

  1. When entering an input item, such as a <field>,

  • The DTMF input buffer will be cleared if bargein is disabled for the first prompt (regardless of bargein values for subsequent prompts).

    • The DTMF input buffer will not be cleared if bargein is enabled for the first prompt (regardless of bargein values for subsequent prompts).

Note: In the case where bargein is enabled, if the inputmodes property is set to voice (<property name="inputmodes" value="voice"/>) or if there are no DTMF grammars active within that input item, any DTMF carried over in the buffer will cause a <nomatch> to be thrown.

  2. When leaving an input item, the DTMF input buffer will not be cleared. (However, because of the following rule, the buffer may have already been cleared while in the input item).

  3. When an event is thrown (for example, <nomatch>, <noinput>), the DTMF input buffer will be cleared.

  4. When entering a <form>,

    • The DTMF input buffer will be cleared if the gvp:cleardtmf attribute is set to true (<form gvp:cleardtmf="true">).

    • The DTMF input buffer will not be cleared if the gvp:cleardtmf attribute is set to false (the default).

  5. When entering a PromptOnly state (for example, where queued prompts are flushed but no speech input is accepted), the DTMF input buffer will always be cleared.

Summary

Without a complete understanding of DTMF buffering, it can seem like applications are behaving in mysterious and unpredictable ways. It may be hard to understand why users can or cannot barge in at certain times, and why users are or are not able to input DTMF for multiple fields at once (typeahead). Understanding the concepts explained in this tutorial enables the developer to have more control over the behavior and success of the application.


Event and Error Handling On GVP

Tutorials > General VoiceXML Concepts

Event and Error Handling In GVP

You may occasionally make mistakes when writing a VoiceXML application. Error messages can help handle and solve problems when they occur. These messages can help you pinpoint the source of the error, alleviate confusion, and promote more useful feedback from users.

Catch Element Selection

When an event/error is thrown, a <catch> tag is selected by using the algorithm defined in the VoiceXML 2.1 specification.

The "current count value" is the count of the exact event that was just thrown. For example, if an error.badfetch.http.404 has just been thrown for the second time, the current count value is 2. In this case, a matching catch element such as

<catch event="error.badfetch" count="5">

will not be considered, since the value of the count attribute is higher than the current count value. Similarly, this catch will also be ignored if the error.badfetch count exceeds 5.

If a page fetch (requested by a <choice>, <goto>, <link>, <subdialog>, or <submit>) results in syntax or other compile-time errors, the errors are thrown and handled in the previous page, in the scope associated with the above tag that requested the fetch.

Defining Error Handlers

When an error is thrown, the Interpreter finds the first matching <catch>. What does this mean?

First

The Interpreter starts with all of the <catch> elements in the current scope in the application, and then moves to each enclosing scope. Lastly, it looks in the platform defaults. For each group of elements at the same level, it goes through them from top to bottom, as they appear in the document.

Matching

To be a match, the error specified in the <catch> must either be exactly the same as the error that was thrown, or a prefix of the error that was thrown. That is, an error xxx.yyy.zzz can be caught by a <catch> for xxx.yyy.zzz, for xxx.yyy, or for just xxx. For example: an error.badfetch.http can be caught by a <catch> for error.badfetch.http, error.badfetch, or error.

Because of these rules, the errors are written in the platform default with more specific errors handled before the less specific errors. Error handlers defined in your applications should be ordered similarly.

Example 1

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Error Handling 1"/>
   <catch event="error.badfetch.http.404">
      The requested page cannot be found.
      HTTP error code is 404.
      Goodbye.
      <exit/>
   </catch>
   <catch event="error.badfetch.http">
      The requested page cannot be found, due to HTTP error.
      Goodbye.
      <exit/>
   </catch>
               ...
</vxml>

If a bad fetch error is caught at some point in this application, it will be compared with error.badfetch.http.404 first, to see whether the first handler should catch it. The first handler will catch it only if the bad fetch error has a matching http error code (404). If not, it will be compared to the more general error.badfetch.http in the second handler, to see if this matches a prefix of the thrown error. If this still does not match, the Interpreter will look in the platform defaults, where the error.badfetch handler will match the prefix of the thrown error, and will catch it.

If the handlers had been defined with the general handler first, the behavior will be incorrect. The error.badfetch.http handler would prefix-match any bad fetch error that was thrown while using http, including error.badfetch.http.404, and the more specific handler will never be used.

Example 2—Defining handlers for all specific errors in the set error.connection

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Error Handling 2"/>
   <catch event="error.connection.noauthorization">
      Sorry, you can't make this call. Goodbye.
      <exit/>
   </catch>
   <catch event="error.connection.baddestination">
      Sorry, I don't understand the phone number. Goodbye.
      <exit/>
   </catch>
               ...
</vxml>

If it is not necessary to have such detailed messages given to the caller, you can just define a single handler for the set of errors. This handler will catch all errors that have a matching prefix.

Example 3—Defining one handler for the set of errors with the prefix error.connection

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Error Handling 3"/>
   <catch event="error.connection">
      Sorry, this call cannot be made at this time. Goodbye.
      <exit/>
   </catch>
               ...
</vxml>

This will catch all errors with the prefix error.connection:

  • error.connection.baddestination

  • error.connection.noauthorization

  • error.connection.noresource

  • error.connection.noroute

Check the Event Handling reference for the messages that are defined in the default handler for each error. Remember, errors without completely matching default handlers defined will be caught by the first handler that prefix matches.


Tutorials > General VoiceXML Concepts

Events in VoiceXML

Events can be thrown or caught. Events are thrown if:

  • The user does not respond (<noinput>).

  • The user does not respond intelligibly (<nomatch>).

  • The user requests help (<help>).

  • The Interpreter fails to load, compile, or fetch a specified grammar (see ASR Error Events).

  • The Interpreter finds a semantic error in a VoiceXML document .

  • The Interpreter encounters a <throw> tag .

Note: The first four items are thrown by the ASR platform and the last two items are thrown by the Interpreter.

Categories of Events

  • Pre-defined events

  • Application-defined events

The pre-defined events include:

  • cancel

  • error

  • exit

  • help

  • noinput

  • nomatch

Application-defined events are events that you define and throw from within your application, as in the following goodbye example. You can define an event using the <throw> tag. If it is not pre-defined, you must have a corresponding <catch> tag to process the event.

<throw event="goodbye"/>
<catch event="goodbye">
   <prompt> Goodbye </prompt>
   <disconnect/>
</catch>

You can also throw any of the pre-defined events. For example, typically the help event happens when a user says help. However, you can throw the help event as follows:

<throw event="help"/>
<help>Please say your account number, followed by the number sign.</help>

Shorthand Notation

The <error>, <help>, <noinput>, and <nomatch> tags are shorthand for the most common types of <catch> tags.

  • <error> is short for <catch event="error">

  • <help> is short for <catch event="help">

  • <noinput> is short for <catch event="noinput">

  • <nomatch> is short for <catch event="nomatch">

These tags have count and cond attributes:

  • count—produces a different prompt on subsequent instances of the same event.

  • cond—establishes an optional test to see if the event should be caught by this tag.

For example:

<catch event="noinput">I did not hear you</catch>
<catch event="nomatch" count="1">No.  Please try again.</catch>
<catch event="nomatch" count="2">That still wasn't it.  Give it another try.</catch>
<catch event="nomatch" count="3">Three tries is all you get.  Goodbye!</catch>

Event Scope

Events can be handled at the form level, the document level, or the application level. The event handler used to handle the event will be the one at the most local level from where the event is thrown.

The Interpreter provides a default handler for a few pre-defined events that are not specifically handled within the application (for example, noinput).


From Tag: Restaurant Ordering Tutorial

Tutorials > General VoiceXML Concepts

Form Tag

This tutorial uses a simple restaurant ordering application, and is designed to be a more interesting application than simply demonstrating the <form> tag. You will use this tag in almost every script you write, as it is the primary method of driving interaction with the user.

Step 1

The initial tags will set up your VoiceXML application. Understanding them is not the focus of this tutorial; however, they provide the GVP server with some useful administrative and configuration information.

Start by typing the following code and replace yourname@yourserver.com with your e-mail address.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Form Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <!-- the first form -->
   <!-- the second form -->
</vxml>

Step 2

Add the next block of code to handle the basic forms. After <!-- the first form --> add:

<form id="meal">
</form>
After <!-- the second form --> add in the following:
<form id="desserts">
</form>

Now you have your two forms. Inside these forms, you will have some fields to make your restaurant application interactive as well as dress it up with some short audio clips that can be found in your audio library.

Step 3

The first form is the more complex of the two. It has two different fields, one for whatsnext and one for bill.

Look at whatsnext first. Inside whatsnext, you have a field and a block. The first field accepts either bill or desserts as the choices that the user can enter to progress through the application. If the user chooses bill, the application goes to the bill block using <goto nextitem='bill'/>. If the user chooses desserts, they are brought over to the other form using a <goto next='#desserts'/>.

Fill in the first form with the following:

<field name="whatnext">
  <prompt>
      <audio src="http://developer.genesyslab.com/libraries/audio/misc/restaurant.vox" />
      I hope your main course was to your liking.  Would you like
      any desserts or do you want me to bring you your bill?
   </prompt>
   <grammar type="application/srgs+xml" version="1.0" root="root">
      <rule id="root">
         <one-of>
            <item>bill</item>
            <item>dessert</item>
         </one-of>
     </rule>
   </grammar>
   <filled>
      <if cond="whatnext=='bill'">
         <goto nextitem="bill" />
      <elseif cond="whatnext=='desserts'" />
         <goto next="#desserts" />
      </if>
   </filled>
</field>
<block name="bill">
   Please wait. I am getting your bill for you.
   <audio src="http://developer.genesyslab.com/libraries/audio/misc/cash.vox" />
   Here is your bill.  Thank you for dining with GVP.
   <disconnect/>
</block>

Note: Both TTS and pre-recorded audio are used in the <prompt> tag. The prompt tag defines a series of prompts to be played when the system is ready to accept input from the user. Also, there is no alternative text in the <audio> tag in this example.

The second form is simpler than the first. It presents the user with three options for desserts, and from there, it tells the user their choice. The restaurant wants to make more money so go back to the top and loop through the application again using <goto next='#meal'>.

Fill in the second form with the following:

<field name="dish">
   <prompt>
      What would you like for your dessert?
      We have chocolate delight, blueberry pie, and
      cherry cheesecake
   </prompt>
   <grammar type="application/srgs+xml" version="1.0" root="root">
      <rule id="root">
         <one-of>
            <item>chocolate delight</item>
            <item>blueberry pie</item>
            <item>cherry cheesecake</item>
         </one-of>
      </rule>
   </grammar>
</field>
<filled mode="all" namelist="dish">
  You ordered <value expr="dish"/> as your dessert.
  <goto next="#meal" />
</filled>

Step 4

The next step is to run your application. Below is the sample code.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Example of Form Tag"/>
<property name="bargein" value="false"/>
<property name="confidencelevel" value="0.45"/>
   <!-- the first form -->
   <form id="meal">
      <field name="whatnext">
         <prompt>
            <audio src="http://developer.genesyslab.com/libraries/audio/misc/restaurant.vox" />
            I hope your main course was to your liking.  Would you like
            any desserts or do you want me to bring you your bill?
         </prompt>
         <grammar type="application/srgs+xml" version="1.0" root="root">
            <rule id="root">
               <one-of>
                  <item>bill</item>
                  <item>dessert</item>
               </one-of>
            </rule>
         </grammar>
         <filled>
            <if cond="whatnext=='bill'">
               <goto nextitem="bill" />
            <elseif cond="whatnext=='desserts'" />
               <goto next="#desserts" />
            </if>
         </filled>
      </field>
      <block name="bill">
         Please wait. I am getting your bill for you.
         <audio src="http://developer.genesyslab.com/libraries/audio/misc/cash.vox" />
         Here is your bill.  Thank you for dining with GVP.
         <disconnect/>
      </block>
   </form>
   <!-- the second form -->
   <form id="desserts">
      <field name="dish">
         <prompt>
            What would you like for your dessert?
            We have chocolate delight, blueberry pie, and
           cherry cheesecake
        </prompt>
        <grammar type="application/srgs+xml" version="1.0" root="root">
           <rule id="root">
              <one-of>
                 <item>chocolate delight</item>
                 <item>blueberry pie</item>
                 <item>cherry cheesecake</item>
              </one-of>
           </rule>
        </grammar>
      </field>
      <filled mode="all" namelist="dish">
        You ordered <value expr="dish"/> as your dessert.
        <goto next="#meal" />
     </filled>
  </form>
</vxml>


Tutorials > General VoiceXML Concepts

Prompt Control in VoiceXML

The VoiceXML Interpreter does not play each prompt as it encounters them in the VoiceXML page. Instead, it alternates between a state where it places prompts into a list, in the order it comes across them (this is called queueing); and a state where it plays the prompts in the ordered list.

When are prompts queued, and when are they played?

At any given time, a VoiceXML Interpreter is in one of two states, waiting for input in a field item, or transitioning between field items in response to an input. The Interpreter is in the transitioning state in a <block>, <catch>, <filled>, or other non-field element, as well as while it is transitioning between elements (even across pages).

Prompts are queued while the Interpreter is in the transitioning state. Queued prompts are played either:

  • When the Interpreter reaches the next waiting state (for example, a <field>, <initial>, or <choice>/<menu>), at which point all queued prompts are played and the Interpreter listens for input simultaneously—PromptAndCollect

  • When the Interpreter reaches an <exit>, <transfer>, <record>, or <object>, at which point all queued prompts are played before the element is executed—PromptOnly

  • When the Interpreter begins fetching a resource (such as a document) using <submit>, <goto>, or <subdialog>, with fetchaudio specified. In this case, all queued prompts are played—PromptOnly—and then the fetchaudio is played until the fetch completes.

Note: In the PromptOnly state, no speech input is accepted. Dual Tone Multi Frequency (DTMF) input is allowed, provided that prompt bargein is enabled (see the DTMF Buffering tutorial).

Example 1—Demonstrate prompt queueing

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Prompt Queueing Demo"/>
<form>
   <block>
      <prompt>
         You think you are in a block.
         Please say yes before I finish reading
         this prompt. I will make it very long so
         you have a chance to properly follow my
         instructions.
      </prompt>
   </block>
   <field name="field1" type="boolean">
      <prompt>
         You should not be hearing this.
         Please say no.
      </prompt>
      <filled>
         <if cond="field1">
            It seems like you barged in during a block.
         <else/>
            You were ignored during the block.
         </if>
      </filled>
   </field>
</form>
</vxml>

Explanation:

While in the transitioning state (in the block and during the transition between the block and the field), the Interpreter queues both the prompt from the block and the one from the field. Then, when it reaches the waiting state (in the field), it begins playing the queued prompts, starting with the prompt from the block, while simultaneously waiting for input. The reason you seemed to be able to provide input in the "block" is that you were actually in the field, hearing the queued prompt from the block.

Examples 2 and 3 show the difference between prompt queueing across documents with and without fetchaudio.

Example 2—Demonstrates prompt queueing across documents, using fetchaudio

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Prompt Queueing 2"/>
<form>
   <block>
      <prompt>
         Please say yes before I finish reading
         this prompt. I will make it very long so
         you have a chance to properly follow my
         instructions.
      </prompt>
      <goto next="document2.vxml"
            fetchaudio="http://developer.genesyslab.com/libraries/audio/misc/racecar2.vox"/>
   </block>
</form>
</vxml>

Explanation:

While in the transitioning state (in the block), the Interpreter queues the prompt from the block. Because the fetch uses fetchaudio, the queued prompt is played while the new page is being fetched. The fetchaudio is played afterwards, if necessary, until the fetch is completed. While transitioning to the field in the new page, the field's prompt is queued. Then, when the Interpreter reaches the waiting state (in the field), it begins playing the queued prompt. The reason that you were not able to "barge in" in the block is that this time, you were actually in the block while hearing that prompt, and blocks cannot accept input.

Example 3—Demonstrates prompt queueing across documents, without using fetchaudio

Note: GVP provides a default fetchaudio audio file. To simulate transferring to another document without fetchaudio, this example uses an empty fetchaudio attribute.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Prompt Queueing 3"/>
<form>
   <block>
      <prompt>
         Please say yes before I finish reading
         this prompt. I will make it very long so
         you have a chance to properly follow my
         instructions.
      </prompt>
      <!-- Read note above about fetchaudio -->
      <goto next="document2.vxml" fetchaudio=""/>
   </block>
</form>
</vxml>

Explanation:

While in the transitioning state (in the block), the Interpreter queues the prompt from the block. Because the fetch does not use fetchaudio, the queued prompt is not played before the new page is fetched. So, the page is fetched, and while transitioning to the field in the new page, the field's prompt is queued as well. Then, when the Interpreter reaches the waiting state (in the field), it begins playing the queued prompts, starting with the prompt from the block, while simultaneously waiting for input. The reason you seemed to be able to provide input in the block is that you were actually in the field on the next page, hearing the queued prompt from the block.

How are prompts selected for queueing?

When the Interpreter enters a field element where it is expected to queue prompts, it does the following:

  1. Forms a list of all prompts in the element (in the order they appear).

  2. Removes all prompts whose cond attribute is false.

  3. From the remaining prompts, finds the highest count that is less than or equal to the current count. Remember that the count attribute defaults to 1.

  4. Removes all the prompts that do not have the count found in Step 3. For example, when the Interpreter processes the following code fragment and the current count equals 3, it:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Prompt Selection"/>
<form>
   <var name="playThis" expr="false"/>
   <field name="field1" type="boolean">
      <prompt> please say yes if </prompt>
      <prompt count="2" cond="playThis"> it is true that </prompt>
      <prompt count="2"> you only heard this </prompt>
      <prompt count="4"> one played </prompt>
   </field>
</form>
</vxml>

Prompt selection, when count=3:

  1. Forms a list of all prompts:

  • "please say yes if"

  • "it is true that"

  • "you only heard this"

  • "one played"

  2. Takes out the second prompt because its cond is false. Remaining prompts:

  • "please say yes if"

  • "you only heard this"

  • "one played"

  3. Analyzes the remaining prompts. The first prompt has count="1" by default, the third one has count="2", and the fourth one has count="4". So the highest count less than or equal to the current count (which is 3) is 2.

  4. Takes out the first and fourth prompts because they do not have count="2". Remaining prompts:

  • "you only heard this"

Rules Related to Prompt Queueing

Bargein

In standard compliance mode, if multiple prompts are queued, the bargein attribute/property of each prompt is honored during the period of time in which that prompt is playing. If the com.genesyslab.strictconformance property is set to false, a prompt with bargein enabled will cause bargein to remain enabled for all of the remaining queued prompts. If bargein occurs at any time, all subsequent prompts are not played.

Timeout/Bargeintype

If multiple prompts are queued before a field input, the timeout/bargeintype of the last prompt is used.

Reprompts

It is expected that a catch element provides the appropriate prompts in the course of handling an event, so the Interpreter does not perform the normal selection and queueing of prompts on the next iteration following the execution of a catch element, except in the following two cases:

  • The catch element ends by executing a <goto> or <submit> to another dialog (for example, form or menu), or it ends with a <return> from a subdialog.

  • A <reprompt> is executed in the catch to request that subsequent prompts be played.

Example 4—Reprompt in a <field>

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Reprompts 1"/>
<form>
     <field name="field1" type="boolean">
      <prompt>
         Did you understand?
      </prompt>
      <nomatch>
         Please say yes or no.
      </nomatch>
      <noinput>
      Please say yes or no.
      <reprompt/>
      </noinput>
       ...
   </field>
</form>
</vxml>

If the user says something other than "yes" or "no", the nomatch message ("Please say yes or no") will be played, but when returning to the field on the next iteration, the prompt will not be queued for play. However, if the user does not say anything, the noinput handler will play the message and instruct the Interpreter (with the <reprompt/>) to queue the prompt on the next iteration. So the user will hear "Please say yes or no. Did you understand?".

Example 5—Reprompt in an <initial>

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<meta name="maintainer" content="yourname@yourserver.com"/>
<meta name="application" content="Reprompts 2"/>
<form>
   <grammar src="somegrammar.txt"/>
   <initial name="leaveInit">
      <prompt>
         When do you want to leave?
      </prompt>
      <catch event="noinput nomatch">
         <assign name="leaveInit" expr="true"/>
         <reprompt/>
      </catch>
   </initial>
     <field name="date">
      <prompt>
         Please say the date you wanted to leave on.
      </prompt>
      ...
</form>
</vxml>

In this example, the user is asked a general question ("When do you want to leave?"), which is intended to be answered by something like "Tuesday March 2nd, at 5 o'clock", "Tuesday March 2nd", or "5 o'clock". If the user does not answer, or answers ungrammatically, leaveInit is set to true, so that on the next iteration, the Interpreter will select the date field and collect the first piece of information explicitly. The <catch> must specify a <reprompt/>, if you want the field prompt to be queued for play on the next iteration.

Summary

Good prompts are critical in a well-designed voice application. Therefore, it is important for the developer to understand the concepts explained in this tutorial. Without understanding these concepts, it is difficult to ensure that the application will behave exactly as designed, and callers may be confused by prompts that should not be played, or by silence when an intended prompt is not played.


VoiceXML Tips and Tricks

Tutorials > General VoiceXML Concepts

VoiceXML Tips

Using <assign>

<assign> can be used to fill any tag with a name attribute, such as <block>, <field>, and <initial>, so that this tag will not be visited.

For example:

<block>
   <!-- NOTE: add single quote for string value. -->
   <assign name="field1" expr=" 'filled already' "/>
</block>
<field name="field1">
   <prompt> say something </prompt>
</field>

Because field1 is filled already, it will not be visited.

Using <audio>

It is always a good habit to put alternate text inside the <audio> tag, so that you can check whether your audio source is correct.

For example:

<audio src="thankyou.vox">
  thank you.
</audio>

Using <block>

<block> is a powerful tag in VoiceXML. You can control the flow of your application by using <assign>, <clear>, <goto>, <if>, and <submit>. Also, all of these tags can be placed inside <block>.

For example:

<block>
   <if cond="test2 == undefined">
      <goto nextitem="test2"/>
   </if>
   <assign name="test3" expr="1"/>
   You assigned test3 with value <value expr="test3"/>
   <clear namelist="test1"/>
</block>

If the field test2 is empty, it is visited. Otherwise, assign the field test3 with value 1 making test3 not be visited. By using clear on the field test1, test1 will be visited again.

Using <catch>

Instead of defining a prompt for the catch event, you can also write condition codes inside <catch>.

For example:

<catch event = "noinput" count="2">
  <if cond="test1 == undefined">
    Please say something in test1.
    <reprompt/>
  <elseif cond="test2 == undefined"/>
    Please say something in test2.
    <reprompt/>
  <else/>
    Sorry. I can't give you one more chance for test3. Goodbye.
    <exit/>
  </if>
</catch>

By writing this sample code, the three fields test1, test2, and test3 can use the same noinput event.

Using <clear>

Sometimes, the <clear> tag can be treated as a <goto> tag, but it is more useful than <goto> when the program structure is complex.

For example:

<form>
  <block name="test1">
    Hello!
  </block>
  <block name="test2">
    Repeat once again.
    <!-- clear used the same as <goto nextitem="test1"/> -->
    <clear namelist="test1"/>
  </block>
</form>

According to the preceding sample code, test1 will be visited again, because its element guard variable is cleared (set to an undefined value) in test2.

Using <form>

In a VoiceXML program, more than one form is allowed; however, you have to use the <goto> tag to link them together. Whenever you visit a form, all tags inside the form, such as <block>, <field>, will be cleared, even though they were visited before.

For example:

<form id="test1">
  <block>
    Hi. You are in the first form.
    <goto next="#test2"/>
  </block>
</form>
<form id="test2">
  <block>
    Hi. You are in the second form.
    <goto next="#test1"/>
  </block>
</form>

You will hear the following:

  • "Hi. You are in the first form." (visit the first form)

  • "Hi. You are in the second form." (visit the second form)

  • "Hi. You are in the first form." (visit the first form and prompt again)

GVP will detect an infinite loop and return an error message to the user.

Using <goto>

There are two ways of using <goto> in VoiceXML:

  • Go to another item within a form: <goto nextitem= "tag_name"/>

  • Go to another form within an application: <goto next= "#form_name"/>

Make sure that you are clear about the program flow when using the <goto> tag. It is easy to lose the control in a complicated VoiceXML program when <goto> is used somewhere inside.

For example:

<form>
   <block name= "one"> <goto nextitem= "three"/> </block>
   <block name= "two"> ... </block>
   <block name= "three"> <goto nextitem= "four"/> </block>
   <block name= "four"> ... </block>
   <block name= "five"> ... </block>
</form>

The program flow will be the following:

Block one > Block three > Block four > Block two > Block five

Note: The jump from block one to block three does not mean that block two is ignored. Block two will still be visited later.


Advanced Features

Tutorials > Advanced VoiceXML Concepts

Overview

Many of the tutorials include sample code. Be aware that the code is intended to shows concepts—it has not been tested. Do not expect that these code samples are working models for your applications.

Tutorial Name | Level | Description
Multi-Language ASR Support | Advanced | Explains how to use a variety of ASR engines in your applications, or throughout a single application.
Multiphase Transfer | Advanced | Explains how to perform multiphase transfers, a Genesys Voice XML (GVP) extension that enables a called party to interact with a VoiceXML page before being connected to the caller.
The N-Best Results | Advanced | Explains how to access useful variables stored for the n-best results of the last recognized utterance, as specified by the VoiceXML 2.0 specification.
Using Cookies | Advanced | Provides a general overview of cookies and how they are used in web-based applications. Includes specific details about how to use cookies on the GVP platform, and gives a VoiceXML example.
VoiceXML 2.1 Features | Advanced | Provides an introduction to the 8 features of VoiceXML 2.1.


Tutorials > Advanced VoiceXML Concepts

Multi-Language ASR Support

This topic describes how you can incorporate recognition of different languages into your application, and it includes the following sections:

Background

Support Overview

Usage

  • Creating Multi-Language Grammars

  • Using Multi-Language Built-in Grammars

  • Using Multi-Language Universals

General Notes

Language IDs

Background

Multi-language support is becoming increasingly important as voice applications are deployed worldwide. With new improvements in automatic speech recognition (ASR) engines, Genesys Voice Platform (GVP) is able to offer recognition in many languages. For example:

Using Scansoft OpenSpeech Recognizer 3.0.x and Nuance Recognizer 9.0.x, GVP currently offers support for UK English, US English, France French, German, Italian, Brazilian Portuguese, and US Spanish. Additional languages may be available on request.

Support Overview

  • In general, all of in-line, external, implicit, and built-in grammars are supported for non-English ASR.

  • GVP includes support for VoiceXML applications encoded in ASCII, UTF-8, UTF-16 (Big/Small Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037, IBM1047 and IBM1140 encodings, ISO-8859-N and Windows-1252.

Note: Support of the ISO-8859 encoding standard relies on the version of Xerces (Apache's collection of software libraries for parsing, validating, serializing and manipulating XML) that is installed on the system(s) hosting Genesys software. With Xerces 3.1.1 installed, GVP cannot support: ISO-8859-12, ISO-8859-16, ISO-8859-17, ISO-8859-18, ISO-8859-19.

Earlier versions of Xerces do support ISO-8859; consult the Apache website www.Apache.org to verify which version of Xerces meets your needs.

  • External grammars can be saved in any encoding supported by the ASR engine in use.

  • GVP supports Media Resource Control Protocol (MRCP). In MRCP, the recognition result is conveyed from server to client (Media Control Platform of GVP) in Natural Language Semantics Markup Language (NLSML) format, which is xml-based. The MRCP server can return the recognition result in any encoding that is not the same as the VoiceXML page. The encoding attribute must be used to specify the encoding that is used for the recognition result. The default encoding value is UTF8, if it is not specified.

Example

<?xml version="1.0" encoding = "ISO-8859-1""?>
    <result grammar="session:1c5a96cd_00000674_3fcdf1c0_2701_0002_2">
      <interpretation confidence="78">
            <instance>
                peanut
            </instance>
            <input mode="speech" confidence="78"
                timestamp-start="2001-06-14T12:00:00"
                timestamp-end="2001-06-14T12:00:03">
                peanut
                <extensions>
                    <word-confidence> 78 </word-confidence>
                </extensions>
            </input>
            <extensions>
                <probability> 1035 </probability>
                <nl-probability> 0 </nl-probability>
                <necessary-word-confidence> </necessary-word-confidence>
            </extensions>
        </interpretation>
    </result>

Usage

Creating Multi-Language Grammars

  • It is generally necessary to specify the desired language within the grammar. For example, to write a non-English xml grammar, use xml:lang="language_ID" in the <grammar> tag.

  • Set the encoding in the xml header of the grammar, if applicable, or in the VoiceXML page if the grammar is inline without CDATA.

  • Type (if possible), or cut and paste from a website or file, the desired characters/words/phrases into the grammar. When saving the file, specify the appropriate encoding, if applicable.

Example

This example shows an external grammar that uses US Spanish. It lets the user say "dos cervezas por favor", and returns "two beers please" (if no tag was specified, it would return the recognized Spanish phrase).

<?xml version="1.0" encoding="iso-8859-1"?>
<grammar xml:lang="es-US" version="1.0" root="ROOT"
          xmlns="http://www.w3.org/2001/06/grammar">
   <rule id="ROOT" scope="public">
      <item> <tag>translation='two beers please';</tag>
         dos cervezas por favor
      </item>
   </rule>
</grammar>

Example

This example shows an external grammar that uses French, with accented characters. It lets the user say either "français" or "être", followed by either "libération" or "dépêche".

<?xml version="1.0" encoding="iso-8859-1"?>
<grammar version="1.0" xml:lang="fr-FR" root="TOP"
         xmlns="http://www.w3.org/2001/06/grammar">
    <rule id="TOP" scope="public">
        <ruleref uri="#FIRST"/>
        <ruleref uri="#SECOND"/>
    </rule>
    <rule id="FIRST">
        <one-of>
            <item> français </item>
            <item> être </item>
        </one-of>
    </rule>
    <rule id="SECOND">
        <one-of>
            <item> libération </item>
            <item> dépêche </item>
        </one-of>
    </rule>
</grammar>

Example

This example shows part of a UTF-8 (double-byte) encoded page that uses a Japanese grammar, when displayed in a web browser. Note the following:

  • This example will only run properly on GVP with Japanese Open Speech Recognition (OSR) and Japanese text-to-speech (TTS) installed.

  • Once downloaded and depending on your system (such as operating system's configuration, text editor and web browser), the Japanese characters in the example might not appear as shown below. Instead, they might be displayed as boxes, dots, a numeric encoding such as \347, strange characters, and so on. However, the file should still contain the correct underlying byte representation of the characters, and should still run properly.

Using Multi-Language Built-in Grammars

In general, all of the VoiceXML built-in grammars (boolean, currency, date, digits, number, phone, time) are available in multiple languages, by specifying the language as a parameter, after the grammar type. Here is an example that uses an OSR built-in French phone number grammar. For other languages, see the language ID chart.

Example

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
    <form>
        <field name="phoneValue" type="phone?language=fr-FR">
            <prompt>
                Say a phone number in French.
            </prompt>
            <filled>
                <value expr="phoneValue$.utterance"/>
            </filled>
        </field>
    </form>
</vxml>

Example

Another example, using an OSR built-in German boolean grammar.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
    <form>
        <field name="answer">
            <grammar src="builtin:grammar/boolean?language=de-DE"/>
            <prompt>
                If you speak German, say yes in German.
            </prompt>
            <filled>
                <if cond="answer">
                   Okay, you speak German.
                </if>
            </filled>
        </field>
    </form>
</vxml>

Using Multi-Language Universals

Supported Languages | Behavior
Any installed ASR language | A separate set of hotkey grammars can exist for each installed language, which contain the translated phrases that are equivalent to "help", "cancel", and "exit". Each VoiceXML page can select one set of hotkey grammars to use.

To use a set of hotkey grammars for an installed language other than US English:

  • The platform must have a set of hotkey grammars for the desired language.

  • Specify the desired language for the universal commands, using
    <vxml version="2.0" xml:lang="language ID">    . This selects the set of hotkey grammars with the matching language ID.

  • Enable the universal commands you want (they are turned off by default in VoiceXML 2.0), using:

<property name="universals" value="<Your commands>"/>

Where <Your commands> is a space-separated list of English commands, from the set {help, cancel, exit}. You can use all to enable all three of the universals. The hotkey grammar file with the specified combination of commands will be activated.

  • Define event handlers for the universal commands that are enabled. The English event names are always used, no matter which language is used to recognize the universal commands.

  • When testing your page, you can trigger a universal event (help, cancel, or exit) by saying the corresponding translated phrase.

Example

This example works when French Canadian OSR is installed and universals are set up properly:

<?xml version="1.0"?>
<vxml version="2.0" xml:lang="fr-CA" xmlns="http://www.w3.org/2001/vxml">
   <property name="universals" value="help"/>
   <form>
      <help>
         You said "aide".
         <reprompt>
      </help>
      <field name="field1">
         <prompt>
            Please say "aide".
         </prompt>
      </field>
   </form>
</vxml>

General Notes

When using ASR languages other than English:

  • You may see different distributions of confidence scores and lower average confidence scores with other languages, than you would with US English ASR. For example, many utterances can be recognized with a confidence score around 0.3. In this case, lower the confidencelevel property. If the default value or a value adjusted for a US English application is used (for example, 0.5 or higher), many utterances might be rejected, causing <nomatch>.

  • When a recognition result is spoken in the VoiceXML page, if you want the text to be spoken with the correct accent, make sure that the appropriate TTS engine is installed and specified in the page (for example, <property name="com.genesyslab.ttsengine" value="speechify_felix"/>). Otherwise, the text will be spoken with a US English (or other default) voice.

Language IDs

The following table shows the IDs you might need to specify the language to be used by the recognizer. Not all of these languages are currently supported.

Language | ID | Possible Alternate Form
Cantonese (Hong Kong) | ce-HK (for OSR) / cn-HK | ce*
Catalan | ca-ES | --
Czech | cs-CZ | --
Czech (Slovak) | cssk-CZSK | --
Danish | da-DK | --
Dutch (Netherlands) | nl-NL | nl*
English (Australia) | en-AU | --
English (India) | en-IN | --
English (Singapore) | en-SG | --
English (UK) | en-GB (OSR) / en-UK | --
English (US) | en-US | en*
Finnish | fi-FI | --
French (Canada) | fr-CA | fr*
French (France) | fr-FR | --
German (Austria) | de-AT | --
German (Germany) | de-DE | de*
German (Switzerland) | de-CH | --
Greek | el-GR | --
Hungarian | hu-HU | --
Italian | it-IT | it*
Japanese | ja-JP | ja*
Japanese, using romanized grammars and dictionaries | ja-JP-roman (OSR) | --
Korean | ko-KR | ko*
Korean, using romanized grammars and dictionaries | ko-KR-roman (OSR) | --
Mandarin (Taiwan) | zh-TW | zh*
Mandarin (Taiwan), using romanized grammars and dictionaries | zh-TW-roman (OSR) | --
Norwegian | no-NO | --
Polish | pl-PL | --
Portuguese (Brazil) | pt-BR / pt-PT (OSR) | pt*
Portuguese (Portugal) | pt-PT | --
Russian | ru-RU | --
Slovakian | sk-SK | --
Slovenian | sl-SI | --
Spanish (Argentina) | es-AR | --
Spanish (Latin-America) | es-LA | --
Spanish (Spain) | es-ES | --
Spanish (US) | es-US | es*
Swedish | sv-SE | sv*
Turkish | tr-TR | --
Arabic-Jordan | ar-JO | --
Catalan-Spain | ca-ES | --
Cantonese-Hong Kong | cn-HK | --
Czech-Czech_Republic | cs-CZ | --
Danish-Denmark | da-DK | --
German-Austria | de-AT | --
German-Switzerland | de-CH | --
German-Germany | de-DE | --
Greek-Greece | el-GR | --
Australian English | en-AU | --
English UK | en-GB | --
Indian English | en-IN | --
English-Singapore | en-SG | --
US English | en-US | --
Spanish-Argentina | es-AR | --
Spanish-Colombia | es-CO | --
Spanish | es-ES | --
US Spanish | es-US | --
Basque-Spain | eu-ES | --
Finnish-Finland | fi-FI | --
French-Belgium | fr-BE | --
French-Canada | fr-CA | --
French-France | fr-FR | --
Hebrew-Israel | he-IL | --
Hindi-India | hi-IN | --
Italian-Italy | it-IT | --
Japanese-Japan | ja-JP | --
Kannada-India | kn-IN | --
Korean-Korea | ko-KR | --
Malayalam-India | ml-IN | --
Marathi-India | mr-IN | --
Dutch-Belgium | nl-BE | --
Dutch-Netherlands | nl-NL | --
Portuguese-Brazil | pt-BR | --
Portuguese-Portugal | pt-PT | --
Russian-Russia | ru-RU | --
Swedish-Sweden | sv-SE | --
Tamil-India | ta-IN | --
Turkish-Turkey | tr-TR | --
Mandarin-China | zh-CN | --

* These 2-letter identifiers are only supported with OSR 3.x. OSR does not recommend the use of these 2-letter identifiers. If these identifiers are used in inline grammars, GVP must have the 2-letter identifier configured as a supported language, or an error.unsupported.language will be thrown.


Tutorials > Advanced VoiceXML Concepts

Multiphase Transfers

Genesys Voice Platform (GVP) supports multiphase transfers, an extension that enables the recipient of a transfer to receive some information from a VoiceXML script before deciding whether to accept the call. This topic provides:

Background Information

Initiating Multiphase Transfers

  • Parent Script

  • Child Script

  • Passing Information from Parent to Child

  • Passing Information from Child to Parent

Example

Background Information

In some cases, you might want your VoiceXML application to transfer a caller to a live agent, but you would like the application to first provide the agent with some information about the call. You can achieve this by using a multiphase transfer.

A multiphase transfer allows an application to begin a transfer, play a VoiceXML page for the agent, and allow the agent to decide if he or she will accept the transfer.

Initiating Multiphase Transfers

A multiphase transfer requires two VoiceXML scripts—one to be heard by the original caller, and one to be heard by the agent. The caller's script is the parent script, and the agent's script is the child script.

Parent Script

The parent script is what the caller hears; it starts playing when the call arrives. This is the script that the caller will interact with until the VoiceXML application initiates a transfer. The transfer is initiated with a <transfer> tag that looks like the following:

<transfer name="<Your name>" dest="<Your destination>"
          gvp:consultexpr="<Your ECMAScript expression giving the URI of the child script>" ...>

In the preceding code, <Your name> is an identifier that will be used later, <Your destination> is the destination phone number or SIP address that this call will be transferred to, and <Your ECMAScript expression giving the URI of the child script> specifies the child script that will be played for the agent.

Notes:

  • The URI of the child script cannot exceed 511 characters.

  • All other attributes of the <transfer> tag can still be used, as before.

When such a tag is reached, GVP puts the caller on hold (so the caller will not hear the agent and the script interacting), and calls the number or address indicated by <Your destination> value. When this call is answered, GVP plays the child script for the agent, and after some interaction, the child script passes a special variable back to the parent. If that variable is not set, or is set to something other than true, the agent will be disconnected, the <transfer> <Your name> variable in the parent script will be set to rejected, and the parent script will continue executing from the point where it initiated the transfer attempt. If the variable is set to true, the caller will be connected to the agent with the usual transfer behavior (if the transfer is bridged, the parent script continues executing from the <transfer> tag. If the transfer is non-bridged, the call is disconnected from the platform and the parent script receives a connection.disconnect.transfer event).

Note: To check the result of a transfer attempt, you can either check the value of the <transfer> <Your name> variable, or the value of the special variable returned from the child script. However, in the case of a non-bridged multiphase transfer, it is not necessary to check the transfer result in <filled>, since <filled> will only be executed in the event that the agent rejected the call.

Example parent script

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml" xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
<form>
  <block name="firstblock">
    I am about to transfer your call.
  </block>
   <transfer name="lastTransfer" dest=" sip:dnis@hostname" gvp:consultexpr="'child.vxml'"
            type="consultation">
    <filled>
      Transfer failed.
    </filled>
  </transfer>
   <block name="secondblock">
    If you are hearing this, then your call was not transferred.
  </block>
  <catch event="connection.disconnect.transfer">
    <log>Your call was successfully transferred.</log>
  </catch>
</form>
</vxml>

When a call comes in, the preceding script executes the block named firstblock, and then runs the <transfer> tag, which attempts to connect to the dest. Once connected, GVP plays the script child.vxml for the agent. At some point, child.vxml passes either true or false back to the preceding script:

  • If true, the transfer completes and <catch> handles the connection.disconnect.transfer event (since it is a non-bridged transfer in this example).

  • If false, lastTransfer is set to rejected, and the preceding script continues from where it left off—the <filled> section, and then the block named secondblock.

Child Script

The child script is what the agent hears before GVP connects him or her to the caller. At this point, the caller is on hold and will not hear the agent interacting with the script. The script must, at some point in its execution, assign a value to a special variable called accepttransfer:

  • If set to true, this variable indicates that the agent wants to be connected to the caller (that the transfer should be completed).

  • If not set, or set to something other than true, this variable indicates that the agent does not want to be connected to the caller.

The child script finally returns the result using a line of the form <exit namelist="<Your variables list>"/>. Where <Your variables list> is a list of any variables you want to return to the parent script. This list must include accepttransfer. Any other variables that are optionally passed back to the parent script can be used later.

Example child script

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
<form>
  <field name="yesno" type="boolean">
    <prompt>
      Would you like to accept the call?
    </prompt>
    <filled>
      <if cond="yesno==true">
        <prompt>Connecting you to the caller</prompt>
        <var name="accepttransfer" expr="true"/>
        <exit namelist="accepttransfer"/>
      <else/>
        <prompt>You will not be connected to the caller</prompt>
        <var name="accepttransfer" expr="false"/>
        <exit namelist="accepttransfer"/>
      </if>
    </filled>
  </field>
</form>
</vxml>

When the parent script attempts to transfer the caller to the agent, the preceding script is played for the agent. It starts from the beginning, as normal, and requests DTMF input.

  • If the agent inputs 1, the script sets the variable accepttransfer to true, and then halts using an <exit> tag, where accepttransfer is included in the <exit>'s namelist attribute.

  • If the agent chooses 2, the script behaves as with 1, but sets false instead of true.

Passing Information from Parent to Child

The child script runs in its own Interpreter instance, and so does not have access to the parent script's variables. However, the parent script can pass one string variable, up to 511 characters, to the child script.

You can pass a message string from the parent script to the child script by adding something like the following to your parent script, somewhere before <transfer>,

    <var name="callvars" expr="new Object()"/>
    <block>
        <assign name="callvars.consultdata" expr="< Your ECMAScript expression giving message string>"/>
    </block>

and then adding a gvp:signalvar="callvars" attribute to your <transfer> tag.

Once you have completed the above, you will be able to access the message string from within the child script by referring to the variable session.com.genesyslab.consultdata. For example, you could assign the passed message string to a variable called parentData with a tag like <var name="parentData" expr="session.com.genesyslab.consultdata"/>.

Also, as with a <fork> instance, the child script has access to the session ID of the parent script, by referring to session.com.genesyslab.instance.parent.

Passing Information from Child to Parent

The child script passes its result back to the parent script by listing accepttransfer in the namelist attribute of its <exit> tag. It can also pass additional variables by listing them there.

If, for example, the child script has variables named myTwoCents, newInformation, and endResult, the child script can pass these variables back to the parent script by ending with the following code:

  <exit namelist="accepttransfer myTwoCents newInformation endResult"/>

Note: The total length of the contents of namelist—that is, the total lengths of the variable names and values—must not exceed 4096 characters.

The child script is first activated by a <transfer> tag in the parent script. This <transfer> tag includes a name attribute. Once the child script has ended, the <transfer>'s shadow variables <your transfer name>$.result.* can be used to access the variables that the child script returned.

For example, if the parent script's <transfer> tag includes name="gettingOpinion", and if the child script's <exit> tag looked like the one listed above, the parent script can access the child script's myTwoCents variable by accessing gettingOpinion$.result.myTwoCents. The following variables will also exist:

  • gettingOpinion$.result.accepttransfer

  • gettingOpinion$.result.newInformation

  • gettingOpinion$.result.endResult

The parent script can then, for example, use a tag such as <var name="childsTwoCents" expr="gettingOpinion$.result.myTwoCents"/> to assign that value to a variable named childsTwoCents.

Example

This example expands on both the child and parent scripts presented earlier, adding trivial message passing between them.

Parent script (parent.vxml)

<?xml version="1.0"?>
<vxml Version="2.1" xmlns="http://www.w3.org/2001/vxml" xmlns:gvp="http://www.genesyslab.com/2006/vxml21-extension">
<form id="MainPage">
  <block name="introduction">
    I am about to transfer your call.
  </block>

  <var name="callvars" expr="new Object()"/>
  <block name="assignment">
    <assign name="callvars.consultdata" expr="'data string sent to child'"/>
  </block>

  <transfer name="newCall" dest="sip:dnis@hostname" gvp:consultexpr="'child.vxml'"
             type="consultation" gvp:signalvar="callvars">
    <filled>
      Transfer failed, with answer: <value expr="newCall$.result.answer"/>.
    </filled>
  </transfer>

  <block name="failure">
    If you are hearing this, then your call was not connected.
  </block>
  <catch event="connection.disconnect.transfer">
    <log>
      The call was successfully transferred, with answer:
      <value expr="newCall$.result.answer"/>.
    </log>
  </catch>
</form>
</vxml>

Child script (child.vxml)

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<var name="parentData" expr="session.com.genesyslab.consultdata"/>
<var name="parentID" expr="session.com.genesyslab.instance.parent"/>
<form id="Dialog">
  <field name="yesno" type="boolean">
    <prompt>
      <value expr="parentData" />
      Would you like to accept the call?
    </prompt>
    <filled>
      <if cond="yesno==true">
        <prompt>Connecting you to the caller</prompt>
        <var name="accepttransfer" expr="true"/>
        <var name="answer" expr="'callee has accepted the call'"/>
        <exit namelist="accepttransfer answer"/>
      <else/>
        <prompt>You will not be connected to the caller</prompt>
        <var name="accepttransfer" expr="false"/>
        <var name="answer" expr="'callee was unavailable'"/>
        <exit namelist="accepttransfer answer"/>
      </if>
    </filled>
  </field>
</form>
</vxml>

The parent script executes the first block, which simply plays text. It then creates a new object named callvars, and assigns the text data string sent to child to this new object's consultdata variable. The parent script then attempts the transfer.

The child script begins playing for the agent. It assigns the previously mentioned consultdata to a variable named parentData, and assigns the parent script's session ID to a variable named parentID. It then plays the contents of parentData for the agent, and requests DTMF input ("would you like to accept the call?").

  • If the agent chooses yes, the child script treats this as a "yes" to its question. It assigns the value true to the variable accepttransfer, and the text callee has accepted the call to the variable answer. It then ends execution of the child script with the <exit> tag, passing these two variables along in the namelist attribute.

  • If the agent chooses no, the child script treats this as a "no" to its question. It assigns the value false to the variable accepttransfer, and the text callee was unavailable to the variable answer. It then ends execution of the child script with the <exit> tag, passing these two variables along in the namelist attribute.

  • If the child script set accepttransfer to true, the transfer completes and the parent script receives a connection.disconnect.transfer event (since it is a non-bridged transfer in this example). The parent script catches it, logs the fact that the transfer went through, and logs the contents of answer.

  • If the child script set accepttransfer to false, the parent script resumes execution where it left off, which is in the <transfer> tag. It tells the user that the transfer failed, plays the contents of answer, then executes the block marked failure.


The N Best Results

Tutorials > Advanced VoiceXML Concepts

The N-Best Results

Genesys Voice Platform (GVP) supports returning of the N-best results in a lastresult array, as specified by the VoiceXML 2.0 specification. This topic describes how to use the N-best result feature in your application, as well as the format of the lastresult interpretation. The following sections are included:

Background

Getting Started

Usage

Summary

Background

When the recognizer gets a complete utterance, it uses proprietary complex algorithms that use the utterance, and all of the active grammars as inputs to output a list of guesses as to what the caller said. Each item in this list is associated with a "confidence level" that indicates how sure the speech recognition engine is about this guess. The higher the confidence level, the better the chance that the speech recognition engine guess is close to what the caller said.

Traditionally, after an utterance, the speech recognition engine returns only its best guess of what the caller said. In many circumstances, it may be necessary to obtain other results from the same utterance that the speech recognition engine considers "less" probable. This is likely to happen in cases in which:

  • The caller is in a noisy environment.

  • There is a bad connection.

  • The caller is using a cell phone.

  • The caller utterance is such that multiple results are approximately equally probable, such as the classic example of "Austin", "Boston".

With this new feature, the user is allowed access to the top N-best results. Depending on the format and the content of the application grammars, when a recognition occurs, one or more results are returned either as value strings or slot/value pairs.

To collect the speech recognition information, VoiceXML 2.0 specifies a set of standard application variables, stored in application.lastresult$, to hold the last recognition result that occurs within the application. Additionally, VoiceXML 2.0 also defines a group of shadow variables of a <field> tag to keep the recognition values for each field.

It is important to understand that application.lastresult$ contains the returned data of the last recognition. Part or all of the data that is contained in application.lastresult$ is then assigned to a field variable and its shadow variables.

Getting Started

When N-best recognition is enabled, the top N guesses of the recognizer are returned as a result of what the caller said. The value of N (or how many top guesses of the recognizer are returned) is specified using the property maxnbest. The variable that holds these N-best results is application.lastresult$. It is an array of elements, of size up to N. The actual number of returned results is indicated in the lastresult$.length value. Each element application.lastresult$[i] represents a possible result through the following read-only variables:

application.lastresult$[i].confidence

The confidence level for this interpretation from 0.0-1.0. A value of 0.0 indicates minimum confidence, and a value of 1.0 indicates maximum confidence. This variable is an ECMAScript number.

application.lastresult$[i].utterance

The raw string of words that were recognized for this interpretation. The exact tokenization and spelling is application and platform-specific (for example, "five hundred thirty" or "5 hundred 30" or even "530").

application.lastresult$[i].inputmode

The mode in which user input was provided.

application.lastresult$[i].interpretation

The interpretation (sets of slot/value pairs) returned by the recognizer.

The following is an example of an interpretation element in the form of an ECMAScript object. This is the interpretation of the ith returned result (from the n-best list), which has a slot named firstslotname, filled with the value firstslotvalue. The value of the slot can be accessed in the following way:

application.lastresult$[i].interpretation.firstslotname (which returns firstslotvalue)

Note: If ambiguous slot/value pairs are returned, only the last one is selected as an element of this object.

The following is an example of an interpretation element in the form of a string. This is the interpretation of the ith returned result (from the n-best list), which has a slot named firstslotname, filled with the value firstslotvalue. The slot/value pair can be accessed in the following way:

application.lastresult$[i].interpretation (which returns an object)

For details on other non-standard application variables added as GVP extensions, see the variables reference.

The index i indicates the ith best result from the recognizer; it goes from 0 to application.lastresult$.length - 1, where application.lastresult$.length indicates the actual number of returned results. It is always less than or equal to the system property maxnbest.

Results are sorted by confidence score, from highest to lowest. Different elements in application.lastresult$ will always differ in their utterance, interpretation, or both.

The number of application.lastresult$ elements is guaranteed to be greater than or equal to one and less than or equal to N. If no results have been generated by the system, application.lastresult$ will be ECMAScript undefined.

Shadow Variables of Field Element

The standard shadow variables of a <field> whose name is <field name> are:

  • <field name>$.confidence

  • <field name>$.utterance

  • <field name>$.inputmode

  • <field name>$.interpretation

Note: See the <field> tag reference for a list of non-standard field shadow variables, added as GVP extensions.

The fieldname$.interpretation is set to the same value as the field variable (not necessarily the same as the lastresult interpretation). The other variables are set with the same values as the corresponding properties in the first result (with the highest confidence score): application.lastresult$[0], with one exception. In the case of a nomatch, none of these field shadow variables, nor the field variable itself, will be set. The application.lastresult$ array may be set with any returned results (which have scores below the confidencelevel).

The application.lastresult$ contains all of the returned data of the last recognition, while the field shadow variables are assigned with part or full recognition values from the application.lastresult$ for that particular field.

Usage

When returning the N-best results is enabled by setting the property maxnbest, the results can be accessed in the filled section of the field or form. In the case of transition to a different URI in link or choice, these results are still accessible in the executable content such as a block section. As soon as the recognition results are received, the first item that should be checked is the number of results returned by checking the value of application.lastresult$.length. If that value is greater than 1, the VoiceXML code in the filled section, or any other executable content, can access the actual results as described above.

A typical use of N-best results is, for example, when a customer is requesting the current value of a stock in her portfolio and she speaks the ticker symbol of the stock that she is interested in. A possible set of N values of strings from the recognizer is returned. Each of these values (starting with the highest confidence) can be compared against the stocks contained in her portfolio. The first ticker symbol that matches (that may not be the first result and can be the third) can be used as the ticker symbol of the stock that the customer is interested in.

It is important to understand that GVP can only expose N-best results if the ASR engine returns the results to GVP. After a nomatch, the results are not always returned to GVP. Some ASR engines might only return a nomatch indicator (but no N-best recognition results). In that case, GVP cannot fill any of the lastresult$ variables (they will all be undefined). Some other ASR engines might return a nomatch indicator along with only partial N-best recognition results; in that case, GVP can only fill some of the lastresult$ variables (and the others will be undefined).

Summary

The property related to N-best results:

Property | Description
maxnbest | Max number of results returned by the recognizer.

The variables containing the results:

Variables | Description
application.lastresult$ | Array containing all N values.
application.lastresult$[i].confidence | The confidence value of i-th result.
application.lastresult$[i].interpretation | The Interpretation of i-th result.
application.lastresult$[i].utterance | Utterance of i-th result.
application.lastresult$[i].inputmode | Inputmode of i-th result.
application.lastresult$[i].rawresults | The raw result from ASR.
application.lastresult$.length | Number of results actually returned.

Note: For details on other non-standard application variables added as GVP extensions, see the Variables topic.


Using Cookies with VoiceXML

Tutorials > Advanced VoiceXML Concepts

Using Cookies

Introduction to Cookies

  • How Do Cookies Work?

  • Cookie Expiry Dates

Cookie Example

Summary

Introduction to Cookies

To understand cookies, you should be familiar with web-based client/server interaction. This includes the following:

  • A client (web browser, either visual or audio)

  • A server (web server)

  • HyperText Transfer Protocol (HTTP) interaction, involving repetitions of the browser requesting a page from the web server and the server sending the page to the browser in its response

Note that HTTP does not allow state information to be retained, which means that each request/response interaction is independent of all others. This is acceptable if the pages that are being fetched are unrelated. However, when a sequence of related pages are being fetched, this means that the requests/responses cannot share and reuse common information.

Cookies were developed to extend the capabilities of web-based client/server applications, by providing a solution to the limitations of using stateless HTTP. Using cookies, information can be shared over multiple web pages.

How Do Cookies Work?

Cookies work by allowing information to be stored in a file on the client system, for a certain amount of time. During this time, the server can make use of the information when processing pages. Here is how it works:

Server-side functions are used to generate a Set-Cookie header, which contains client-specific information:

  • NAME=VALUE (required)

  • expires=DATE (optional)

  • domain=DOMAIN_NAME (optional)

  • path=PATH (optional)

  • secure (optional)

A server-side function is used to add the generated cookie header to the HTTP response. When the server sends the response to the client, the client stores the cookie information in a file.

Because the server cannot directly access the client's cookie file, the client passes all relevant cookie information to the server, in the Cookie header of any HTTP requests. The client does this automatically, by checking if any of its stored cookies match the requested URL, and including the name/value pairs of any cookies that match.

A server-side function is used to extract all the cookies from the client's request, so that the developer can use the information in server-side processing.

Cookie Expiry Dates

With a visual browser, there is usually a persistent "real" client-side state—the user—that does not change over a long time period. Therefore, it makes sense to allow stored information about the client-side state to last for a long time too. For this type of long-term information, the developer can specify a cookie expiry date that is far away. Until that expiry date is reached, the cookies will last, even over multiple sessions (browser being opened and closed). For example, a site that requires the user to log in with their user name can make use of cookies to remember and automatically fill in the name after the first login on a browser. This information will be remembered over any number of sessions, until the cookie's expiry date is reached.

With an audio browser, there is no persistent "real" client-side state; many users call in, each with different user information. Therefore, it does not make sense to allow stored information about the client-side state to last for more than the current session. Because there is no long-term information, the developer cannot specify the cookie expiry date. Every cookie in an audio browser will last only during a single session (phone call) and will expire when the session ends. For example, a shopping site can make use of cookies to remember the selected items as the user moves from page to page, until they are ready to pay. After the session ends, the cookie will expire, and information will not be remembered.

Note: Even if expiry dates are given to session cookies, they will expire only when the VoiceXML session ends.

Cookie Example

In the following example, a "count" cookie is used to keep track of how many times a page has been visited, during one session. Create a sample such as test.jsp, and either play the page on a VoiceXML platform (over the phone) or view the page in a visual browser. As you refresh the page, the cookie will keep track of how many times the page has been refreshed. You will hear the number in a prompt or see a new prompt each time. Here is how it works:

  1. The first time that the page is run/viewed, the client's request does not contain the "count" cookie.

  2. The server executes the server-side code, in which it looks for the "count" cookie. Finding no matching cookie, it generates one (and the VoiceXML page) in the response. This response is sent to the client, who stores the "count" cookie and runs/displays the page.

  3. The client sends a subsequent request for this page, and the request contains the "count" cookie.

  4. The server executes the server-side code, in which it looks for the "count" cookie. Finding the matching cookie, it increments the value of the cookie (and generates the VoiceXML page) in the response. This response is sent to the client, who updates the value of the "count" cookie and runs/displays the page.

  5. Steps 3 and 4 are repeated until the user exits the program/closes the browser window.

<%
// This variable will be used to look for the "count" cookie
Cookie countCookie = null;
// The name of the "count" cookie
String countCookieName = "count";
// This variable will be used to hold the value of the "count" cookie
int countCookieValue = 0;
// This variable will flag whether the "count" cookie was found or not
boolean countCookieFound = false;
// All the client's cookies, which were sent in the request
Cookie[] allCookies = request.getCookies();
if (allCookies != null) {
   // Look through the client's cookies, for the "count" cookie
   for (int i=0; i<allCookies.length; i++) {
      countCookie = allCookies[i];
      if (countCookie.getName().equals(countCookieName)) {
         countCookieFound = true;
         break;
      }
   }
}
// If the "count" cookie is found in the client's cookies
if (countCookieFound) {
   // Get the existing value in the "count" cookie
   countCookieValue = Integer.parseInt(countCookie.getValue());
   // Increment the value in the "count" cookie
   countCookie.setValue(Integer.toString(++countCookieValue));
   // Send modified cookie back to the client, in the response
   response.addCookie(countCookie);
}
// If the "count" cookie is not found
else {
   // Create a new cookie with name="count" and value="0"
   Cookie newCookie = new Cookie("count", "0");
   // Send new cookie to the client, in the response
   response.addCookie(newCookie);
}
%>
<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form>
      <block>
<% if (countCookieValue == 0) { %>
         I see this is your first visit to the Cookie Page.
<% } else if (countCookieValue == 1) { %>
         You have refreshed this page 1 time.
<% } else { %>
         You have refreshed this page <%=countCookieValue%> times.
<% } %>
      </block>
      <field name="refresh" type="boolean">
         <prompt>
<% if (countCookieValue == 0) { %>
            Would you like to refresh this page?
<% } else { %>
            Would you like to refresh this page again?
<% } %>
         </prompt>
         <filled>
            <if cond="refresh">
               Okay.
               <submit next="test.jsp"/>
            <else/>
               Okay. Thanks for calling. Goodbye.
            </if>
         </filled>
      </field>
   </form>

</vxml>

In this example, the server-side code is written in JavaServer Pages (JSP). However, the same idea can be used to do the same with any other server-side technology. The structure will basically be the same; only the syntax should be different.

Summary

After reading this tutorial, you should have a good understanding of the motivation for using cookies, as well as how they work (at a low level) and how they can be used in web pages (at a higher level). However, there is much more that has not been mentioned here, such as the pros and cons of using cookies. Also, remember that there are other methods of sharing information over multiple web pages that are not mentioned here, which can be useful alternate solutions, depending on the situation.


Tutorials > Advanced VoiceXML Concepts

VoiceXML 2.1 Features

Many VoiceXML platform vendors have developed additional, innovative features beyond VoiceXML 2.1, to offer improvement and advancement to the technology.

The VoiceXML 2.1 specification defines a set of eight commonly implemented additional features to VoiceXML 2.0, ensuring portability between platforms and maintaining backward-compatibility with VoiceXML 2.0. For details, refer to the latest version of the VoiceXML 2.1 specification.

Genesys Voice Platform (GVP) has full support for VoiceXML 2.1. The following sections give an overview of how each of the eight features can be used:

  • Referencing Grammars Dynamically (<grammar> srcexpr)

  • Referencing Scripts Dynamically (<script> srcexpr)

  • Accessing Information About Prompt Barge-in (<mark>)

  • Fetching XML Without a Dialog Transition (<data>)

  • Concatenating Prompts Dynamically (<foreach>)

  • Recording User Utterances

  • Using <disconnect> Namelist

  • Using <transfer> Type

Referencing Grammars Dynamically (<grammar> srcexpr)

With VoiceXML 2.1, the Uniform Resource Identifier (URI) of a grammar can be found at runtime by evaluating an ECMAScript expression. This makes it easy to reference grammars dynamically without any server-side processing.

This is done through a new <grammar> srcexpr attribute. The <vxml> version attribute must be specified as 2.1 (or higher) to use this feature.

Dynamic grammars can be used to improve recognition accuracy by implementing a sequence of fields with smaller, more focused grammars that narrow down what the caller wants, instead of using a single large grammar. This is shown in the example in the VoiceXML specification, in which the caller specifies a city/state, and then is asked to choose a street from a list of only the streets in the specified city/state. This approach can also reduce ambiguity in the same types of scenarios. Another benefit of dynamic grammar selection is that the application can select custom grammars as soon as the caller's identify is known. For example:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <!-- Assume caller's identity was verified in a previous field. -->
   <var name="callerName" expr="'john_doe'"/>
   <form>
      <field name="contactList">
         <!-- Add a grammar that allows 'family', 'friends', 'work', and 'other'. -->
         <grammar src="contactListTypes.grxml" type="application/srgs+xml"/>
         <prompt> Which contact list do you want? </prompt>
      </field>
      <field name="whoToCall">
         <!-- Add contact list grammars, named like 'john_doe_family.grxml'. -->
         <grammar srcexpr="callerName+'_'+contactList+'.grxml'" type="application/srgs+xml"/>
         <prompt>
            Okay, say a name from your
            <value expr="contactList"/>
            contact list.
         </prompt>
         <filled>
            Calling <value expr="whoToCall"/>.
         </filled>
      </field>
   </form>
</vxml>

Referencing Scripts Dynamically (<script> srcexpr)

With VoiceXML 2.1, the URI of a script file can be found at runtime by evaluating an ECMAScript expression. This makes it easy to reference scripts dynamically without any server-side processing.

This is done through a new <script> srcexpr attribute. The <vxml> version attribute must be specified as 2.1 (or higher) to use this feature.

A benefit of dynamic script selection is that the application can select custom scripts as soon as certain information about the caller is known. In the following example, the caller's preferred language is American English. The specified script contains functions that will format various types of digit input, so that it can be read back to the caller by using the appropriate dialect.

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <!-- Assume caller chose to use English in a previous field. -->
   <var name="language" expr="'en-US'"/>
   <form>
      <!-- Add a script called 'formatting_en-US.js', that -->
      <!-- defines the formatDate() function used below. -->
      <script srcexpr="'formatting_'+language+'.js'"/>
      <field name="month" type="digits?length=2">
         <prompt> Please enter the two digits for the month. </prompt>
      </field>
      <field name="day" type="digits?length=2">
         <prompt> Please enter the two digits for the day. </prompt>
      </field>
      <filled>
         Okay, I've scheduled you for
         <!-- The function from the en-US script returns a date string -->
         <!-- like 'january first', rather than 'the first of january'. -->
         <value expr="formatDate(month,day)"/>.
      </filled>
   </form>
</vxml>

Accessing Information About Prompt Barge-in (<mark>)

With VoiceXML 2.1, if the prompt has an SSML text/tag sequence containing <mark> markers (as defined in the SSML specification), the VoiceXML application can access timing information about barge-in during prompt playback.

This is done through two new variables: markname and marktime. When barge-in occurs, or the end of audio playback is reached, these variables give the name of the mark that was last executed by the Speech Synthesis Markup Language (SSML) processor during audio output, and the number of milliseconds that elapsed since that mark was executed, respectively. These variables can be referenced as properties of the application.lastresult$ variable, or as properties of the field/record/transfer shadow variable, if applicable. In addition, VoiceXML 2.1 extends the <mark> tag with a new nameexpr attribute. The <vxml> version attribute must be specified as 2.1 (or higher) to use this feature.

Here is an example that uses <mark> at the beginning and end of an advertisement. In <filled>, the code checks which mark, if any, was last executed when barge-in occurred. If the ad_start mark is executed but ad_end is not, the code checks that at least five seconds of the advertisement have been played and sets the played_ad variable appropriately:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
  <var name="played_ad" expr="false"/>
  <form>
    <field name="field1" type="boolean">
      <prompt>
        <mark name="ad_start"/>
        Baseball scores brought to you by Elephant Peanuts.
        There's nothing like the taste of fresh roasted peanuts.
        Elephant Peanuts. Ask for them by name.
        <mark name="ad_end"/>
        <break time="500ms"/>
        Would you like to continue?
      </prompt>
      <filled>
        <!-- application.lastresult$ could be used instead of field1$. -->
        <if cond="typeof(field1$.markname) == 'string' &amp;&amp;
           (field1$.markname=='ad_end' ||
           (field1$.markname=='ad_start' &amp;&amp;
              field1$.marktime &gt;= 5000))">
          <assign name="played_ad" expr="true"/>
        <else/>
          <assign name="played_ad" expr="false"/>
        </if>
      </filled>
    </field>
  </form>
</vxml>

Note: Use of this feature depends on whether the SSML processor (the text-to-speech engine) supports <mark>. That is, when <mark> is executed during audio output, if the SSML processor neither allows the VoiceXML Interpreter to retrieve the mark information nor informs the Interpreter about the mark, the Interpreter will not have any mark information to store in the markname and marktime variables.

Fetching XML Without a Dialog Transition (<data>)

The VoiceXML 2.1 specification states: "The <data> element allows a VoiceXML application to fetch arbitrary XML data from a document server without transitioning to a new VoiceXML document." For more details on this new element, see the <data> tag.

Concatenating Prompts Dynamically (<foreach>)

With VoiceXML 2.1, there is support for looping through an array (as in ECMAScript and various other programming languages) to execute some specified content for each item in the array. The primary purpose of this feature is to allow dynamic concatenation of prompts. It can also be used to create a sequence of executable content.

This feature is supported through the <foreach> tag, with attributes array and item. The array attribute specifies the array that will be looped through, and the item attribute specifies a variable that will reference the item of the array for the current iteration. The <vxml> version attribute must be specified as 2.1 (or higher) to use this feature.

In the following example, the array of horoscope signs is used to concatenate the 12 corresponding audio files (aries.vox). If the audio files are not found (try misspelling part of the path to test this), the array entries will be read as text-to-speech (TTS):

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <var name="zodiac" expr="new Array('aries','taurus','gemini','cancer','leo',
                                      'virgo','libra','scorpio','sagittarius',
                                      'capricorn','aquarius','pisces')"/>
   <form>
      <block>
         The 12 signs of the zodiac are:
         <foreach array="zodiac" item="sign">
            <!-- On each iteration of the loop, this plays out audio like -->
            <!-- 'http://developer.genesyslab.com/libraries/audio/horoscopes/aries.vox'. -->
            <audio expr="'http://developer.genesyslab.com/libraries/audio/horoscopes/'
                         + sign + '.vox'">
               <!-- If the audio is not found, use TTS -->
               <!-- to read out something like 'aries'. -->
               <value expr="sign"/>
            </audio>
         </foreach>
      </block>
   </form>
</vxml>

The VoiceXML specification gives two examples. The first, which is similar to the preceding example, is a simple application that concatenates prompts to play a list of movie titles. The second example is quite complex, as it combines several VoiceXML 2.1 features. Like the first, it uses <foreach> to concatenate prompts, both to play a list of movie titles to the caller and to play a list of details after the caller chooses a title. However, it also makes use of <mark> in the movie list, so that the application can figure out which title was being played when the caller barged in to ask for more details. It also makes use of the <data> feature to retrieve the movie information, and it implements functions that extract the list of movie titles and movie details from the retrieved XML data.

Note: GVP supports the <foreach> tag as a VoiceXML 2.1 extension (where <foreach> is not supported as a child of <prompt>). For details on using this feature, see the <foreach> tag.

Recording User Utterances

With VoiceXML 2.1, user utterances can be recorded during recognition (in a field/initial/menu, including when using a link grammar). The recorded utterances can be played back in the VoiceXML application, or can be sent to the back-end server to perform some processing, such as for caller identification/verification, or to be saved for later statistical use (determining caller usage patterns).

The feature is enabled by setting the recordutterance property to true. The recording data can then be accessed by referencing recording, recordingsize, and recordingduration, as properties of the application.lastresult$ variable, or as properties of the field shadow variable, if applicable. The <vxml> version attribute must be specified as 2.1 (or higher) to use this feature.

For example:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <form>
      <property name="recordutterance" value="true"/>
      <field name="pin" type="digits?length=4">
         <prompt> Please say your 4 digit pin. </prompt>
         <filled>
            I heard you say <value expr="pin"/>.
            <!-- In the following, pin$ could be used instead of application.lastresult$. -->
            Here's how you sounded:
            <value expr="application.lastresult$.recording"/>
            That recording had a size of
            <value expr="application.lastresult$.recordingsize"/> bytes.
            And it has a duration of
            <value expr="application.lastresult$.recordingduration"/>.
         </filled>
      </field>
   </form>
</vxml>

The format of the recorded utterance can be specified by using the recordutterancetype property, which can be set to one of the media types in the following chart (default is audio/basic):

Audio Format | Media Type
Raw (headerless) 8kHz 8-bit mono mu-law [PCM] single channel (G.711) | audio/basic
Raw (headerless) 8kHz 8-bit mono A-law [PCM] single channel (G.711) | audio/x-alaw-basic
WAV (RIFF header) 8kHz 8-bit mono mu-law [PCM] single channel | audio/x-wav
WAV (RIFF header) 8kHz 8-bit mono A-law [PCM] single channel. | audio/x-wav

Notes:

  • The recording utterances feature is not supported for <record> or <transfer>.

  • The recording will not be set for application.lastresult$[i] for i > 0.

  • The recording will be made available in <filled> and <nomatch> sections. However, in <nomatch>, the recording is available only through the application.lastresult variable (never through a field shadow variable).

  • GVP's saved-utterance extension also includes the com.genesyslab.utterancedest property (or the utterancedest attribute), which can be used to specify a disk location for the saved utterance, in order to save a permanent copy of the utterance audio file on the platform after the call ends. The com.genesyslab.utterancedest property (or the utterancedest attribute) can be used equally with either the GVP saved-utterance extension or the VoiceXML 2.1 record-utterance feature.

Using <disconnect> Namelist

With VoiceXML 2.1, when the application disconnects the caller from the Interpreter context, a list of variables can be passed back to the Interpreter for further processing. This is done through the <disconnect> namelist attribute. The <vxml> version attribute must be specified as 2.1 (or higher) to use this feature.

For example:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <form>
      <field name="number" type="phone">
         <prompt> What number did you want to call? </prompt>
      </field>
      <block>
         <prompt>
            Got it. Calling <value expr="number"/>.
         </prompt>
         <disconnect namelist="number"/>
      </block>
   </form>
</vxml>

Using <transfer> Type

With VoiceXML 2.1, the Interpreter can be directed to connect the caller to another entity by using a bridge, blind, or consultation transfer. This is done through a new <transfer> type attribute, with values bridge, blind, and consultation. It is not required that the <vxml> version attribute be specified as 2.1 (or higher) to use this feature.

For example:

<?xml version="1.0"?>
<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">
   <catch event="connection.disconnect.transfer">
      <log> Transfer result: successful connection </log>
   </catch>
   <catch event="error">
      <log> Transfer result: <value expr="_event"/> </log>
   </catch>
   <form>
      <!-- Change the specified destination number. -->
      <transfer name="xfer" dest="tel:4165551234" type="consultation">
         <prompt> Transferring your call. </prompt>
         <filled>
            <log> Transfer result: <value expr="xfer"/> </log>
         </filled>
      </transfer>
   </form>
</vxml>

Note: For more details, see the <transfer> tag.


Overview: Sample VoiceXML Applications

Sample Voice XML Applications

Overview

This section provides details on:

  • CTI Interactions, which provides sample VoiceXML applications that demonstrate how to access CTI interaction data.

  • Functions, which provides the code for the functions that are called in the sample VoiceXML applications.


CTI Interactions

Sample Voice XML Applications > CTI Interactions

Overview

The following topics provide VoiceXML code samples that show how to access call data during:

  • Call Setup

  • Mid Call

  • Initiate Transfer

  • Treatments (Post Initiate Transfer)

  • Transfer Complete


Call Setup

Sample Voice XML Applications > CTI Interactions > Call Setup

Overview

The following topic shows how to access call data during call setup:

  • AttachedData in the Invite headers


AttachedData in the incoming Invite headers

Sample Voice XML Applications > CTI Interactions > Call Setup

Attached Data in the Incoming Invite Headers

Attached data, prefixed with X-Genesys-, is appended to the INVITE header by the SIP Server as follows:

INVITE sip:dialog@mcp;voicexml=http://appserver/promptcollect.vxml SIP/2.0
Via: SIP/2.0/UDP 192.0.2.4;branch=z9hG4bK776asdhds
Max-Forwards: 70
To: <sip:user@mcp>
From: <sip:caller@example.com>;tag=1928301774
Call-ID: a84b4c76e66710@example.com
CSeq: 1 INVITE
Contact: <sip:caller@example.com>
X-Genesys-customername: acme
X-Genesys-customerid: 1234
X-Genesys-action: pincollection
Content-Type: application/sdp

Once the Media Control Platform (MCP) receives the INVITE, the SIP headers are processed and the attached data is available in the VoiceXML session.com.genesyslab.userdata.* session variables (with X-Genesys- removed):

session.com.genesyslab.userdata[’customername’]=’acme’;
session.com.genesyslab.userdata[’customerid’]=’1234’;
session.com.genesyslab.userdata[’action’]=’pincollection’;


Mid Call

Sample Voice XML Applications > CTI Interactions > Mid Call

Overview

If the Genesys CTI Connector is in the call path, all of the following computer telephony integration (CTI) interactions are possible during mid call:

  • GetData

  • SetData (Add)

  • SetData (Replace)

  • DeleteData (Delete One)

  • DeleteData (Delete All)

  • GetStat

  • PeekStat

  • AccessNumGet

Accessing Mid-Call Data

To take advantage of the above functions:

  • The Resource Manager (RM) must be configured.

  • The VoiceXML application must verify that the RM was configured.

The Resource Manager

The RM must append the following to the X-Genesys-GVP-Session-ID SIP header:

X-Genesys-GVP-Session-ID:800DB7A5-33C6-45CB-7E9F-410507B7097A;gvp.rm.datanodes=1;gvp.rm.cti-call=1

The VoiceXML Application

In the VoiceXML application, check for the presence of gvp.rm.cti-call=1 as follows:

<script>
   //Is this a CTI-Connector call from X-Genesys-GVP-Session-ID?
   function isCTICCall ( strUserData )
   {
      if ( strUserData != undefined)
      {
         if ( strUserData.indexOf( "gvp.rm.cti-call=1" ) >= 0 )
         {
            return "true";
         }
      }
      return "false";
   }
   var AppState=new Object();
   if (session.com.genesyslab.userdata != undefined)
   {
      AppState.GVPSessionID = session.com.genesyslab.userdata['gvp-session-id'];
      AppState.g_CTICCall = isCTICCall( AppState.GVPSessionID );
   }
   else
   {
      AppState.GVPSessionID = 'undefined';
      AppState.g_CTICCall = 'false';
   }
   // Use AppState.g_CTICCall henceforth to check if this call used
   // CTI-C or not...
</script>

All the mid call CTI functions are invoked using the <send> and <receive> tags (which translate to SIP INFO at the protocol level between the Media Control Platform and the CTI Connector) as follows:

  • SIP INFO messages are sent from the Media Control Platform (MCP) to the CTI Connector using <send>.

  • VoiceXML application blocks waiting for data back from the CTI Connector using <receive>.

  • Once CTI Connector sends back the data to the MCP using the SIP INFO method, <receive> unblocks.
    <receive>     may unblock for other reasons. For example, an incoming http trigger instead of SIP INFO, or SIP INFO that is not from CTI Connector. To verify that <receive> received the SIP INFO from the CTI Connector, check:
    - If application.lastmessage$.sourcetype = = "sip"
    - If application.lastmessage$.contenttype = = "application/x-www-form-urlencoded;charset=utf-8"


Sample Voice XML Applications > CTI Interactions > Mid Call

GetData

An application requests data from the Universal Routing Server (URS) strategy by passing data-key names to the URS as follows:

<script>
  var Action = "GetData";
  var KeyName1 = "GRAMMARFILEDIR";
  var KeyName2 = "VOXFILEDIR";
</script>
<gvp:send namelist="Action KeyName1 KeyName2" async="false"/>
<gvp:receive maxtime="10s"/>
<var name="GetDataMessage" expr="application.lastmessage$.content"/>
<var name="arrUserData" expr="getUserDataArray(GetDataMessage)"/>
<var name="GetDataResult" expr="utilGetReceiveDataValue('Result', arrUserData)"/>
<if cond="GetDataResult != 'SUCCESS'">
   <var name="GetDataResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)"/>
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="GetDataResultReason" />
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

SetData (Add)

An application sends data to the Universal Routing Server (URS) strategy as key-value pairs in the SIP INFO message, as follows:

<script>
   var Action = "AttachData";
   var sub_action = "Add";
   var GRAMMARFILEDIR = AppState.GRAMMARFILEDIR;
   var VOXFILEDIR = AppState.VOXFILEDIR;
</script>
<gvp:send namelist="Action sub_action GRAMMARFILEDIR VOXFILEDIR" async="false"/>
<gvp:receive maxtime="10s"/>
<var name="SetDataMessage" expr="application.lastmessage$.content"/>
<var name="arrUserData" expr="getUserDataArray(SetDataMessage)"/>
<var name="SetDataResult" expr="utilGetReceiveDataValue('Result', arrUserData)"/>
<if cond="SetDataResult != 'SUCCESS'">
  <var name=" SetDataResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)"/>
  <throw event="error.com.genesyslab.studio.receiveerror" messageexpr=" SetDataResultReason"/>
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

SetData (Replace)

An application can replace the value of a data item that was previously set using the SetData feature, as follows:

<script>
   var Action = "AttachData";
   var sub_action = "Replace";
   var GRAMMARFILEDIR = "GRAMMARFILEDIR";
   var VOXFILEDIR = "VOXFILEDIR";
</script>
<gvp:send namelist="Action sub_action GRAMMARFILEDIR VOXFILEDIR" async="false"/>
<gvp:receive maxtime="10s"/>
<var name="ReplaceDataMessage" expr="application.lastmessage$.content"/>
<var name="arrUserData" expr="getUserDataArray(ReplaceDataMessage)"/>
<var name="ReplaceDataResult" expr="utilGetReceiveDataValue('Result', arrUserData)"/>
<if cond="ReplaceDataResult != 'SUCCESS'">
   <var name="ReplaceDataResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)"/>
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="IReplaceDataResultReason"/>
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

DeleteData (Delete One)

An application can selectively delete a data value that was previously set, as follows:

<script>
var Action = "DeleteData";
var sub_action = "DeleteKey"
var KeyName = "VOXFILEDIR"
</script>
<gvp:send namelist="Action sub_action KeyName" async="false"/>
<gvp:receive maxtime="10s" />
<var name="DeleteOneMessage" expr="application.lastmessage$.content"/>
<var name="arrUserData" expr="getUserDataArray(DeleteOneMessage)"/>
<var name="DeleteOneResult" expr="utilGetReceiveDataValue('Result', arrUserData)"/>
<if cond="DeleteOneResult != 'SUCCESS'">
  <var name="DeleteOneResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)"/>
  <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="DeleteOneResultReason"/>
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

DeleteData (Delete All)

An application can delete all data that was previously set, as follows:

<script>
   var Action = "DeleteData";
   var sub_action = "DeleteAll"
</script>
<gvp:send namelist="Action sub_action" async="false" />
<gvp:receive maxtime="10s" />
<var name="DeleteAllMessage" expr="application.lastmessage$.content" />
<var name="arrUserData" expr="getUserDataArray(DeleteAllMessage)" />
<var name="DeleteAllResult" expr="utilGetReceiveDataValue('Result', arrUserData)" />
<if cond="DeleteAllResult != 'SUCCESS'">
   <var name="DeleteAllResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)" />
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="DeleteAllResultReason" />
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

GetStat

An application can request statistics from the Stat Server, as follows:

<script>
   var Action = "GetStatReq";
   var ServerName = "abc";
   var StatType = "call";
   var ObjectID = "123";
   var ObjectType = "queue";
</script>
<gvp:send namelist="Action ServerName StatType ObjectID ObjectType" async="false" />
<gvp:receive maxtime="10s" />
<var name="Statistics1Message" expr="application.lastmessage$.content" />
<var name="arrUserData" expr="getUserDataArray(Statistics1Message)" />
<var name="Statistics1Result" expr="utilGetReceiveDataValue('Result', arrUserData)" />
<if cond="Statistics1Result != 'SUCCESS'">
   <var name="Statistics1ResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)" />
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="Statistics1ResultReason" />
<else />
   <assign name="AppState.Statistics1" expr="utilGetReceiveDataValue('ResultCode', arrAccessNumGet)" />
   <if cond="AppState.Statistics1 == undefined">
      <throw event="error.com.genesyslab.studio.invalidkey" message="Missing Statistics key 'AppState.Statistics1'" />
   </if>
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

PeekStat

An application can request two kinds of statistics (as follows):

  • CurrNumberWaitingCalls

  • ExpectedWaitTime

<script>
var Action = "PeekStatReq";
var statname = "CurrNumberWaitingCalls";
</script>
<gvp:send namelist="Action statname" async="false" />
<gvp:receive maxtime="10s" />
<var name="Statistics1Message" expr="application.lastmessage$.content" />
<var name="arrUserData" expr="getUserDataArray(Statistics1Message)" />
<var name="Statistics1Result" expr="utilGetReceiveDataValue('Result', arrUserData)" />
<if cond="Statistics1Result != 'SUCCESS'">
   <var name="Statistics1ResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)" />
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="Statistics1ResultReason" />
<else />
   <assign name="AppState.Statistics1" expr="utilGetReceiveDataValue('ResultCode', arrAccessNumGet)" />
   <if cond="AppState.Statistics1 == undefined">
      <throw event="error.com.genesyslab.studio.invalidkey" message="Missing Statistics key 'AppState.Statistics1'" />
   </if>
</if>


Sample Voice XML Applications > CTI Interactions > Mid Call

AccessNumGet

This computer telephony integration (CTI) feature is used for remote switch transfers. Interaction data (UData and ExtnsEx, not CED) can be sent with an AccessNumGet request. First, the interaction data is sent prior to the actual AccessNumGet request. Second, the AccessNumGet feature is not possible in Network mode (this is a limitation of IServer).

<script>
   var Action = "GenericData";
   var sub_action = "ExtnsEx";
   var VOXFILEDIR = AppState.VOXFILEDIR;
</script>
<gvp:send namelist="Action sub_action VOXFILEDIR" async="false" />
<gvp:receive maxtime="10s" />
<var name="AccessNumGet1Message" expr="application.lastmessage$.content" />
<var name="arrUserData" expr="getUserDataArray(AccessNumGet1Message)" />
<var name="AccessNumGet1Result" expr="utilGetReceiveDataValue('Result', arrUserData)" />
<if cond="AccessNumGet1Result != 'SUCCESS'">
   <!-- Possibilities: undefined/timeout/<iserver error message> -->
   <var name="AccessNumGet1ResultReason" expr="utilGetReceiveDataValue('Reason', arrUserData)" />
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="AccessNumGet1ResultReason" />
</if>
<!-- Do AccessNumGet -->
<script>
   var Action = "AccessNumGet";
   var DestDN = "1234";
   var Location = "abcd";
</script>
<!--Get data using the CTI Connector -->
<gvp:send namelist="Action DestDN Location" />
<gvp:receive maxtime="10s" />
<var name="AccessNumGetContent" expr="application.lastmessage$.content" />
<var name="arrAccessNumGet" expr="getUserDataArray( AccessNumGetContent )" />
<var name="AccessNumGet1Result" expr="utilGetReceiveDataValue('Result', arrAccessNumGet)" />
<if cond="AccessNumGet1Result != 'SUCCESS'">
   <var name="AccessNumGet1ResultReason" expr="utilGetReceiveDataValue('Reason', arrAccessNumGet)" />
   <throw event="error.com.genesyslab.studio.receiveerror" messageexpr="AccessNumGet1ResultReason" />
<else />
   <assign name="AppState.AccessNumGet1" expr="utilGetReceiveDataValue('AccessNum', arrAccessNumGet)" />
   <if cond="AppState.AccessNumGet1 == undefined">
      <throw event="error.com.genesyslab.studio.invalidkey" message="Missing AccessNumGet key 'AppState.AccessNumGet1'" />
   </if>
</if>


Initiate Transfer

Sample Voice XML Applications > CTI Interactions > Initiate Transfer

Overview

After the interactive-voice-response (IVR) phase of a call, a VoiceXML application can request data during:

  • Blind Transfer

  • Bridge Transfer

To make this possible, and to differentiate from a regular transfer, the <transfer> tags, dest attribute, RouteRequest parameter must equal 1 as shown in the Transfer Tag section below. When this parameter is present, the CTI Connector intercepts the transfer and routes it using the IServer.

Transfer Tag

Blind Transfer

For a Blind Transfer, the <transfer> tag, dest attribute, RouteRequest parameter is set, as follows:

<transfer type=”blind” dest=”sip:9000@10.10.30.67:5060;RouteRequest=1” />

This results in a REFER message with the following Refer-To header:

Refer-To: sip:9000@10.10.30.67:5060;RouteRequest=1

Bridge Transfer

For a Bridge Transfer, the <transfer> tag, dest attribute, RouteRequest parameter is set, as follows:

<transfer type=”bridge” dest=”sip:9000@10.10.30.67:5060;RouteRequest=1” />

This results in an INVITE message with the following To header:

To: sip:9000@10.10.30.67:5060;RouteRequest=1

Types of Interaction Data Sent

The types or interaction data that can be sent with a transfer request includes:

  • CED

  • UData

  • ExtnsEx

At the protocol level, this data is sent using SIP headers. Specifically, in the REFER header for blind transfer, and the INVITE header for bridge transfer. Note: The three types of data can be sent simultaneously, so they must be identified:

  • CED data must be named CED (see the following script)

  • UData data must be prefixed with UData_ (see the following script)

  • ExtnsEx data must be prefixed with ExtnsEx_ (see the following script)

<script>
<var name=”myUserData” expr=”new Object()”/>
<assign name=”myUserData[‘CED’]” expr=”1”/>
<assign name=”myUserData[‘UData_param1’]” expr=”3”/>
<assign name=”myUserData[‘UData_param2’] expr=”4”/>
<assign name=”myUserData[‘ExtnsEx_param1’] expr=”5”/>
<assign name=”myUserData[‘ExtnsEx_param2’] expr=”6”/>
</script>
<transfer dest=”sip:9000@10.10.30.67:5060;RouteRequest=1” type=”blind” gvp:userdata=”myUserData”/>

This translates to the following SIP header (REFER or INVITE ):

X-Genesys-CED: 1
X-Genesys-Udata_param1: 3
X-Genesys-Udata_param2: 4
X-Genesys-ExtnsEx_param1: 5
X-Genesys-ExtnsEx_param2: 6


Sample Voice XML Applications > CTI Interactions > Initiate Transfer

Blind Transfer

This shows an example of a REFER transfer. The VoiceXML session ends after the transfer to the route DN is successful.

<form id="RouteRequest1">
   <property name="inputmodes" value="dtmf" />
   <script>
      var RouteRequest1Destination = '1234';
      var userdata = new Array();
   </script>
   <block>
      <if cond="AppState.g_CTICCall == 'false'">
         <script>
            userdata["GRAMMARFILEDIR"] = AppState.GRAMMARFILEDIR;
            userdata["VOXFILEDIR"] = AppState.VOXFILEDIR;
            userdata["SCRIPTSDIR"] = AppState.SCRIPTSDIR;
         </script>
         <log>
            userdata= <value expr="userdata.toSource()" />
         </log>
      <else />
         <var name="userTransferType" expr="'blind'" />
         <if cond="userTransferType == 'consultation'">
            <throw event="error.com.genesyslab.studio.unsupported"
                   message="Consultation transfer is not support with CTIConnector."
            />
         <else />
            <assign name="RouteRequest1Destination"
                    expr="RouteRequest1Destination + ';RouteRequest=1'"
            />
            <!-- Do userdata SIP INFO here. Check result using <receive> -->
            <script>
               var Action = "GenericData";
               var sub_action = "UData";
               var VOXFILEDIR = AppState.VOXFILEDIR;
                   userdata["VOXFILEDIR"] = AppState.VOXFILEDIR;
            </script>
            <gvp:send namelist="Action sub_action VOXFILEDIR" async="false" />
            <!-- Do extdata SIP info here. Check result using <receive> -->
            <script>
               var Action = "GenericData";
               var sub_action = "ExtnsEx";
               var SCRIPTSDIR = AppState.SCRIPTSDIR;
                   userdata["SCRIPTSDIR"] = AppState.SCRIPTSDIR;
            </script>
            <gvp:send namelist="Action sub_action SCRIPTSDIR" async="false" />
            <!-- Do CED SIP info here. Check result using <receive> -->
            <script>
               var Action = "GenericData";
               var sub_action = "CED";
               var GRAMMARFILEDIR = AppState.GRAMMARFILEDIR;
                   userdata["GRAMMARFILEDIR"] = AppState.GRAMMARFILEDIR;
            </script>
            <gvp:send namelist="Action sub_action GRAMMARFILEDIR" async="false" />
         </if>
      </if>
   </block>
   <transfer name="RouteRequest1Call"
             type="blind"
             destexpr="RouteRequest1Destination"
             gvp:userdata="userdata"
   />
</form>


Sample Voice XML Applications > CTI Interactions > Initiate Transfer

Bridge Transfer

This is an INVITE transfer. The outgoing leg from Media Control Platform (MCP) (to the route DN) is held at the CTI Connector until an agent is available, and then connected to the agent.

<script src=”ctic.js” />
<form id="RouteRequest1">
   <property name="inputmodes" value="dtmf" />
   <script>
      var RouteRequest1Destination = ”r;sip:9000@10.10.30.117”;
      var userdata = new Array();
   </script>
   <block>
      <if cond="AppState.g_CTICCall == 'true'" >
         <!--  CTIC Case -->
         <assign name="RouteRequest1Destination" expr="RouteRequest1Destination + ';RouteRequest=1'"/>
         <script>
            userdata["ExtnsEx_GRAMMARFILEDIR"] = AppState.GRAMMARFILEDIR;
            userdata["CED"] = AppState.VOXFILEDIR;
            userdata["Udata_SCRIPTSDIR"] = AppState.SCRIPTSDIR;
         </script>
      </if>
   </block>
   <transfer name="RouteRequest1Call"
             type="bridge"
             destexpr="RouteRequest1Destination"
             maxtime="0s"
             connecttimeout="30s"
             genesys:userdata="userdata">
   </transfer>
</form>

This translates to a SIP INVITE message from MCP to CTI Connector as (only the relevant headers are shown):

INVITE  sip:9000@10.10.30.117;RouteRequest=1 SIP/2.0
X-Genesys-CED: <some value>
X-Genesys-UData_SCRIPTSDIR: <some value>
X-Genesys-ExtnsEx_GRAMMARFILEDIR: <some value>

Error Propagation

As part of the bridge transfer, the INVITE sent from MCP to the CTI Connector is acknowledged by the CTI Connector (which establishes the SIP dialog). This is necessary in order to play treatments while waiting for an agent. When the agent does become available, the CTI Connector establishes a new SIP dialog with the agent and then joins the two SIP legs (the MCP-CTI Connector leg is joined to the CTI Connector-agent leg).

As part of the CTI Connector invite to the agent, if the agent replies with a 4xx, then that error cannot be propagated (as is) to the MCP SIP dialog (since the MCP dialog is already established). In order to preserve the VoiceXML application semantics (and allow the application to be aware of errors from the transfer), the CTI Connector sends a BYE to MCP with the sip Reason: header (per RFC 3326):

Reason: SIP ;cause=600 ;text="Busy Everywhere"

This is populated into the disconnectreason shadow variable of <transfer> and is available to the application (if there are multiple Reason: headers received in BYE, they are appended into one comma separated string).

Note: The result of the <transfer> would be far_end_disconnect. The shadow variable disconnectreason is populated only when the <transfer> result is far_end_disconnect. The following sample VoiceXML code shows the usage:

<form>
   <block>
      <prompt>
         Welcome to Genesys
      </prompt>
   </block>
   <transfer name="newcall"
             dest="sip:dialog@127.0.0.1"
             connecttimeout="60s"
             bridge="true"
             genesyslab:connectwhen="immediate"
             genesyslab:analysis="true"
   >
      <filled>
         Your call lasted <value expr="newcall$.duration"/> seconds.
         <if cond="newcall == 'far_end_disconnect'">
            The disconnect reason is <value expr="newcall$.disconnectreason"/>
         </if>
      </filled>
   </transfer>
</form>


Treatments

Sample Voice XML Applications > CTI Interactions > Treatments (Post Initiate Transfer)

Overview

After the VoiceXML application initiates the transfer to find an agent, the Universal Routing Server (URS) strategy could invoke a series of treatments:

  • PlayApplication

  • PlayAnnounce

  • PlayAnnounceAndDigits

  • PlayMusic

  • CancelTreatment

These play something back to the caller (and may gather input) while the caller is waiting for an agent. At the end of the treatment, some interaction data (CED, UData, ExtnsEx) can be passed back to the strategy.

Each treatment is a new VoiceXML dialog to the Media Control Platform (MCP) invoked NETANN style (see RFC 4240 section 4) since the original caller on the MCP is either on:

  • Hold (if a bridge transfer to route DN was issued).

  • Terminated (if a blind transfer to a route DN was issued).

At the end of the treatment, the interaction data is passed back in the BYE message body. Since all three kinds of interaction data can be passed back at the end of treatment (in BYE), specific variable naming conventions must be used to differentiate each.

The VoiceXML <exit> tag with namelist can be used to pass back the interaction data to the strategy.

<script>
   <assign name=”CED” expr=”1”/>
   <assign name=”UData_param1” expr=”3”/>
   <assign name=”UData_param2” expr=”4”/>
   <assign name=”ExtnsEx_param1” expr=”5”/>
   <assign name=”ExtnsEx_param2” expr=”6”/>
</script>
<exit namelist=”CED UData_param1 Udata_param2 ExtnsEx_param1 ExtnsEx_param2”/>

The corresponding BYE message body:

CED=1&Udata_param1=3&Udata_param2=4&ExtnsEx_param1=5&ExtnsEx_param2=6

All UData variables must be prefixed with UData_ and all ExtnsEx variables must be prefixed with ExtnsEx_. Since CED is the only variable, there is no prefix necessary and the variable must be named CED.


Sample Voice XML Applications > CTI Interactions > Treatments (Post Initiate Transfer)

PlayApplication

PlayApplication is the most generic of the four treatments. The CTI Connector invokes this treatment using the
NETANN style dialog invocation to the Media Control Platform (MCP). The resulting VoiceXML dialog is free to
do anything with the caller. At the end of the treatment, three kinds of interaction data can be passed back
to the strategy:

  • CED

  • UData

  • ExtnsEx

The ScriptID parameter (from the strategy) is passed to the VoiceXML application as a RequestURI parameter. The VoiceXML application must understand the semantics of the ScriptID value in order to request the correct application file.

There are two ways the PlayApplication treatment can be invoked from the strategy:

  • With APP_URI specified in the strategy.

  • Without APP_URI specified in the strategy.

With APP_URI Specified in the Strategy

In this scenario, the strategy can set the APP_URI to point to a VoiceXML application that will handle the PlayApplication treatment. Then, the CTI Connector will pass the URL in the NETANN invite to the MCP:

INVITE sip:dialog@172.24.129.86:5080;ScriptID=1;LANGUAGE=English(US);
       voicexml=http://172.24.129.55:8080/playapplication/src-gen/Main.vxml SIP/2.0

Without APP_URI Specified in the Strategy

In this scenario, the CTI Connector sends the NETANN invite with a specific keyword SCRIPTURL in the
voicexml parameter value:

INVITE sip:dialog@172.24.129.86:5080;ScriptID=1;LANGUAGE=English(US);
       voicexml=SCRIPTURL SIP/2.0

As this INVITE passes through the Resource Manager (RM), on the way to MCP, the RM reads the script-url parameter from the gvp.service-prerequisites section of IVR Profile, and updates the SCRIPTURL with this value. If the script-url parameter is not configured, then the RM reads the initial-page-url value from the IVR Profile, and updates the SCRIPTURL with this value.

At the end of treatment of the VoiceXML application's execution, the interaction data (CED, UData, ExtnsEx) can be passed back to the strategy using <exit> namelist, as follows:

<script>
   <assign name=”CED” expr=”1”/>
   <assign name=”UData_param1” expr=”3”/>
   <assign name=”UData_param2” expr=”4”/>
   <assign name=”ExtnsEx_param1” expr=”5”/>
   <assign name=”ExtnsEx_param2” expr=”6”/>
</script>
<exit namelist=”CED UData_param1 Udata_param2 ExtnsEx_param1 ExtnsEx_param2”/>


Sample Voice XML Applications > CTI Interactions > Treatments (Post Initiate Transfer)

PlayAnnounce

The PlayAnnounce treatment is managed by the Media Control Platform (MCP). The VoiceXML application does not do anything. Interaction data is not passed back to the strategy at the end of treatment. The following parameters, from the strategy, are passed as RequestURI parameters to the VoiceXML application:

  • MSGID

  • MSGTXT

Note: The CTI Connector sets the ScriptID to PlayAnnounce.

The MCP installation ships with a default VoiceXML application that manages PlayAnnounce treatments. They are installed in the C:\Program Files\GCTI\gvp\VP Media Control Platform 8.1\MCP_App2\treatments\PlayAnn.vxml) directory. The code is as follows:

<?xml version="1.0"?>

<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">

  <form>

    <block>

       <if cond="'text' in session.connection.protocol.sip.requesturi">

         <prompt>

           <value expr="session.connection.protocol.sip.requesturi['text']"/>

         </prompt>

       <elseif cond="'msgtxt' in session.connection.protocol.sip.requesturi"/>

         <prompt>

           <value expr="session.connection.protocol.sip.requesturi['msgtxt']"/>

         </prompt>

        </if>

    </block>

  </form>

</vxml>

The CTI Connector invokes a NETANN style dialog to the MCP for the PlayAnnounce treatment:

INVITE sip:dialog@172.24.129.86:5080;LANGUAGE=English(US);MSGID=2;
MSGTXT=In%20the%20process%20of%20playing%app;ScriptID=PlayAnnounce;
voicexml=http://localhost/treatments/PlayAnn.xml SIP/2.0

The CTI Connector includes a PlayAnnouncePath parameter that manages the location of the PlayAnnounce application. This parameter defaults to:
PlayAnnouncePath=http://localhost/treatments/PlayAnn.xml.

If needed, this parameter can be changed to point to another VoiceXML application to handle the PlayAnnounce treatment. If this parameter is left blank, then the CTI Connector set SCRIPTURL
in the NETANN INVITE (as in the PlayApplication), and the Resource Manager (RM) will substitute it based on the IVRProfile.


Sample Voice XML Applications > CTI Interactions > Treatments (Post Initiate Transfer)

PlayAnnounceAndDigits

The PlayAnnounceAndDigits treatment is managed by the Media Control Platform (MCP). The VoiceXML application does not do anything. The CED Interaction data is passed back in the <exit> namelist attribute. This translates to the BYE message body at the end of treatment.

The following parameters, from the strategy, are passed to the VoiceXML application as RequestURI parameters:

  • MSGID

  • MSGTXT

  • MAX_DIGITS

Note: In addition, the CTI Connector sets the ScriptID parameter to PlayAnnounceAndDigits.

The MCP installation ships with a default VoiceXML application to manage the PlayAnnounceAndDigits treatments. This is installed in the following web accessible directory C:\Program Files\GCTI\gvp\VP Media Control Platform 8.1\MCP_App2\treatments\PlayAnnDigits.vxml. The code is as follows:

<?xml version="1.0"?>

<vxml version="2.1" xmlns="http://www.w3.org/2001/vxml">

  <property name="inputmodes" value="dtmf"/>

   <form>

         <catch event=".">

     <exit/>

         </catch>

     <var name="strMaxLen" expr="''"/>

     <var name="strPlayMsg" expr="''"/>

      <block>

         <if cond="session.connection.protocol.sip.requesturi['max_digits'] > 0">

            <assign name="strMaxLen" expr="'?maxlength=' + session.connection.protocol.sip.requesturi['max_digits']"/>

         </if>

         <if cond="'text' in session.connection.protocol.sip.requesturi">

             <assign name="strPlayMsg" expr="session.connection.protocol.sip.requesturi['text']"/>

         <elseif cond="'msgtxt' in session.connection.protocol.sip.requesturi"/>

             <assign name="strPlayMsg" expr="session.connection.protocol.sip.requesturi['msgtxt']"/>

         </if>

      </block>

    <field name="CED">

      <catch event="noinput nomatch">

           <reprompt/>

      </catch>

      <catch event="noinput nomatch" count="3">

         <throw event="exit"/>

      </catch>

      <prompt>

       <value expr="strPlayMsg"/>

      </prompt>

         <grammar srcexpr="'builtin:dtmf/digits'+strMaxLen"/>

      <filled>

        <exit namelist="CED"/>

      </filled>

     </field>

   </form>

</vxml>

CTI Connector invokes a NETANN style dialog to the MCP for the PlayAnnounce treatment:

INVITE
sip:dialog@172.24.129.86:5080;LANGUAGE=English(US);
MAX_DIGITS=1;MSGID=2;MSGTXT=In%20the%20process%20of%20playing%app;
ScriptID=PlayAnnounceAndDigits;
voicexml=http://localhost/treatments/PlayAnnDigits.xml SIP/2.0

The CTI Connector supports a parameter that controls the location of the PlayAnnounce application.
This parameter defaults to:

PlayAnnounceAndDigitPath=http://localhost/treatments/PlayAnnDigits.xml

This parameter can be changed to another VoiceXML application that will manage the PlayAnnounceAndDigits treatment. If this parameter is blank, then the CTI Connector assigns the SCRIPTURL (as in the PlayApplication above) in the NETANN INVITE, and the Resource Manager (RM) substitutes it based on the IVRProfile.


Sample Voice XML Applications > CTI Interactions > Treatments (Post Initiate Transfer)

PlayMusic

The PlayMusic treatment is managed by the Media Control Platform (MCP). The VoiceXML application does not
require do anything. This treatment is invoked by the CTI Connector as an ANNC style dialog to the MCP.

The following parameters from the strategy are passed to the VoiceXML application in the RequestURI DURATION parameter:

INVITE
sip:annc@172.24.129.86:5080;DURATION=10;
play=http://172.24.129.55:8080/Test/Resources/Prompts/m.vox SIP/2.0

If the audio file size is greater than (>) the DURATION, then the playback is restricted to the DURATION in seconds. Otherwise, the DURATION is ignored. No interaction data is passed back at the end of PlayMusic treatment.


Sample Voice XML Applications > CTI Interactions > Treatments (Post Initiate Transfer)

CancelTreatment

Any ongoing treatment can be cancelled by the CTI Connector by sending a BYE to the Media Control Platform (MCP) to terminate the dialog. This will appear as a regular caller hangup to the VoiceXML application.

If the treatment is not yet started, but is in the process of being initiated (the CTI Connector has sent the NETANN invite to the MCP, but has not received the 200 OK back from MCP, it can be cancelled by the CTI Connector by sending a sip CANCEL message to MCP.


Transfer Complete

Sample Voice XML Applications > CTI Interactions > Transfer Complete

Overview

The following topics detail Transfer Complete:

  • Regular (no action on MCP)

  • Reroute after first transfer (no action on MCP)


Sample Voice XML Applications > CTI Interactions > Transfer Complete

Regular (No Action on MCP)

After the treatments are complete and an agent is available, the CTI Connector transfers the caller to the agent.

Note: No action is required on the VoiceXML application side. This is true for both blind and bridge transfers.


Reroute after first transfer (only Bridge and Network modes, no action on MCP)

Sample Voice XML Applications > CTI Interactions > Transfer Complete

Reroute after First Transfer (No Action on MCP)

After the caller is transferred to the agent, the agent may decide to transfer the call to another agent.
This is called ReRoute. It is managed by Genesys Voice Platform (GVP).

Note: No action is required on the VoiceXML application side.


Overview_Functions

Sample Voice XML Applications > Functions

Overview

The following functions are called from the sample VoiceXML applications in the CTI Interactions section:

  • getUserDataArray

  • utilGetReceiveDataValue


Sample Voice XML Applications > Functions

getUserDataArray

The following code is the getUserDataArray function:

function getUserDataArray(dataMessage)
{
   if(dataMessage == undefined)
      return undefined;
      var resultArray = new Array();
      var message = dataMessage.split("&");
      var startIndex = 0;
      var endIndex = 0;
      var keyName;
      var keyValue;
      var arrayIndex;
      for (arrayIndex in message)
      {
         startIndex = message[arrayIndex].indexOf ("=", startIndex) + 1;
         endIndex = message[arrayIndex].length;
         keyName = message[arrayIndex].substring (0, startIndex-1);
         keyValue = message[arrayIndex].substring (startIndex, endIndex);
         if(keyValue != undefined)
         {
            resultArray[keyName] = decodeURI("" + keyValue);
         }
         startIndex = endIndex = 0;
      }
   return resultArray;
}


Sample Voice XML Applications > Functions

utilGetReceiveDataValue

The following code is the utilGetReceivedDataValue function:

function utilGetReceiveDataValue(strKeyName, arrReceiveData)
{
   var strOut = "";
   if (arrReceiveData != undefined && strKeyName != undefined)
   {
      strOut = decodeURI(arrReceiveData[decodeURI(strKeyName)]);
      if (strKeyName == "Result")
      {
         strOut = strOut.toUpperCase();
      }
   }
   else
   {
      strOut = undefined;
   }
   return strOut;
}


About Genesys

Genesys is the world’s leading provider of customer service and contact center software—with more than 4,000 customers in 80 countries. Drawing on its more than 20 years of customer service innovation and experience, Genesys is uniquely positioned to help companies bring their people, insights and customer channels together to effectively drive today’s customer conversation. Genesys software directs more than 100 million interactions every day, maximizing the value of customer engagement and differentiating the experience by driving personalization and multi-channel customer service – and extending customer service across the enterprise to optimize processes and the performance of customer-facing employees. For more information, go to www.genesyslab.com.

Product documentation is provided on the Technical Support website, the Genesys Documentation wiki, and the Documentation Library DVD or the Developer Documentation CD that is shipped on request with your software.

Contacting Genesys

Genesys Telecommunications Laboratories, Inc.
www.genesyslab.com

Technical Support from VARs

If you have purchased this software from a value-added reseller (VAR), please contact the VAR for technical support.

Technical Support from Genesys

If you have purchased support directly from Genesys, please contact Genesys Technical Support.

Before contacting technical support, please refer to the Genesys Care Program Guide for complete contact information and procedures.

Ordering Information

For complete information on ordering Genesys products, please see the Genesys Licensing Guide.


Disclaimers

Although reasonable effort is made to ensure that the information in this document is complete and accurate at the time of release, Genesys Telecommunications Laboratories, Inc., cannot assume responsibility for any existing errors. Changes and/or corrections to the information contained in this document may be incorporated in future versions.

Your Responsibility for Your System Security

You are responsible for the security of your system. Product administration to prevent unauthorized use is your responsibility. Your system administrator should read all documents provided with this product to fully understand the features available that reduce your risk of incurring charges for unlicensed use of Genesys products.

Trademarks

Genesys and the Genesys logo are registered trademarks of Genesys Telecommunications Laboratories, Inc. All other company names and logos may be trademarks or registered trademarks of their respective holders. © 2012 Genesys Telecommunications Laboratories, Inc. All rights reserved.


Printing This Help File

You can print a single topic (page) or all the topics (pages) within a single book. You cannot, however, print the entire Help file at once.

From the Table of Contents, select a topic or book and then do the following:

  1. Select the Print button.

  2. In the Print Topics dialog box, select either:

    • Print the selected topic

    • Print the selected heading and all subtopics

  3. Select OK.