Tutorial: JavaScript and VoiceXML

This tutorial describes how to use JavaScript in your VoiceXML application to perform client-side processing. When we're done, you'll have a basic understanding of how to include JavaScript functions in your applications and how to use those functions to enhance your VoiceXML.

This tutorial builds on lessons learned in Tutorial 7. If you haven't completed that tutorial, you'll need to go through it first.

Note: ECMAScript is a standard scripting language based on JavaScript 1.1. The VoiceXML specification makes several references to ECMAScript. JavaScript is currently used as the ECMAScript implementation on the Voxeo network.

Step 1: Creating our initial VoiceXML document



<?xml version="1.0" encoding="UTF-8"?>

<vxml version = "2.1" >



 <meta name="maintainer" content="YOUREMAILADDRESS@HERE.com"/>



  <form id="Hello World">

    <block>

     <prompt>

      Hello there. The caller i d number is <value expr="session.callerid"/>

      The called i d of this application is <value expr="session.calledid"/>

     <prompt>

    </block>

  </form>

</vxml>

You should be familiar with this code from our earlier tutorial on Caller/CalledID. It simply grabs the session variables for these values, and speaks these values back to the caller. Hey, wait a minute...........when I run this script it tells me my caller ID is "eight billion, three hunderd fourteen million ..." What's going on? That's not my phone number!

Ohhhh, wait a second, I know what's going on. It is reading my phone number like a number, not a digit-by-digit value like we would be accustomed to hearing. We covered how to use the <say-as> elements so that our phone number was spoken as a set of digits, but just to illustrate how JavaScript works in your VoiceXML application, we will tackle this problem from another direction.

Step 2: Creating the JavaScript function

Let's try a little trick so that our phone number is spoken as a stream of digits instead of as a number. The trick is to add a space between each digit in the phone number. That way each digit is spoken separately and not as one large number. But... how are we going to do that with VoiceXML?

We are going to use VoiceXML's <script> element to write a JavaScript function. This function will add the spaces so that we can hear our phone number the way it should be, instead of "eight billion...".

As mentioned in our Introduction to this tutorial, the <script> element allows you to include scripting language code in your application. In this case, the scripting language is JavaScript. Code contained in the <script> element is executed on the client side, so we don't have to go to the back-end server for such a simple task. Each <script> element follows the same scoping rules as other elements, meaning, the <script> element is executed in the scope of the containing element.



<script>

  <![CDATA[

    function sayasDigits(number)

    {

      var digitNumber = number.charAt(0);

      for(var i = 1; i < number.length; i++)

      {

        digitNumber += ' ' + number.charAt(i);

      }

      return digitNumber;

    }

   ]]>

</script>

As you can see, the JavaScript part of the code is very straight forward. But what is that CDATA thing at the top of the script? We use the CDATA directive so that our script can contain characters that are normally reserved for XML syntax usage. XML uses certain characters, such as the 'less-than' sign, "<", as part of the syntax, and not as part of the content. Since our script uses one of these characters we need to use this CDATA directive so that these reserved characters are interpreted as content, and not as part of the syntax....otherwise, would likely see a nasty XML parsing error when viewing the code in a web browser.

Step 3: Using the JavaScript function in VoiceXML elements

Okay, now that we have defined this nifty little JavaScript function, how do we use it? You may have noticed that several VoiceXML elements have an 'expr' attribute. Heck, you may even have used the 'expr' attribute before. Well, the 'expr' attribute can contain any valid JavaScript expression. So, we can use our function in the 'expr' attribute of various VoiceXML elements. Let's see how its done.



<prompt>

  Hello there. The caller i d number is: 

  <value expr="sayasDigits(session.callerid)"/>

</prompt>

Here, we are calling the function 'sayasDigits' and passing in the caller ID value. The function adds the spaces between each of digit of the number and returns to us the newly formatted value. As the text-tospeech engine will read off any numeric value that is space-delimited as a digit, we are in the clear. The value of the 'expr' attribute, in this case the new 'number' is then spoken to the caller.

