VoiceXML 2.1 Development Guide

Home | Frameset Home

Using Audio Files

| TOC

Caller ID-Called ID

Tutorial: Call Transfer

This tutorial is based on the things you accomplished in Lessons 1 through 3. If you have not completed those tutorials, you'll need to go through them first. In this tutorial, we will:

construct an outbound dialing application
learn and implement common telephony error handling for phone transfers
utilize structures to trap hangup events

upload the new app and try it out

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.

Step 1: creating our initial VoiceXML structure

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



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

<vxml version = "2.1" >



</vxml>

Step 2: making an outbound call

VoiceXML allows you to "place an outbound call" in a very succinct fashion. Notice that there are quotes around the phrase "place an outbound call" -- this is intentional, as there are several important limitations that must be noted. But first, let us look at the syntax:



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

<vxml version = "2.1">





<form id="CallTransfer">

    <transfer name="MyCall" dest="tel:+11112223333" bridge="true" >

     

    </transfer>

  </form>

</vxml>

The term "call transfer" is a more accurate description for this process. As we have our value for "bridge" attribute set to "true" in this case, VoiceXML will attempt a bridged transfer to the phone number in the <transfer> element; in this case, 1-111-222-3333. Say, can we make a bridge='false' (or 'blind'), transfer? Sure you can, but it won't work. The Voxeo network does not allow 'blind' transfers on the Staging network, but we do allow 'take back and transfer' calls on the Production network. Contact your designated Voxeo Account Manager for details on this feature.

