CallXML 2.0 Development Guide Home  |  Frameset Home
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.

<transfer>  element


This element allows multiple lines in a single session to be conferenced together so that the parties on each line can talk to each other simultaneously. Note that there is no event thrown on a "far end" disconnect (i.e., when the called party hangs up). The address is specified by the attribute value and is in URL format. Supported formats include:

tel:  classic phone number (See RFC 2896)
pstn:    same as "tel:", deprecated
sip:      SIP protocol address

Note: The usage of this element 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.



usage

<transfer answeronmedia="(true|false)" callerID="(tel|pstn|sip)" maxtime="(m|s|ms)" method="bridged" playrepeat="(true|false)" playvalue="string - URI" termdigits="(123456789*#|ABCD)" value="(tel|pstn|sip)">


attributes

answeronmedia Data Type: (true|false) Default: none - attribute is optional
Determines when audio passes from second call leg to the first. If set to "TRUE," this will pass audio back to the originating call leg upon the first instance of media. In practice, this will typically mean the caller hears the standard "telephone ring" as if they had picked up a normal telephone and dialed the number. If set to "FALSE," there will be silence until an actual answer or callfailure is achieved.

Note that this attribute is primarily used to detect that a phone has been answered in the event that the destination number does not send back the proper ISDN signal upon pickup, (common to some 800 numbers).
callerID Data Type: (tel|pstn|sip) Default: none - attribute is required
CallerID to present when placing the call. The list of allowable values declared for this attribute follow the same rules as the call value element/attribute combination, to wit:
  • "tel:"            classic phone number
  • "pstn:"          same as "tel:", deprecated value
  • "sip:"            SIP protocol address


maxtime Data Type: (m|s|ms) Default: none - attribute is optional
Maximum amount of time to wait for the call to be answered. Time format strings are used for maxTime and maxSilence attributes, and in the <wait> tag.

The time string format is:
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are:
  • m: minutes
  • s: seconds (default)
  • ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
method Data Type: bridged Default: bridged
This attribute determines the transfer method. At this time, only Bridged transfers are allowed on the Voxeo CallXML network.
playrepeat Data Type: (true|false) Default: False
This attribute defines whether or not the audio file indicated in the <playvalue> attribute should be repeated.
playvalue Data Type: string - URI Default: none - attribute is optional
The playvalue attribute functions in the same way as the <playaudio> element, in that the value defined should be a URI reference which indicates the sound file to play to the caller in place of a ring tone.

The indicated value can either be a complete URI:
http://Myserver.com/MyDir/MySoundFile.wav

or a relative URI:
MySoundFile.wav
termdigits Data Type: (123456789*#|ABCD) Default: none - attribute is optional
This attribute holds the list of touch-tone digits which can terminate the current caller action. Note that for each termdigit specified, there should be an <ontermdigit> handler in the code to catch the event. Allowable values are any one of "012356789*#", the ordinary DTMF (Touch-Tone) keypad possibilities, plus the special keypad tones found on some telephones "ABCD".
value Data Type: (tel|pstn|sip) Default: none - attribute is required
The value for this attribute defines the URL describing the place to initiate a call to. An empty value will result in an error. Any value that does not begin with a valid prefix will be assumed to be a pure "tel:" number.

Valid URL values are:
  • "tel:"            classic phone number
  • "pstn:"          same as "tel:", deprecated value
  • "sip:"            SIP protocol address

Note that developers who use the non-US datacenters are required to specify an E164-formatted dial string:

tel:+[country code][number]



possible events

onerror type="badnumber" The destination number is malformed, or returns a SIT tone.
onerror type="telephony" Unable to issue a telephony event such as <call> or <playaudio> or <ftp>
onmaxtime This event occurs during user input if the user takes more time than is allowed by a maxTime attribute to input their entire response. See the onmaxtime element description for further details.
ontermdigit Used for catching and handling term digit events as they occur in the call flow. See the ontermdigit element description for further details.
onerror type="document" Document was unable to be fetched for all the reasons web servers are unavailable
onerror type="linenotactive" Trying to issue a telephony event such as <getdigits> or <playaudio> on a non-active line
oncallfailure This event occurs when the session determines that the attempted call cannot be completed because the dialed number is busy, a circuit is unavailable, a SIT tone was detected or other detectable call failure mode. The call is not automatically disconnected; rather, this element allows the developer to catch the event and attempt another action. See the oncallfailure element description for further details.
onhangup This event occurs when a session determines that one side of the call has hung up. A typical use for this handler is to execute any necessary clean-up code. See the onhangup element description for further details.



code samples

<Transfer - method - value - termdigits - maxtime - answeronmedia - playvalue - playrepeat>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="2.0">

  <block>

    <text>
      Preparing to place your call, fruitcake.
    </text>

    <transfer method="bridged" value="tel:1112223333"
      termdigits="*" maxtime="30s" answeronmedia="false"
      playvalue="ringtone.wav" playrepeat="true"/>


    <onmaxtime>
      <text>
        Sorry there, holmes.
        You hit max time for the call, and were disconnected.
      </text>
    </onmaxtime>

    <ontermdigit value="*">
      <text>
        You must have terminated the conference by pressing the star key.
      </text>
    </ontermdigit>

  </block>
</callxml>



additional links

none


  ANNOTATIONS: EXISTING POSTS
andymoe
6/4/2007 7:04 AM (EDT)
I'm wondering why 'onanswer' event handler is not available for this element
VoxeoDante
6/4/2007 12:19 PM (EDT)
Hello,

The <transfer> tag it is a blocking element.  The action will either succeed of fail.  Upon success, execution is will essentially freeze until <transfer> is complete.

Furthermore, the call-legs are bridged immediately, so you will not have individual control of each.  If you would like to do things such as play an audio message to either call-leg when the called party answers, you should use a standard "parent/child session" method to bridge the inbound and outbound calls.  You can find a handy example of this in the "Call Bridging" tutorial at 'http://docs.voxeo.com/callxml/2.0/t_8cxml.htm'.

I hope this helps to explain. If further questions arise, please do let us know.


All the Best,

Dante Vitulano

login


© 2011 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site