CallXML 3.0 Development Guide

| TOC

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 <prompt>, <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 handling element/attribute combinations such as <on event="choice:foo"> and <on event="hangup"> to describe how to react to things the user can do during the call, such as pressing digits, gathering voice input or hanging up
Container elements, and container element aliases which logically group actions and events together, so that one set of event handling elements can be used for several sequential actions

Whats new in CallXML 3.0?

In an effort to continually improve our platform offerings, Voxeo has announced the next-generation in our CallXML markup language. That’s right, CallXML 3.0 is here! Not tempted yet? Take a look at the new features, and you will be:

Voice Recognition: That’s right, Voxeo has added voice recognition into CallXML 3.0, which leverages the simplicity that CallXML is known for, and allows the ability to write voice-driven applications in the fraction of the time it normally takes with other markups.

Container Element Features: We’ve added a number of new bells and whistles to the container elements, including:
- conditional logic operators
- intrinsic child variable population via a single command
- inherent support for list iterations
- new container aliases allow you to write code that is readable at-a-glance, and lets the you choose the style of element naming that suits your own personal coding style

Improved Event and Error Handling: the addition of a modular event handling scheme allows finer-grained event handling, resulting in cleaner, and more robust handling with even simpler markup than before
Native XPath 1.0 Support: if you haven’t worked with XPath before, you’ll be blown away at how cool this is. Imagine the ability to pull any piece of data from a XML webpage, and importing it to your IVR applications without having to enlist the aid of a server side language. Or, imagine native operators to parse and format your returned data from an XML source. Fantasy? XPath offers this ability and lots more for you to leverage in your next-generation IVR applications.

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	on event="choice:1"	event element describes what to do when a user presses the '1' 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="3.0">

  <block>

    <prompt value="Grandpa is angry!"/>

  </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 complex 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.)
Applications that use simple voice commands
Applications that wish to leverage advanced XPath commands and features

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 CallXML 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 CallXML3.0 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 & the 'Mailto' feature
Single Party Conferencing
CalledID and CallerID
Cache Control and CallXML
Using an HTTP request to create an outbound call
How to use XPath in the CallXML 3.0 context

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

jayanth123

2/18/2009 10:01 AM (EST)

i have a need where i want to do some processing of the data i have received and send it across to our servers.is it possible

voxeoJason

2/18/2009 10:05 AM (EST)

Hi,

Would is be possible to explain what you're trying to do a little more thoroughly so we can give a more precise and relevant answer to your quandary? Once we know exactly what you're asking we can provide thorough support. In the meantime if we can help you with anything else, please don't hesitate to ask.

Standing by,

Jason
Voxeo Support

voxeoJason

2/18/2009 10:31 AM (EST)

Hi,

I believe you might be looking for the [url=http://docs.voxeo.com/callxml/3.0/goto.htm]<goto>[/url] element. If this isn't what you had in mind, please let us know.

Regards,

Jason
Voxeo Support

jayanth123

2/18/2009 10:13 PM (EST)

For example, if i get the dtmf input from the caller,i want the data stored in that variable to be pushed to our database using http post.
Meaning lets say the user entered 200,i want to push this value,the callerid to our server and store it.
Am i clear now?

voxeoAlexBring

2/19/2009 12:21 AM (EST)

Hello,
You can gather DTMF information by simply using the [code]name="foo"[/code] attribute of the [url=http://www.vxml.org/field.htm]<field>[/url] element. By specifying a name to this it will be assigned the value of your prompt from within the <field>. With this value you can then use a [url=http://www.vxml.org/submit.htm]<submit>[/url] element to send this information to a document that can apply this information to your server. Please let us know if you have any further questions or comments that we may be able to assist you with.

Regards,

Alex Bring
Voxeo Support

ananth.nk

3/10/2009 5:08 AM (EDT)

Hi,

Actually I'm trying to call to an IVR(VXML) from a Softphone. I want the IVR to call to another phone(SIP phone or softphone). And after sometime, i need both the softphones to be connected. what should i use for this?

voxeoJeffK

3/10/2009 5:36 AM (EDT)

Hello,

You mention that your IVR is VXML. Rather than the CallXML documentation I might direct you to the excellent tutorials and documentation we have on VoiceXML here:

http://www.vxml.org/

Specifically what you will want to do is accept an inbound call, and then do a <transfer> to the second phone. We have a tutorial on transfers here:

http://www.vxml.org/t_6.htm

There is additional information on outbound dialing here:

http://www.vxml.org/mot_appendixg.htm

And there is specific data concerning the <transfer> element located here:

http://www.vxml.org/transfer.htm

If you are developing on our Hosted platform you will need to request that your account be given outbound dialing rights. Please let us know if this is the case, and we'll be happy to enable that for you.

Regards,
Jeff Kustermann
Voxeo Support

Table Of Contents

| TOC

| Platform Overview