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 Transfer Types and Call Exceptions

This section is a must-read for anyone intersted in making outbound calls on the Voxeo network. Failure to read this section before contacting Voxeo Support for assistance might well cause spontaneous combustion in the user; for this reason, it is recommended that you review the information listed here with a fine-toothed comb.

Note: This tutorial requires the use of outbound dialing priveleges, which must be provisioned by voxeo support. If you have not contacted us to get these permissions, click here to learn how you can get hooked up with this feature.

Transfer Types...bridged or blind?

One of the three ways that you may dial out within your Voxeo CallXML applications is to make use of the <transfer> element. Lesson 6 covers this procedure step by step, so we will content ourselves with a broad overview of the types of calls we can make, and the intricacies of dealing with all of the possible events that can happen during a <transfer>.

There are two kinds of calls that we can make on the Voxeo network, a bridged transfer, and a blind transfer. A bridged transfer is where the original caller is returned to the CallXML application after the dialed party hangs up, and a blind transfer will end the application execution when either party disconnects. Note that at this time, only bridged transfers are allowed; blind transfers are not enabled on either the Staging network, or on the Production network. For a true blind transfer, you will need to contact the Voxeo Sales team, and get hooked up with the ‘take-back and transfer’ feature, which allows the caller to dial into the application, and then make a transfer off the Voxeo network. This feature is not enabled on the Staging center, but can be enabled on a Production application upon request. Contact the Voxeo Sales Team for further details regarding this feature.

Call Exceptions

There are several events that can happen when an outbound call is placed using CallXML; knowing what these events are, and how we can trap and handle them is key to making a smooth application that you can call your own. The following listing details these events, and offers suggestions for discreet handling so that your callers are none the wiser when your application goes belly-up.

oncallfailure events

This event will be thrown when any set of circumstances dictates that the conference has ended. The possible types of callfailure, and their explanations are as follows:

oncallfailure value="busy" : This event indicates that the destination number returned a 'busy' signal
oncallfailure value="noanswer" : Indicates that the called party did not answer the phone before the call/transfer 'maxtime' was exceeded
oncallfailure value="unreachable" : This is returned when the destination number returns a SIT tone;( 'doo doo dee, the number you have dialed is not in service at this time'), most often, the dialed number is either employing a call screening device, or is indeed out of service
oncallfailure value="rejected" : This event will very rarely get returned. In some circumstances, a switch or PSTN might return a series of codes to the CallXML browser, informing it that the destination number has been rejected at the Telco level
oncallfailure value="unknown" : The call was rejected for unknown reasons

For further information on these error types, and their usage, please see the CallXML Element Guide.

Additional Event Handling

Depending on your application architecture, there are a few more things that smart developers will be prepared to catch and handle when doing an outbound call. All methods of outbound calls allow you to specify a termdigit value, so we will want to trap and handle these events. In addition, we will also want to be prepared when the called party hangs up, so we will want to add that to our list, as well:

<ontermdigit> : This event will get thrown when the caller presses a DTMF key that will terminate the conference, as dictated in the 'termdigits' attribute of either the <call> or the <transfer> element.
<onhangup> : This might seem rather redundant, but when the called party decides to hang up, we will need to handle the event unless we want application execution to end. Adding an <onhangup> handler to our code allows us to seamlessly transition our original caller elsewhere in the application

Inbound International Dialing

While we Americans tend to show a bit of hubris when it comes to..well, just about everything, we certainly don't discriminate when it comes to sharing the love to our friends from other countries. If you happen to live 'across the pond' from us Yanks, then you still have the ability to use our testing platform for free. Another Capitalist trick, you ask? Not hardly. Our partnership with Free World Dialup allows anybody with a internet connection to make a SIP call to our networks, without incurring any weighty long distance fees. Check our VoIP dialing information page, and our web-forums for more information on this feature.

Outbound International Dialing

Some applications with a 'world beat' in mind will likely want to make use of outbound International dialing, such as within the <transfer> element, or within a token-based outbound call. Before we start, there are a few basic things you should know about International dialing on the Voxeo platform. Intenational dialing can be enabled for production accounts only, with the following caveats:

A prepaid deposit of $5000.00 is required before this can be enabled for a particular account.
A one-time setup fee, (non-refundable), of $775.00 is required, for this feature.
International rates are almost always more expensive than calls within the Continental US. It is the customers responsibility to make themselves aware of the billing differences

Contact our sales team for additional information on International dialing.

Once you have gotten setup with this feature, then you'll need to actually code it, so a few bits of advice are in order to get you off on the right foot. The number formatting for placing an international call to anyone is as follows:



tel:+[country code][number]

So, if you wanted to place a bridged transfer to '000-111-2222' in Uganda, where the Country Code is '256' then your dialing string might look like this:



<transfer value="tel:+2560001112222">

For a token-initiated call, the same holds true, but with one caveat: Sending a string value of 'tel:+2560001112222' isn't going to fly at all, as we will need to URL-encode the '+' character before sending it across to session.voxeo.net. To illustrate, let's look at two examples:

Incorrect Formatting



http://session.voxeo.net/CallXML.start?

     numbertodial=tel:+2560001112222&

      tokenid=yourTokenIDhere

Correct Formatting



http://session.voxeo.net/CallXML.start?

     numbertodial=tel:%2B2560001112222&

      tokenid=yourTokenIDhere

ANNOTATIONS: EXISTING POSTS

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

B: Outbound Dialing

| TOC

| Outbound Sample Code