callxml elements - transfer

CallXML 2.0 Development Guide

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

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: 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

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

<?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