Notice that the string "tel:" is included inside the attribute value -- this is required so that VoiceXML knows to induce a telephony function rather than, say, goto a new VoiceXML webpage (which is what we learned how to do with the <goto> element back in Tutorial 4. There also needs to be 10 digits for the phone number to connect successfully.

Now that we have this knowledge of transfers down pat, let's take a closer look at the individual attributes of the transfer element.

Name : The transfer name works pretty much like a field name in that we use this namespace as our 'call variable'. Our call, and various aspects of it such as error handling and hangup can be referenced by using the name we give it here.
Dest : This is the place where we code in the destination phone number.
Bridge : This controls whether or not our call is a bridged, or blind transfer. A Blind transfer, (again, unsupported on the Voxeo network), can be summed up by saying that once the caller initiates a transfer to another party, the application disconnects from the caller; no further interaction with the application is possible aside from a final catch hangup/submit action. A Bridged transfer means that the application stays connected to both lines after the transfer goes through, allowing the caller to return to the application once the transfer is complete.
Connecttimeout : This simply defines how long we want to let the application ring the destination phone before timing out and throwing a "noanswer" event (see below).

Keep in mind, the transfer technology itself was designed with the intention to call numbers that answer on the first ring (such as call centers). That means what exactly? Well, the most obvious effect is that, for both good and bad, the "timeout" length for the call to successfully transfer defaults to around 10 seconds. This can be bad because if your code is attempting to transfer to a normal phone (like your brother, who is lazy and takes his time strolling across the room to pick up the phone), it may timeout before an answer event occurs. But, we can easily adjust this with the timeout attribute of the transfer element.

So what happens when the call is initiated? Like any normal telephone call, the caller will now either be able to interact with whatever exists on the other phone line (voicemail, live person, call center automaton, fluffy cat that accidentally knocked the phone off the hook, etc.), or the call will get a busy signal, or maybe that lazy brother lets the phone ring off the hook until our humble app times out. So how does the VXML interpreter discern that the call got picked up, you ask?

Notice that in the next step below, we have added a <filled> event, (along with a spiffy prompt), which works just like the <filled> event in a voice-reco field. In this <filled> event, we place some conditional statements to execute depending on what value our transfer variable resolved to. If we receive a busy or a noanswer event, they will be caught and dealt with by using these basic error handling techniques:



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

<vxml version = "2.1">





<form id="CallTransfer">

<!-- *************************************************************************** -->

<!-- TRANSFER  sample code as performed by Snoop Doggy Dogg  -->

<!-- *************************************************************************** -->



 <block>

  <prompt>Dizzling the phizzle</prompt>

 </block>



<transfer name="MyCall" dest="tel:+11112223333" 

          bridge="true" connecttimeout="20s">



<filled>

    <if cond="MyCall == 'busy'">

     <prompt>

       Tha fizzle be fo bizzeled shizz, nephew.

     </prompt>

<exit/>

    <elseif cond="MyCall == 'noanswer'"/>

     <prompt>

      No bizzle is in the hizzle.

     </prompt>

    </if>

   </filled>

  

 </transfer>

</form>

</vxml>

Now that we have learned how to trap and handle the possible results of the call, what happens when we disconnect? Well, we can handle that stuff, too. We have three possible results that can result from a party hanging up:

far_end_disconnect : returned result when the called party hangs up.
near_end_disconnect : returned result when the dialing party, (you), disconnects from the transfer via a dtmf keypress

For the final part of this tutorial, we will add some more event handlers so that we are prepared for these types of scenarios:



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

<vxml version = "2.1">







<form id="CallTransfer">

 <block>

<!-- *************************************************************************** -->

<!-- TRANSFER  sample code as performed by Snoop Doggy Dogg  -->

<!-- *************************************************************************** -->

  <prompt>Dizzling the phizzle</prompt>

 </block>



<transfer name="MyCall" dest="tel:+11112223333" 

          bridge="true" connecttimeout="20s">



<filled>



    <if cond="MyCall == 'busy'">

     <prompt>

       Tha fizzle be fo bizzeled shizz, nephew.

     </prompt>

<exit/>



    <elseif cond="MyCall == 'noanswer'"/>

     <prompt>

      No bizzle is in the hizzle.

     </prompt>



    <elseif cond="MyCall == 'far_end_disconnect'"/>

    <prompt> 

     Yo bizzel done be dizzleling tha phizzle on you.

    </prompt>



   <elseif cond="MyCall == 'near_end_disconnect'"/>

    <prompt> 

     <!--submit next ="MyCoolCleanupPage.cgi"/-->

    </prompt>



    </if>

   </filled>

  

 </transfer>

</form>

</vxml>

Note the fact that the catch event for "disconnect" is commented out in this example; it is shown here to illustrate the allowable syntax for handling a such an event.

All that remains now is to upload our new hello world VoiceXML application. In keeping with our naming scheme, we might save this file as http://www.myserver.com/helloworld/helloworld6.xml. Now you can provision a number to your simple call transfer application, and call all your friends to impress them with this cool insider knowledge.

Download the Code!

Motorola source code.

What we covered:

learned the how to make calls via VoiceXML
learned how to trap transfer errors in VoiceXML
learned how to trap disconnect events in VoiceXML
uploaded a new hello world application

ANNOTATIONS: EXISTING POSTS

ddantow

11/9/2005 2:11 PM (EST)

I think there's a single quote missing from this line:
<elseif cond="MyCall == 'far_end_disconnect"/>
It should be
<elseif cond="MyCall == 'far_end_disconnect'"/>

mikethompson

11/9/2005 2:34 PM (EST)

Hey there,

Thank you for bringing this minor error to our attention. This error has been corrected in our internal documentation build, which we will be rolling out to the external environment in a week or so. Thanks again!

~Mike

haigang

11/21/2006 2:58 AM (EST)

Hello ,How many tel id can call in dest="tel:xxxx" Simultaneously? Thanks

sidvoxeo

11/21/2006 12:04 PM (EST)

Hi there,

You can only make a single transfer using the dest="tel:xxxx" attribute of VoiceXML transfer element.
On our Staging platform if you use tokens to make outbound calls, you can make two calls concurrently.

~Sid

artybala

6/3/2007 11:25 PM (EDT)

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

<form id="CallTransfer">

<block>
<prompt>
Hello World
</prompt>
</block>

<transfer name="MyCall" dest="tel:+18176841884"
bridge="true" connecttimeout="20s" maxtime="60s">
</transfer>

</form>

</vxml>

Hi.,
I am learning to write Voice Applications through the tutorials.
When i use the above code, it says that "this content has an internal error" Can you please tell me what am i missing.?

Thanks

voxeojeff

6/3/2007 11:38 PM (EDT)

Hi artybala,

The problem was that your account was not flagged for outbound dialing access, thus you could not execute the transfer :) This has been fixed, and you should now be able to do so. Please remember to use this privilege for testing purposes only, in order to keep your outdial ability.

