CallXML 2.0 Development Guide

| TOC

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: Answering machine Hello world

This tutorial is based on the things you accomplished in Lessons 1, 2, and 3. If you haven't yet done those lessons, you'll need to go through them first.

In this Lesson, we will:

learn how to record an audio file with the record audio action element
save that audio file as an email attachment
upload the new hello world app and try it out

Step 1: creating our initial callxml structure

From our previous Lessons, we now recognize the following structure as a normal starting point:



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

<callxml version="2.0">



  <block>

  </block>



</callxml>

Step 2: our first look at recordaudio

To have a virtual answering machine, we clearly need the ability to save sound that is transmitted over the telephone. Recordaudio is very similar to playaudio, which we learned how to use in the very first tutorial. Except now we are going to save the audio.

Notice that recordaudio has several new attributes that we did not see before with playaudio:



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

<callxml version="2.0">



  <block>

    <recordaudio format="audio/wav"

                                  value="mailto:my-email@my-email-server.com"

                                  termdigits="#"

                                  maxtime="60s"

                                  maxsilence="10s"

                                  beep="true"/>



  </block>



</callxml>

The first difference is in the attribute 'format'. Like the playaudio tags we have been using, we want to record the file as a .wav file. As for the value attribute (i.e., the destination), we are using a standard HTML 'mailto:' address. As long as the email address points to a functional email account, a message will be sent as an attachment. The beep attribute will play a cute tone to let the caller know when to start speaking.

But what are these other two attributes called maxtime and maxsilence all about? Remember how we learned that termdigits generated a trappable event in Lesson 2? Well, maxtime and maxsilence also generate events. In our example, we only want to allow a message to be 60 seconds long, so we give it an upper limit. After 60 seconds, the recordaudio will stop, send the email attachment, and move on to whatever (if anything) is in our event handler.

Maxsilence is similar, but is used in case we don't want 60 seconds of pure silence. When there is no information, audio, etc. coming across the phone, we are in a state of silence -- when that length of silence equals our maxsilence attribute, we stop recording, send the email attachment, and move on to whatever (if anything) is in our event handler.

Step 3: adding our event handlers

First, we need to add each of our three event handlers (one each for termdigits, maxtime, and maxsilence, respectively):



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

<callxml version="2.0">



  <block>

    <recordaudio format="audio/wav"

                          value="mailto:my-email@my-email-server.com"

                          termdigits="#"

                          maxtime="60s"

                          maxsilence="10s"

                          beep="true"/>



     <ontermdigit value="#">

     </ontermdigit>



     <onmaxtime>

     </onmaxtime>



     <onmaxsilence>

     </onmaxsilence>



  </block>



</callxml>

Then we need to add the appropriate messages so the caller can known what has happened, right?



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

<callxml version="2.0">



  <block>

    <recordaudio format="audio/wav"

                          value="mailto:my-email@my-email-server.com"

                           termdigits="#"

                           maxtime="60s"

                           maxsilence="10s"

                           beep="true"/>



     <ontermdigit value="#">

       <text> Your message has been sent.</text>

     </ontermdigit>



     <onmaxtime>

       <text> You have reached maxtime.  Message sent.</text> 

     </onmaxtime>



     <onmaxsilence>

       <text> Maxsilence exceeded.  Message sent.</text> 

     </onmaxsilence>



  </block>



</callxml>

Step 4: adding a greeting

All that remains now is to create our greeting file, as no answering machine is complete without a message (you do remember how to record a file from Lesson 1, right?). Record a file and save it as "greeting.wav".



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

<callxml version="2.0">



  <block>

    <playaudio value="http://www.myserver.com/greeting.wav"/>



    <recordaudio format="audio/wav" value="mailto:my-email@my-email-server.com"

                           termdigits="#" maxtime="60s" maxsilence="10s"  beep="true"/>



        <ontermdigit value="#">

         <text> Your message has been sent.</text>

       </ontermdigit>



     <onmaxtime>

       <text> You have reached maxtime.  Message sent.</text>

    </onmaxtime>



     <onmaxsilence>

       <text> Maxsilence exceeded.  Message sent.</text>

     </onmaxsilence>



  </block>



  <onerror>

   <sendemail from="MyApp@here.com"

    to="YourEmail@there.net" type="debug">

    We caught an error in our application.  Details follow...

   </sendemail>

  </onerror>



</callxml>

Step 5: upload, and try it out

Your updated hello world callxml application is now done. Now you can call the number associated with your callxml application to hear the results.

CallXML 2.0 source code.

What we covered:

Learned how to record an audio file with the record audio action element
Saved an audio file as an email attachment
Uploaded a new hello world application

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Recording Audio

| TOC

| Introduction to CallerID