Outbound Call via <transfer> Example

The <transfer> element is the means available to the VoiceXML programmer for connecting the caller to another line, and so it deserves to have an in depth treatment of how to best use it when creating voice applications. Let's look at some of the considerations surrounding the use of <transfer>, and then apply them in a fully functioning VoiceXML script. Of course when you need definitive answers you should always go to the source, the almighty W3C itself:

W3C Voice Extensible Markup Language, transfer element

Transfer Types

We should start out by examining the different types of transfers: bridged, blind or take-back-and-transfer. The practical difference between the different transfers is how many lines they require. A blind transfer connects two endpoints directly using one line. Take-back-and-transfer can be thought of as a type of blind transfer where the telecom carrier "listens" for a message to take back this call and transfer it somewhere else instead. These types of transfers depend heavily on carrier specific limitations and configuration. For these reasons Voxeo cannot offer these types of transfers on our Free Developer network, but inquiries for a production environment are welcomed by our sales department at Sales@Voxeo.com.

A bridged transfer is just as it sounds, a bridge. The line carrying the caller is bridged to another line carrying the called party. Both lines are active for the duration of the transfer. We'll be using a bridged transfer for our example.

Effect On Grammars

When a transfer begins some important things happen to your application's grammars. All grammars that have been scoped outside the <transfer> are disabled. This makes sense when you consider that the voice recognizer will be listening during the bridged call, and there would be a good possiblity of an accidental grammar match. You can scope a grammar within the <transfer>, and that will remain active. That is a technique useful for "Transfer Hotwording".

Transfer Outcomes

Information about the return of the transfer is in all but one case determined by the value of the form variable. Simple conditional testing of that variable will allow you to control program flow. The one exception is the instance of caller disconnect where the disconnect was not caused by a grammar match. In that case a connection.disconnect.hangup event is thrown, and the form variable and shadow variables are not set.

Condition	Explanation
maxtime_disconnect	Maxtime of `<transfer>` expired
busy	Destination number was busy
network_busy	Network busy....contact Voxeo Support
noanswer	Connect timeout reached
far_end_disconnect	Callee disconnected during the transfer
near_end_disconnect	Caller disconnected during the transfer
unknown	Call disconnected for an unknown reason

The Code


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

<catch event="connection.disconnect.hangup">
   <log expr="'**** LOG: Near end hung up. ****'"/>
   <exit/>
</catch>

<form id="CallTransfer">
  <block>
    <prompt>Preparing to dial the number.</prompt>
  </block>

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

    <grammar xmlns="http://www.w3.org/2001/06/grammar" xml:lang="en-US"
                    mode="dtmf"
                    root = "MYRULE">
      <rule id="MYRULE">
        <one-of>
          <item> 1 </item>
        </one-of>
      </rule>
    </grammar>

    <filled>
      <if cond="MyCall == 'busy'">
        <prompt>
          The lines are busy. Please try again later.
        </prompt>
        <exit/>

      <elseif cond="MyCall == 'noanswer'"/>
        <prompt>
          No one is answering the line.
        </prompt>

      <elseif cond="MyCall == 'far_end_disconnect'"/>
        <prompt>
          The called party has hung up.
        </prompt>

      <elseif cond="MyCall == 'near_end_disconnect'"/>
        <prompt>
          You have pressed 1 to disconnect the transfer.
        </prompt>
   
      <elseif cond="MyCall == 'maxtime.disconnect'"/>
        <prompt>
          Your call ran over the maxtime of sixty seconds,
            and the called party has been disconnected.
        </prompt>
        
       <elseif cond="MyCall == 'unknown'"/>
        <prompt>
          The call failed for an unknown reason.
        </prompt>

      </if>

  <!-- note that this shadow var is ONLY available if the call transfer completes -->
  <!-- if the caller hangs up while the call transfer is in progress, then this will be 'undefined' -->
  <!-- See "Transfer Shadow Variables" on how to use javascript to calculate duration in that case. -->
      <log expr="MyCall$.duration"/>

    </filled>
  </transfer>
</form>
</vxml>

Download the Code!

Download the source code

ANNOTATIONS: EXISTING POSTS

