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.

Introduction to CallXML

If you have come to this documentation, then you are no doubt slavering to learn the CallXML language. What follows will give you the broad overview of what the CallXML markup can do, and more importantly, what it cannot do. We will cover the basic building blocks of CallXML, the core theories of design, and give you an idea of where to start and where to look for the information that you will need at your fingertips when coding your applications on the Voxeo network.

What is CallXML?

CallXML is an XML based markup language used to describe the user interface of a telephone, voice over IP, or multi-media call application to a CallXML browser. A CallXML browser can then use that description to control and react to the call itself. CallXML includes:

Media action elements such as <playaudio> and <recordaudio> to describe what to present to the user during a call
Call action elements such as <answer>, <call>, and <hangup> to describe how to control and route the call itself
Logic action elements such as <assign>, <clear>, and <goto> to describe how to modify variables and interact with traditional server-side web logic such as perl, PHP, ColdFusion, or ASP
Event elements such as <ontermdigit> and <onhangup> to describe how to react to things the user can do during the call, such as pressing digits or hanging up
Block elements which logically group actions and events together, so that one set of event handling elements can be used for several sequential actions

CallXML compared to HTML

HTML is a markup language used to describe the user interface of a web application. The table below compares some elements from HTML to elements in CallXML:

HTML Markup	Explanation	CallXML Markup	Explanation
html	element begins an HTML document	callxml	element begins an CXML document
table	element groups other visual elements together	block	element groups other CallXML action and event elements together
img	element displays a graphic	playaudio	element plays an audio file
a href="URL"	element describes where to go when a user clicks on a web link	ontermdiigit	event element describes what to do when a user presses a button on the phone

If you know HTML ...

If you know HTML but not XML, you will find that the two are very similar, although XML requires more precision when coding. Significant differences include:

HTML files are often called "pages", while XML files are normally called "documents".
All XML elements must be closed. For example, in HTML you often find the paragraph element (< p >) without a closing element. This is not allowed in XML. In XML you have to close the element like this:

More surprising is the fact that empty elements must be closed as well. So the HTML break tag <br> would have to be closed in XML with the combined open/close element form:

For compatibility with existing HTML processors, you should always include a space before the closing slash.
When using elements with names that are identical to existing HTML elements, you should avoid using the equivalent form, since many HTML processors will break when they see this construct.:

XML is very strict about nested elements. While HTML will let you get away with a construct like this:

XML requires all contained elements to be closed before the containing element can be closed. So this is the legal way to handle the tags in XML:

Note that HTML officially requires the same thing, but these errors are so common that most HTML processors deliberately ignore them.

Now, let's look at a comparison of a CallXML app versus a simple HTML application:

HTML Sample Code



<html>

  <body>

    <img src="AngryGrandpa.jpg"/>

  </body>

</html>

CallXML Sample Code



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

<callxml version="2.0">

  <block>

    <text>

      Grandpa is angry!

    </text>

  </block>

</callxml>

Both pages output content to the user, the only difference in the two examples above is the semantics of the markup, (duh!), and the medium of delivery...in one case, we have a visual representation of an angry grandpa delivered by a web browser, in the other instance, we have an audio file informing us that Grandpa White is mightily upset, which is delivered by the telephone.

CallXML compared to VoiceXML

VoiceXML is designed to make it easy for web developers to create voice recognition based interfaces for either telephones or computer-based applications. As such, VoiceXML is an excellent solution for voice based applications which provide access to web content and information, including:

Applications which allow users to retrieve web content via phone (i.e., voice portals, web-by-phone, audiotex, etc.)
Applications which allow users to interact with web based services using spoken commands (i.e., stock quotes, sports scores, etc.)

CallXML was designed to make it easy for web developers to create applications that can interact with and control any number or type of calls, including:

Telephone or Voice over IP call applications which can control the initiation and routing of a phone call itself, supporting such features as outbound dialing, conferencing, and multi-call interactions (i.e., conference bridges, internet call waiting, follow-me/find-me, etc.)
Telephone or Voice over IP call applications which can easily interact and respond to touch-tone based entry and selection (i.e., voicemail, interactive voice response, etc.)
Call Applications which include support for additional media, such as faxes and video (i.e., unified messaging, video conferencing, etc.)

Because of the natural complexity associated with dealing with voice commands, VoiceXML uses a relatively complex form / field / grammar / filled interface model in its design. In contrast, CallXML uses a more simplified block / action / event interface model, which can be easier to learn and which allows for visual design tools which directly represent CallXML markup as simple flowchart-like user interfaces.

How it Works

Creating a telephony application on the Voxeo platform is easier than you might think. Sticking with our HTML versus CallXML analogy, lets look at how HTML pages are served up, and compare it to how CallXML pages get executed by your callers. When designing an HTML page, like our example above, we first author the document, and then upload it to our webserver so that it is publicly available for the whole world to see. CallXML is no different; content must reside on a public webserver so that our servers can see it.

CallXML works with the same general principles, but with a slightly different spin, as we are using the telephone as the browser. The first difference is that while webhosts commonly serve up HTML, there aren't that many folks in the telephony game, so you will have to specifcally associate a phone number from a voice gateway, (us), and map it to the URL where your CXML page resides. This is easily accomplished in the Voxeo Account Manager, (see Lesson 1 for more information on mapping applications in the VAM).

The next point is in how documents are fetched and executed. When a user clicks a link to our 'angry grandpa' HTML page, a request is sent to the webserver hosting the document, and the HTML page will then load the page in the user's web browser with the accompanying picture of a really angry 'golden ager'. Who happens to be holding a pair of .45's.

Again, CallXML works on the same principles, but remember that we are using the telephone as our web browser. Instead of clicking on a link, a user will dial the number pointing to your application, which is the equivalent of a hyperlink in HTML. When this number is dialed, it tells our servers to fetch the document that has been associated with that particular phone number or PIN code. Assuming that the code is well formed XML, and that the mapping has no typos, then our AngryGrandpa.xml file will load and execute, thus outputting the text to speech message to the caller.

What Will We Learn?

The Voxeo CallXML Guide is broken down in a pretty simple format. Preceding each hands-on, how-to module, you will find a short introduction that explains the principles of each Lesson in detail.

By the time you have completed the Lessons in the Voxeo CallXML guide, you should have a solid handle on the following topics:

Text-to-Speech in the CallXML environment
DTMF (phone keypad) entry and recognition
Script Navigation within a single Document
Script Navigation to an External Document
Recording Audio & Mailto
Single Party Conferencing
CalledID and CallerID
Cache Control and CallXML
Using an HTTP request to create an outbound call

Also included in this reference manual are sections that will clue you in on the best practices that the Pros use, a treatise on debugging your CallXML applications, and more stuff that I haven't written yet. Stay tuned...

ANNOTATIONS: EXISTING POSTS

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

Table Of Contents

| TOC

| Platform Overview