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.

CallXML 3.0 Porting Guide

The Prophecy 8.0 hosted platform for CallXML 2.0 is slated for end-of-life at the end of 2011 in favor of the Prophecy 10 platform software, and CallXML 2.0 will no longer be officially supported. It is our hope that we can help all of our production customers and active developers get ready for this platform end-of-life well before this time comes.

When switching from the CallXML 2.0 markup to the newer CallXML 3.0 markup, there are a few things to bear in mind. As with any migration to a new software offering, there will be some degree of application-scoped edits to apply on the developer side, and we will try to detail each and every possible impact to any existing code in the below porting guide. In the case of CallXML 2.0 users, be aware that while it is not absolutely required to update your application content to the 3.0 markup syntax aside from changing the version declaration, it is very highly recommended to do so.

Frequently Asked Questions

1: Why do I have to move to CallXML 3.0 and what can I expect?
Voxeo is continuously making improvements to its platform, and the CallXML 2.0 markup uses an antiquated code branch. As part of our efforts to continually enhance our IVR services, CallXML 3.0 is the new standard for development.

2: What do I need to do in order to get ready?
For any existing applications that are currently deployed and active, you will need to secure resources for functional application testing on the new software platform. The first step to making sure that you are ready for this porting effort is to research what version of IVR software that you are currently using on Voxeo's hosted platform. You can verify this in several ways:

Within your code, if your initial declaration reads as <callxml version="2.0">, this indicates that your code will always use the CallXML 2.0 engine. By contrast, if your application code specifies <callxml version="3.0">, then your code was written with the Prophecy software platform in mind.

If there is any doubt at all as to what platform that you are using, we encourage you to <url=http://evolution.voxeo.com/account/tickets/tickets.jsp?bb-name=tickets-account&bb-cmd=newpost>ask us for confirmation</url>: We are happy to provide assistance to our developers to ensure that no problems arise from the migration to the newer software platform.

After auditing the XML applications and applying the suggested changes detailed in this guide, then it is time to map the new instance of the application to the most recent version of Voxeo's Prophecy IVR software:

1) Login to your evolution account, and select "Application Manager" ("Account" --> "Application Manager")

2) Select "Add Application"

3) Choose the "Prophecy 10.0 - CallXML 3.0, Staging" platform

4) Map your new instance of the XML code to the platform, provision a number or application token as needed

3: After testing, how do I migrate my production applications to the Prophecy platform?
When you are ready to switch your production applications to using the Prophecy platform, you may either create the new Production mappings yourself, and use the "move" button in the "phone numbers" or "call start tokens" tab of the application detail screen, or you may contact your Account Manager via our <url=http://evolution.voxeo.com/account/tickets/tickets.jsp?bb-name=tickets-account&bb-cmd=newpost>ticketing system</url>, and list the application names denoted that you want switched over in order to migrate a large group of applications en masse.

4: How do I perform a functional test?
It is strongly advised that all call paths, event and error handlers, and text-to-speech formatting, audio files, and resource fetching is tested very thoroughly and completely to ensure that no unforeseen problems occur after migrating to the new platform.

5: What if I have a problem during testing?
If you come across a problem in your porting efforts and testing that isn't covered in our porting guides, then the <url=http://evolution.voxeo.com/account/tickets/tickets.jsp?bb-name=tickets-account&bb-cmd=newpost>Voxeo Support</url> team is standing by to assist 24 hours a day, 365 days a year.

Prophecy CallXML 3.0 features

The below notations describe the major upgrades and additions to CallXML that have been introduced in the deployment of the CallXML 3.0 markup language. Note that while CallXML 2.0 is fully backwards-compatible with a 3.0 application mapping, some developers may wish to take advantage of the new features, and to fully convert their older 2.0 applications to utilize some of these features.

CallXML 3.0 introduces voice recognition capabilities to the language, which can be enabled via the new "choices" attribute: Simple comma-delimited grammar choices can be specified, or a fully detailed JSGF grammar can be used, depending on the complexity desired.

CallXML 3.0 also comes with native <url=http://docs.voxeo.com/callxml/3.0/appendixf_cxml.htm>XPath 1.0 support</url>, which provides a much easier interface to accessing "plain" XML node data without having to resort to using the Document Object Model. The inclusion of Xpath support also has several <url=http://docs.voxeo.com/callxml/3.0/xpathfunctions_cxml30.htm>built-in functions</url> that can be used by developers for string manipulation, mathematical calculations and the like.

For the first time when using CallXML, developers can now use <url=http://blogs.voxeo.com/voxeodeveloperscorner/2008/02/22/certified-tech-tip-prophecy-8-ssml-in-callxml/>SSML syntax</url> to get even finer-grained control over text-to-speech output, thereby allowing for more room to tweak, tune, and polish an application for a better caller experience.

CallXML 3.0 has inherent support for conditional logic operations by way of the new "test" and "value-is/value-is-not" attributes.

CallXML application porting

Note that application edits are required when moving from CallXML 2.0 to the CallXML 3.0 platform. To be absolutely clear, CallXML 2.0 markup should run without incident on the Prophecy platform when mapped to the application type "Prophecy - CallXML 3.0" assuming that you enact the change in CallXML version number, as listed below. However, it is very strongly encouraged that developers make the effort to port their code so that CallXML 2.0-specific elements are removed, and then updated with CallXML 3.0-compatible syntax.

When porting your code from 2.0 syntax to 3.0 syntax:

For CallXML 3.0 documents, note that the version information specified in the declaration must be adjusted accordingly: <callxml version="3.0">

The <text> element has been deprecated in favor of <say>
The various <on[EVENTNAME]> handlers have been deprecated in favor of the finer-grained <on> handler elements: The deprecated event handler listing encompasses <onanswer>, <oncallfailure>, <oncparesult>, <onerror>, <onexternalevent>, <onhangup>, <onmaxdigits>, <onmaxsilence>, <onmaxtime>, and <ontermdigit>.

The Prophecy IVR software is more strict in terms of requiring that the initial xml declaration is defined on the first line of the XML output. Developers should be very careful to ensure that <?xml version="1.0" encoding="UTF-8"?> is on the very first line of all application content, else the interpreter will default to using the 2.0, or 1.0 engine, which will then result in the newer 3.0 tags not being recognized: Consequently, a fatal error may be thrown in these cases.

Outbound call transfer syntax via the <transfer>, <call>, or <createconference> elements, or programmatic outbound dialing via a request to http://api.voxeo.net should be specified using a strict <url=http://en.wikipedia.org/wiki/E.164>e.164 format</url>, as the Prophecy software is more strict in this regard: CallXML 3.0 code should use a syntax that specifies "tel:+<country code><number>", or "tel:+14072223333".

ANNOTATIONS: EXISTING POSTS

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

Cache Manager API

| TOC

| Learning CallXML