fayyazkl

2/19/2007 5:03 AM (EST)

I am inputting a number through field type=digit. Now i want to place a call to that number. The problem i am having is, that trasfer function works in a separate form only. If transfer call is nested in the filled event of input, it gives an internal error. If i shift to a new form and make a call then i can't access the early field in which i have input number. How can i access a field declared in a separate form from the from where i am placing calls ?? Please help. I have been trying through all tutorials on this site.

Thanks.

Fayyaz Lodhi

fayyazkl

2/19/2007 7:46 AM (EST)

In addition to above, i read here "during the transfer operation the current interpretter session is suspended". Does that mean that i can't play my recorded voice to a destination number?? Is there a way to do that?

Thanks,

Fayyaz Lodhi

VoxeoBrian

2/19/2007 11:14 AM (EST)

Hello,

Please read through our documentation on variable scoping, this is a very important aspect of vxml programming and should be thoroughly understood.

Variable Scoping:
http://docs.voxeo.com/voicexml/2.0/varscoping.htm

Variables that you want to be accessible through a document should be defined at the application level, and are thus accessible throughout.

As for your second question, with the playing of recorded audio dialog during a transfer the receiving party is not possible within VXML. You can obtain this functionality utilizing a CCXML wrapper and the usage of a whisper message. I hope this information I have provided is helpful to you, if you do have any other questions please don't hesitate to ask.

Cheers

Brian

fayyazkl

2/20/2007 1:13 AM (EST)

Thanks alot Brian. I was already using application scoped variables but i didnt understand the use of "destexpr" instead of "dest" in transfer. Now it works and i was able to place a call simultaneously. I am greateful for your advise and prompt response. Will shift to CCXML now. It really nice to know that people at voax are doing a great job in providing support to people.

best regards,

Fayyaz

fayyazkl

2/22/2007 5:08 AM (EST)

My objective is to play a user recorded voice to a destination number.I have been reading CCXML dialogs and joining two separate call legs. What confuses me is that, join takes call id as parameters which it interconnects. How can i indicate that one of those id's will be an audio file while is played with <audio> tage. I was told as above to utilize whisper message for that. I havent been able to find any thing on that. Could you please indicate a reference to what is a whisper and how to use it in CCXML.

Thanks.

Fayyaz

VoxeoBrian

2/22/2007 10:27 AM (EST)

Hello,

You can find information on the CCXML conference whisper message here:
http://docs.voxeo.com/ccxml/1.0/whisper_ccxml.htm

Please read through this documentation and see if you are able to utilize it successfully. If you are unable to, please do let us know, we are always happy to help.

Regards

Brian

amaghazaji

12/6/2007 2:21 AM (EST)

after a transfer, when the callee picks up, how do we detect that phone has been picked up and that the call is in progress?

VoxeoDustin

12/6/2007 10:50 AM (EST)

Hey Amer,

This is actually handled at the CCXML level. CCXML will throw a CONNECTION.CONNECTED event when the call is accepted. Here is a little info on state handling in CCMXL: http://docs.voxeo.com/ccxml/1.0-final/

If you're coding the CCXML front-end yourself you can actually pass any information to your VoiceXML dialog via <dialogstart namelist="var1 var2".../>.

When you map a VoiceXML script with Prophecy or in our hosted environment, there is a default CCXML script that handles loading that VXML dialog. For finer grained control, though, you can always create your own CCXML script to load your dialog.

Hope this helps,
Dustin

georgelai

1/19/2008 12:03 AM (EST)

A quick question:

Is it possible in one vxml file to <goto ...> a CCXML file? Say a user has dialed into my VXML application. If I want to transfer him to another number, while playing audio, can I transfer to a CCXML application from VXML?

Thanks, I hope I haven't been to unclear.

George

voxeojeff

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

Hi there,

Unfortunately, VXML cannot <goto> a CCXML document. The only way for a VoiceXML document to transition to a CCXML document is via the <exit namelist/> command, returning control to CCXML. In this case, you'll want your main application to be CCXML, which then utilizes VXML dialogs.

Hope this helps,

Jeff

Transfer Exceptions

| TOC

| Blind Transfers