Best regards,

Jeff Menkel
Voxeo Corporation

artybala

6/4/2007 7:16 PM (EDT)

Jeff.,

Thanks a LOT. i am able to test the call transfer now.
Thanks for the faster response.

Thanks
artybala

DanYork

1/26/2008 4:52 PM (EST)

I'll note that to do a transfer to a SIP endpoint, you basically just replace the "tel:<number>" with "sip:<SIP address>" subject to one difference outlined below.

As an example, Gizmo SIP addresses take the format "<number>@proxy01.sipphone.com".

The syntax for the on-premise Prophecy would be similar to this:

<transfer name="MyCall" dest="sip:17476185034@proxy01.sipphone.com" bridge="true" connecttimeout="20s">

However for the hosted Evolution platform, you need to find out the IP address of the SIP server and modify the string to be:

sip:<SIP endpoint address>!<SIP server IP address>@sbc-staging-internal

For instance, my Gizmo address is "17476185034" and the IP address for "proxy01.sipphone.com" is "198.65.166.131", so the resulting transfer statement looks like this:

<transfer name="MyCall" dest="sip:17476185034!198.65.166.131@sbc-staging-internal" bridge="true" connecttimeout="20s">

As another example, my Voxeo SIP address is "dyork@corpsip.voxeo.com" which would translate into:

<transfer name="MyCall" dest="sip:dyork!66.193.54.208@sbc-staging-internal" bridge="true" connecttimeout="20s">

More info can be found in these threads:

- https://evolution.voxeo.com/bizblog/viewer?&bb-name=masterforum&bb-q=sip+gizmo&&bb-cid=5&bb-tid=487502#bb
- https://evolution.voxeo.com/bizblog/viewer?&bb-name=masterforum&bb-q=sip+gizmo&&bb-cid=6&bb-tid=496278#bb

alexey.timofeev

2/27/2008 9:50 AM (EST)

Hi!

Is there any possibility to call line identifier (CLI) during the transfer?

I mean the next kind of situation:
1) we call to the person;
2) the vxml script is launched;
3) the person chooses to transfer the call;
4) the call is transferred to the call center and on the call center's phone the person's number appear.

Is it possible? Would it be possible if it is the outbounding call?

Thanks in advance

voxeojeff

2/27/2008 10:05 AM (EST)

Hi Alexey,

You can "spoof" the caller ID on a VoiceXML transfer by specifying ';ani=1234567890' in the dest attribute. For example,

<transfer name="Mycall" dest="tel:+12223334444;ani=5556667777" bridge="true" connecttimeout="20s" maxtime="60s">

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

For US carriers, there is a 10 digit limit for ANI. In our UK VoiceCenter, you may specify more than 10 (up to 13) in order to simulate a UK CLI.

Hope this helps,

Jeff

alexey.timofeev

2/28/2008 10:42 AM (EST)

Hi Jeff
Thanks a lot for your answer.

I'll appreciate a lot if you answer my following questions:

1)Could I use the ECMAscript variable for ANI? I mean if I have <var name="phone" expr="'0101010101'"/> will the following code be correct:

<transfer name="Mycall" dest="tel:+12223334444;ani=phone" bridge="true" connecttimeout="20s" maxtime="60s">
</transfer>

For US carriers, there is a 10 digit limit for ANI. In our UK VoiceCenter, you may specify more than 10 (up to 13) in order to simulate a UK CLI.

2)What will happen if the ANI has more than 10 (or 13 - for UK VoiceCenter) digits? CLI won't be transferred to the Call center?

mikethompson

2/28/2008 12:59 PM (EST)

Hello Alexey,

Allow me to address your questions numerically...

1) If you want to dynamically populate the ani value, you'll have to use server-side scripting, as ani is not an attribute, it is simply an extension of the transfer destination.

2) When testing this to my cell phone, the call was still successfully placed. I set the ani to '12345678901234' and that is what came through on my display. This was a Blackberry setup with Verizon. When placing the call to my Desk SIP phone, the entire callerID was passed as well.

