callxml elements - transfer

CallXML 3.0 Development Guide

<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
id	Data Type: (element id)	Default: none - attribute is optional
	The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the `<on>` element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur.
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".
test	Data Type: CDATA	Default: Optional
	The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document.
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
value-is	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.

code samples

<3.0 transfer-method-value-termdigits-maxtime-answeronmedia-playvalue-playrepeat>

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

<callxml version="3.0">

<do>

<prompt value="Preparing to place your call, fruitcake"/>

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

<on event="maxtime">
<log> *** MAXTIME EVENT DETECTED ***</log>
<say>
You hit max time for the call, and were disconnected.
</say>
</on>

<on event="callfailure:hangup">
<log> *** HANGUP EVENT DETECTED ***</log>
</on>

<on event="termdigit:1">
<log> *** TERMDIGIT PRESSED BY USER ***</log>
<say>
you must have pressed 1 to end the call.
</say>
</on>

<on event="callfailure:unreachable">
<log>*** UNREACHABLE EVENT DETECTED ***</log>
<say>
the called number returned an un reachable event.
</say>
</on>

<on event="callfailure:busy">
<log>*** BUSY EVENT DETECTED ***</log>
<say>
the number that you dialed is busy.
</say>
</on>







<on event="callfailure">
<log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>
</on>
</do>

</callxml>

<3.0 transfer - valueis>

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

<callxml version="3.0">

<do label="Fruit">

<prompt value="Preparing to place your call, fruitcake"/>


<transfer method="bridged" value="tel:4072223333"
maxtime="30s" playvalue="ringtone.wav"
value-is="Cake">


<transfer method="bridged" value="tel:4072223333"
maxtime="30s" playvalue="ringtone.wav"
value-is-not="Fruit">


<transfer method="bridged" value="tel:4072223333"
maxtime="30s" playvalue="ringtone.wav"
value-is="Fruit">

<on event="maxtime">
<log> *** MAXTIME EVENT DETECTED ***</log>
<say>
You hit max time for the call, and were disconnected.
</say>
</on>

<on event="callfailure:hangup">
<log> *** HANGUP EVENT DETECTED ***</log>
</on>

<on event="termdigit:1">
<log> *** TERMDIGIT PRESSED BY USER ***</log>
<say>
you must have pressed 1 to end the call.
</say>
</on>

<on event="callfailure:unreachable">
<log>*** UNREACHABLE EVENT DETECTED ***</log>
<say>
the called number returned an un reachable event.
</say>
</on>

<on event="callfailure:busy">
<log>*** BUSY EVENT DETECTED ***</log>
<say>
the number that you dialed is busy.
</say>
</on>







<on event="callfailure">
<log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>
</on>

</do>
</callxml>

<3.0 transfer test>

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

<callxml version="3.0">

<do label="Fruit">

<prompt value="Preparing to place your call, fruitcake"/>


<transfer method="bridged" value="tel:4072223333"
maxtime="30s" playvalue="ringtone.wav"
test="1=2">


<transfer method="bridged" value="tel:4072223333"
maxtime="30s" playvalue="ringtone.wav"
test="1!=1">


<transfer method="bridged" value="tel:4072223333"
maxtime="30s" playvalue="ringtone.wav"
test="1=1">

<on event="maxtime">
<log> *** MAXTIME EVENT DETECTED ***</log>
<say>
You hit max time for the call, and were disconnected.
</say>
</on>

<on event="callfailure:hangup">
<log> *** HANGUP EVENT DETECTED ***</log>
</on>

<on event="termdigit:1">
<log> *** TERMDIGIT PRESSED BY USER ***</log>
<say>
you must have pressed 1 to end the call.
</say>
</on>

<on event="callfailure:unreachable">
<log>*** UNREACHABLE EVENT DETECTED ***</log>
<say>
the called number returned an un reachable event.
</say>
</on>

<on event="callfailure:busy">
<log>*** BUSY EVENT DETECTED ***</log>
<say>
the number that you dialed is busy.
</say>
</on>







<on event="callfailure">
<log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>
</on>

</do>
</callxml>

additional links

none

ANNOTATIONS: EXISTING POSTS

sgaitskell

3/1/2007 3:02 AM (EST)

There is no documentation on the valid values for the Method attribute.

It is only from the forums that you find out about bridge, blind and refer.

jbassett

3/1/2007 5:00 AM (EST)

Hello,

I reviewed the section you referred to, and I understand your concern. The only thing we illustrate is that the default is set to "bridged" because that is all that the Voxeo network supports. I will pass your suggestion of listing all options (even the unsupported ones).

Thanks
Jesse Bassett
Voxeo Support