IVR Deconstructed

Plum Voice is now accepting requests for beta testers of our new web-based graphical IVR development toolkit called SynApps.  Those with experience developing applications in VoiceXML or IVR GUIs would be preferable.  If you are interested in becoming a beta tester for SynApps, please send an e-mail to synappsbeta@plumgroup.com

Another useful feature that root documents offer IVR developers is the ability to transition from a leaf document back to the root document. This ability allows you to send information back to your root document that has been updated through your leaf documents.

The following IVR example demonstrates how you can do this:

root.vxml (root document):

<?xml version=”1.0″?>
<vxml version=”2.0″>
<var name=”foo”/>
<form>
<block>
<prompt bargein=”false”>
The value leaf is set to <value expr=”leaf”/>.
</prompt>
</block>
</form>
</vxml>

Page1.vxml (leaf document):

<?xml version=”1.0″?>
<vxml version=”2.0″ application=”root.vxml”>
<form>
<block>
<assign name=”foo” expr=”‘bar’”/>
<goto next=”Page2.vxml” maxage=”0″ maxstale=”0″/>
</block>
</form>
</vxml>

Page2.vxml (leaf document):

<?xml version=”1.0″?>
<vxml version=”2.0″ application=”root.vxml”>
<var name=”leaf”/>
<form>
<block>
<assign name=”leaf” expr=”‘rab’”/>
<prompt bargein=”false”>
The value foo is set to <value expr=”foo”/>
</prompt>
<goto next=”root.vxml” maxage=”0″ maxstale=”0″/>
</block>
</form>
</vxml>

From this IVR example, when the application, Page1.vxml, is started, it accesses the variable, “foo”, from the root document, root.vxml, and assigns it the value of string, “bar”. Page1.vxml then transitions to Page2.vxml, which creates a new variable, “leaf”, and assigns it the value of string, “rab”. Page2.vxml then returns the prompt, “The value of foo is set to bar.” After the prompt, Page2.vxml transitions to the root document, root.vxml, which references the variable, “leaf”, from Page2.vxml and returns the prompt, “The value leaf is set to rab.” Thus, it is possible for root documents to reference variables from leaf documents as long as the leaf documents reference the root document.

This ends our discussion on the benefits of using root documents within your VoiceXML IVR code. One thing to keep in mind is that you must reference the root document in each of your leaf documents so that your leaf documents can continue to reference the same content. So, if your root document is entitled rootdocument.vxml, then you must reference the name of this root document in the following way for each of your leaf documents:

<vxml version=”2.0″ application=”rootdocument.vxml”>

If your IVR application reaches a leaf document that no longer references the root document, then the root context becomes destroyed. To clarify this point, think of an example where you have initially declared a variable within your root document and when this variable gets updated in a leaf document, the value is preserved through referencing the root document. If an IVR developer, however, forgets to  reference the root document within a leaf document, then the values that get preserved for the variables throughout the leaf document become lost at that point in the application.

Have you ever gotten tired of writing the same error handler into your IVR code to ensure that callers listen to the same messages for when they enter no input or when they enter an input that doesn’t match your VoiceXML grammar? This not only makes your code lengthy, but it’s just not needed.

If you know that you’re going to be using the same error handler in parts of your IVR application where you’re not explicitly stating them, then you can set up your error handler to be a global catch handler in your root document.

Also, you can use your root document for setting up global properties such as “interdigittimeout” within your IVR code. This is helpful for when you know that you want users to have the same amount of time when they’re entering digits on their phone keypad.

The following IVR example demonstrates this point:

Root.vxml:

<?xml version=”1.0″?>
<vxml version=”2.0″>
<var name=”username”/>
<var name=”age”/>

<property name=”interdigittimeout” value=”3s”/>

<catch event=”noinput”>
Please enter an input.
</catch>
<catch event=”nomatch”>
Your input does not make sense.
</catch>
</vxml>

Page1.vxml:

<?xml version=”1.0″?>
<vxml version=”2.0″ application=”Root.vxml”>
<form>
<block>
<assign name=”username” expr=”‘Big Dog’”/>
</block>
<field name=”userage” type=”digits”>
<prompt>
<value expr=”username”/>,
please enter the digits of your age.
</prompt>
<filled>
You entered <value expr=”userage”/>.
<assign name=”age” expr=”userage”/>
<goto next=”Page2.vxml”/>
</filled>
</field>
</form>
</vxml>

Page2.vxml:

<?xml version=”1.0″?>
<vxml version=”2.0″ application=”Root.vxml”>
<form>
<block>
<prompt bargein=”false”>
Your name is <value expr=”username”/>.
Your age is <value expr=”age”/>.
</prompt>
</block>
</form>
</vxml>

From this example, the root document, Root.vxml, sets a global default property for “interdigittimeout” to be 3 seconds long. This means that if there are no properties set locally within your IVR application for “interdigittimeout”, the “interdigittimeout” for the user to input digits would be 3 seconds. The root document also sets up global catch handlers for “noinput” and “nomatch” events for your application. This means that if there are no error handlers set for “noinput” and “nomatch” locally, the application would use the “noinput” and “nomatch” catch handlers set in your root document. 2 global variables, “username” and “age”, are set up for this IVR example as well.

When the IVR application starts at Page1.vxml, “username” is assigned the value of string “Big Dog”. The user is then prompted for an age to be inputted. Since there is no property set for “interdigittimeout” within Page1.vxml, the IVR application uses the “interdigittimeout” property from the root document. This means that the user has 3 seconds between the input of each digit before the application begins to process the digits that were entered. Also, if the user does not enter any digits, the application uses the “noinput” catch handler from the root document since there is no error handler set for “noinput” within Page1.vxml. Let’s assume you enter “12″ for your age. Finally, the IVR application transitions to Page2.vxml, which returns a prompt of “Your name is Big Dog. Your age is 12.” Thus, if you have multiple VoiceXML scripts linked together, you can use a root document to store global variables, properties, or catch handlers that would be used by these VoiceXML scripts.

There have been times on the forum when I have seen developers create a long VoiceXML script with mounds and mounds of IVR code. Scrolling through all this IVR code sure can make it tough on developers for debugging. So, as a general rule of thumb, you should break up your VoiceXML pages to make it easier to debug your code and for better organization.

But how do I maintain variables between the VoiceXML pages?

Ah, that brings us to the point of this blog post. We can use root documents to declare all the variables that we are going to use within our VoiceXML scripts.

But how do these VoiceXML scripts know about this root document?

Simple, by including it in the “application” attribute of the <vxml> tag. Here’s a short example to demonstrate:

root.vxml:

<?xml version=”1.0″?>
<vxml version=”2.0″>
<var name=”foo”/>
</vxml>

page1.vxml:

<?xml version=”1.0″?>
<vxml version=”2.0″ application=”root.vxml”>
<form>
<block>
<assign name=”foo” expr=”‘bar’”/>
<goto next=”page2.vxml”/>
</block>
</form>
</vxml>

page2.vxml:

<?xml version=”1.0″?>
<vxml version=”2.0″ application=”root.vxml”>
<form>
<block>
<prompt bargein=”false”>
The value foo is set to <value expr=”foo”/>
</prompt>
</block>
</form>
</vxml>

From this example, page1.vxml accesses the variable “foo” from the root document root.vxml, assigns it the value, “bar”, and transitions to page2.vxml. Once inside of page2.vxml, the root document is referenced again, which allows page2.vxml to use the variable “foo”. Since the root document preserves the assignment of the variable from page1.vxml, page2.vxml returns a prompt of “The value foo is set to bar.”

Even though this is a simple example, you can see the benefits of using a root document for declaring the variables that you are going to use within your VoiceXML code. Imagine if you had three separate VoiceXML pages; one page for getting input data from the user, another page for verifying the input data from the user, and a final page for processing the data. Sticking this code all into one VoiceXML script would be sloppy and unorganized. But instead, we can use a root document to declare a variable that would hold this input data and use it through each of our VoiceXML pages.