As for the UK VoiceCenter...

Yesterday, we tested transfer ani from the UK VoiceCenter with more than 13 digits in the callerID, and the call failed.

Hope this helps,
Mike Thompson
Voxeo Corporation

alexey.timofeev

2/29/2008 4:28 AM (EST)

Hi Mike!

I do appreciate the information you've provided. That's very valuable help for me.

I'd like to confirm one more issue with you.

I have the variable <var name="phone" expr="session.connection.ccxml.values.phone"/> and I need to pass it as CLI during the transfer call. As far as I understand I have no opportunity to do this?

Thanks in advance

mikethompson

2/29/2008 3:58 PM (EST)

Hello Alexey,

You can do this with the use of sever-side scripting, but there is no way to pass the ani in a VoiceXML transfer dynamically via ECMA script. You could simply pull the variable phone from the querystring with something like PHP and echo it into the ani= space. Let me know if this doesn't make sense.

Best,
Mike Thompson
Voxeo Corporation

eraldo

4/10/2008 1:30 PM (EDT)

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1">
<form id="Proof">
<block>
<prompt>
Hello World. This is just a test. Lets see what happens.
</prompt>
</block>
<transfer name="MyCall" dest="'sip:17473083562!198.65.166.131@sbc-staging-internal'" bridge="true" connecttimeout="40s" maxtime="60s">
</transfer>
</form>
</vxml>

I'm new in this stuff, right now i'm trying to test this code, but there is some error message that appears and says that has an internal error. Can u help me with that? Thanks a lot.

voxeojeremyr

4/10/2008 3:50 PM (EDT)

Hi eraldo,

Looking at your code, it appears you have the destination enclosed in double quotations and also in single quotations. If you remove the single quotations, the syntax will be valid.

Also, your account needs to have outbound dialing privileges. To have those those granted, please open a support a support ticket and we would be happy to help you.

We have some documentation that covers transfers and outbound dialing here:
http://docs.voxeo.com/voicexml/2.0/t_6.htm
http://docs.voxeo.com/voicexml/2.0/token_intro.htm

Thanks,
Jeremy Richmond
Voxeo Support

borisattva

6/3/2008 6:47 PM (EDT)

Hi Mike,

To add to the subject of Alexeys questions; you explained its impossible to dynamically allocate specifically the 'ani' portion of the dest= attribute.
Does that limitation extend to 'dest' attribute as a whole?

I'm asking this in the context of constructing the whole 'dest' attribute dynamically.

rough example:

(vars XFRDest, XFRNumber, XFRAni)

<assign name="XFRDest" expr="tel:' + XFRNumber + ';ani=' + XFRAni"/>

<transfer name="MyCall" dest="XFDest" bridge......etc

Does this make sense? Or is dest limited to being explicitely static syntax&content...

Thanks,

voxeodamonic

6/3/2008 11:36 PM (EDT)

Hi,

I will forward your question to our Tier II support. Please allow us some time to research your inquiry and provide more details by tomorrow afternoon.

Thanks,

Damonic Robertson
Voxeo Support

voxeojeremyr

6/4/2008 6:32 AM (EDT)

Hi,

While you cannot use the dest attribute of a transfer to dynamically set the transfer number, you can use destexpr which allows you to use ECMAscript to build your transfer string. For example, this snippet of code works:

<var name="numberToDial" expr="'+14075551234'"/>
<var name="aniSpoof" expr="'4075559999'"/>

<transfer name="MyCall" destexpr="'tel:' + numberToDial + ';ani=' + anispoof"
bridge="true" connecttimeout="30s" maxtime="0">

Or you could certainly build the string prior to the transfer and simply call a variable such as this:

<var name="numberToDial" expr="'+14075551234'"/>
<var name="aniSpoof" expr="'4075559999'"/>
<var name="transferNumber" expr="'tel:' + numberToDial + ';ani=' + anispoof"/>

<transfer name="MyCall" destexpr="transferNumber"
bridge="true" connecttimeout="30s" maxtime="0">

Happy Coding.

Jeremy Richmond
Voxeo Support

Using Audio Files

| TOC

Caller ID-Called ID