CallXML 2.0 Development Guide Home  |  Frameset Home
  DTMF Entry and Recognition  |  TOC  |  Introduction to Document Navigation  
This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Tutorial: Hello World with Termdigits

This Lesson is based on the things you accomplished in Lesson 1. If you haven't yet done this Lesson, you'll need to go through it first so that you aren't left in the dust with the high-falutin' concepts that we discuss here.

In this tutorial, we will:


Step 1: extend hello world to respond to keys

In the previous tutorial, we ended up with a callxml file that looked like this:


<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="2.0">
  <playaudio value="helloworld.wav"/>
</callxml>


In callxml, things like <playaudio> are called action elements. These elements perform "actions", such as playing audio, recording audio, and hanging up. Callxml has another category of elements known as event elements. These elements describe what to do when various events occur during a call, such as when the user presses touch-tone keys on their telephone. Here we will add a callxml event element to the hello world callxml we created in the last tutorial. This event element will react to the "*" key.


<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="2.0">
  <playaudio value="helloworld.wav"/>
  <ontermdigit value="*">

  </ontermdigit>
</callxml>


Now we need to fill in the event element with instructions on what to do when the '*' key is pressed. In this example, we will use another action element -- the <text> element -- to read text to the caller, telling them that they "pressed the star key."


<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="2.0">
  <playaudio value="helloworld.wav"/>
  <ontermdigit value="*">
    <text>you pressed the star key.</text>
  </ontermdigit>
</callxml>


Next we'll add a second event element for the '#' key, which will tell the caller they "pressed the pound key" when they do, in fact, press that key.


<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="2.0">
  <playaudio value="helloworld.wav"/>
  <ontermdigit value="*">
    <text>you pressed the star key.</text>
  </ontermdigit>
  <ontermdigit value="#">
    <text>you pressed the pound key.</text>
  </ontermdigit>
</callxml>



Step 2: the termdigits attribute

Pretty easy so far... but we need to do one more thing. By default, callxml will not interrupt actions such as <playaudio> when keys are pressed. To allow an action to be interrupted, or terminated, you must add a termdigits attribute to the action. Termdigits specifies a list of digits which can terminate the action. In this tutorial, we'll add termdigits="*#" to playaudio, as shown below:


<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="2.0">
  <playaudio value="helloworld.wav"
            termdigits="*#"/>
<wait value="4s" termdigits="#*"/>
  <ontermdigit value="*">
    <text>you pressed the star key.</text>
  </ontermdigit>
  <ontermdigit value="#">
    <text>you pressed the pound key.</text>
  </ontermdigit>

  <onerror>
  <sendemail from="MyApp@here.com"
    to="YourEmail@there.net" type="debug">
    We caught an error in our application.  Details follow...
  </sendemail>
  </onerror>

</callxml>


You'll notice that we also added a new element into the mix, the <wait> tag. We need this to be placed at the end of our <playaudio>, since our sound file is so short, otherwise, the caller's DTMF ijnput may not have time to be recognized. You'll probably also notice that this tag has the same termdigits attribute as in our <playaudio> element. This is required as well, since if a caller enters DTMF input while in the <wait>, then we need to be able to trap and handle the event.

We also tossed another curve ball at you, as well. You'll note the <onerror/sendemail> tags at the very bottom of the code. This is not an accident; since CallXML does not have a Form Interpretation Algorithm, any and all event handlers should reside at the very bottom of your CallXML documents in order to execute. The cool thing about this event handler, coupled with the <sendemail> element, is this: Whenever the application takes a nose-dive, be it from a fetch error, or a coding typo, the event will be caught, and an email sent to the email address that you specify. When we set the type attribute to 'debug' the resulting email will also contain information about the application failure that you can use to correct the problem. If the problem in question still eludes you, you can simply forward the debug email to the Voxeo Support team, who can use this information to help you fix your application.


Step 3: save, upload, and try it out

Your updated hello world callxml file is now done. Go ahead and save it as "helloworld.xml", and upload it to the same web server and directory you uploaded to in the previous tutorial. Call the number you received in the previous example, and try pressing '*' or '#'. You should here a message saying which key you've pressed.

  CallXML 2.0 source code.




  ANNOTATIONS: EXISTING POSTS
0 posts - click the button below to add a note to this page

 login
  DTMF Entry and Recognition  |  TOC  |  Introduction to Document Navigation  
© 2011 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site