Stay tuned next week for Parts 2 and 3 of The Benefits of Using Root Documents Within Your IVR Code.

A common issue that crops up on the forum from time to time is leaving voicemails on an answering machine when an outbound IVR call is not picked up by a human. Many times, developers would write IVR test code to act on a callee type of “answeringmachine” and wonder why a voicemail was not left on their cell phone.

So, we typically suggest to developers to use the following IVR code:

<?php
header(”Content-type: text/xml”);
echo(”<?xml version=\”1.0\”?>\n”);
$calleetype = $_POST['callee_type'];
?>
<vxml version=”2.0″>
<form id=”mainmenu”>
<var name=”callee_type” expr=”‘<?= $calleetype ?>’”/>

<record cond=”callee_type==’answeringmachine’” finalsilence=”2000ms”/>
<block>
<prompt>
Hello! This is a reminder to take your medicine today.
</prompt>
</block>

</form>
</vxml>

From this IVR code, if the callee is an answering machine, the VoiceXML application initially goes to the <record> tag to account for the answering message that gets played at the beginning of a voicemail. Once that message gets played, the VoiceXML application then plays the prompt, “Hello! This is a reminder to take your medicine today”, which is the message that gets left on the voicemail.

However, one thing that IVR developers need to keep in mind is that callee type detection for outbound is 94% accurate. This means that every once in a while, the outbound system will mistake an answering machine for a human and vice versa. The consequence of this behavior is that a voicemail message may get cut off at the beginning or a message may not be left at all.

Thus, for applications that require a voicemail message be left on an answering machine 100% of the time, we suggest that the IVR developer repeat the message numerous times. For example:

<?php
header(”Content-type: text/xml”);
echo(”<?xml version=\”1.0\”?>\n”);
?>
<vxml version=”2.0″>
<property name=”inputmodes” value=”dtmf”/>

<form id=”message”>
<field name=”leavemsg”>
<grammar type=”application/x-jsgf” mode=”dtmf”>(0|1|2|3|4|5|6|7|8|9|”#”|”*”)</grammar>

<prompt>
Hello! This is an application from your hospital. Please press 1 to continue. Please remember to call the phone number listed in your e-mail to reserve your appointment. Hello! This is an application from your hospital. Please press 1 to continue. Please remember to call the phone number listed in your e-mail to reserve your appointment. Hello! This is an application from your hospital. Please press 1 to continue. Please remember to call the phone number listed in your e-mail to reserve your appointment. Hello! This is an application from your hospital. Please press 1 to continue. Please remember to call the phone number listed in your e-mail to reserve your appointment. Hello! This is an application from your hospital. Please press 1 to continue. Please remember to call the phone number listed in your e-mail to reserve your appointment.
</prompt>

<filled>
<prompt>
Here is a different message that should be played to a human.
</prompt>
<goto next=”#confirmtransfer”/>
</filled>

</field>
</form>

<form id=”confirmtransfer”>
<field name=”leavemsg”>
<grammar type=”application/x-jsgf” mode=”dtmf”>1</grammar>

<prompt>
Would you like to be tranferred? Press 1 for yes.
</prompt>

<filled>
<prompt>
Okay, please hold while we transfer you.
</prompt>
<goto next=”#maketransfer”/>
</filled>
</field>
</form>

<form id=”maketransfer”>
<transfer dest=”tel:+1XXXXXXXXXX”/>
</form>

</vxml>

From this IVR example, the outbound IVR call will leave a voicemail that keeps on repeating the prompt, “Hello! This is an application from your hospital. Please press 1 to continue. Please remember to call the phone number listed in your e-mail to reserve your appointment.” if no one picks up and enters 1 on their phone keypad.

If the IVR outbound call is picked up by a human and the human presses 1 on their phone keypad, then a different message will be played and the human will be prompted to enter 1 on their phone keypad if they want to be transferred.