Step 4: The complete application

We have all the necessary pieces now, so lets assemble them into a complete VoiceXML application.



<?xml version="1.0" encoding="UTF-8"?>

<vxml version = "2.1">



 <meta name="maintainer" content="YOUREMAILADDRESS@HERE.com"/>

  <form id="HelloWorld">

    <block>

      <script>

        <![CDATA[

          function sayasDigits(number)

          {

            var digitNumber = number.charAt(0);

            for(var i = 1; i < number.length; i++)

            {

              digitNumber += ' ' + number.charAt(i);

            }

            return digitNumber;

          }

         ]]>

      </script>

     <prompt>

       Hello there. The caller i d value is: <value expr="sayasDigits(session.callerid)"/>

       The called i d of this application is: <value expr="sayasDigits(session.calledid)"/>

     </prompt>

    </block>

  </form>

</vxml>

Step 5: upload, and try it out

All that remains is to upload the new VoiceXML application, provision a number, and call the associated number to hear the results.

Download the Code!

Motorola source code

What was just covered:

Learned how to define JavaScript functions using the <script> element
Learned basic script-scoping rules
Learned how to use JavaScript functions to perform client side processing
Learned that a Voxeo tutorial without any gags, goofy pictures, or witty 'bon mots' can be quite boring

ANNOTATIONS: EXISTING POSTS

alvaro

7/19/2006 8:01 AM (EDT)

Hi! I'm Alvaro and I would like to know how to create a text file(.txt) in an VoiceXML application to store data. May someone help me? If it's possible I would prefer a practical example with a little explanation. I am novate. Thanks.

VoxeoDenise

7/19/2006 2:24 PM (EDT)

Hey Alvaro,

In order to write to a text file using VoiceXML, you will need to implement some sort of Server Side Language such as PHP, ASP, JSP, or Cold Fusion.

Hopefully this will help to get you started. Please feel free to contact us if you have any further questions.

Regards,
Denise Rodriguez
Voxeo Extreme Support

alvaro

7/20/2006 6:15 AM (EDT)

Thanks for your answer.
Now a have another doubt. I want to store data in this URL: http://localhost/....../reserva.php?info1=..&info2=..&info3=.. and I have tried with the submit element but it doesn`t work and I would like to know if there is another element or another way using submit to do this. With submit I have use the "next" attribute and/or the "namelist" attribute.

Don.Lawson

7/20/2006 10:47 AM (EDT)

Alvaro,
The namelist attribute specifies a space-separated list of variables to send to the URI indicated by the next or expr attributes. Note that if the namelist attribute is left unspecified, then all input-item variables will be submitted to the destination URI.

So for your case

<submit next="http://localhost/....../reserva.php" namelist="info1 info2 info3" />

And of course if you leave the namelist attribute out of it, all of the variables will be past along. You can also specify a method attribute to make it a POST request. It defaults to GET so if your php script is expecting POST you will need to specify this. Also in your php script make sure you are using the $_REQUEST global variable instead of $_POST as it will eliminate any error related to this.

Don Lawson
Voxeo Support

anil.s

5/9/2008 8:39 AM (EDT)

Hi,
I am Anil.. I am not able to figure it out why i am getting the following error. Please post me in which scenarios generally the voice xml end up with these kind of errors.

"Cannot read property "termchar" from undefined (JSI#1)"

Thanks,
Anil

voxeojeremyr

5/9/2008 1:28 PM (EDT)

Hi Anil,

I am not familiar with that error. I think that you are trying to set the termchar property and that there is some kind error when trying to set the value.

To help us troubleshoot this more effectively, could you open an account ticket and attach your code and a debugger log?

Thanks,
Jeremy Richmond
Voxeo Support

DTMF Recognition

| TOC

Subgrammars