<transfer>

<transfer
    name="string"
    expr="ECMAScript_Expression"
    cond="ECMAScript_Expression"
    dest="URI"
    destexpr="ECMAScript_Expression"
    bridge="boolean"
    type="bridge" | "blind" | "consultation"
    method="string"
    connecttimeout="time_interval"
    maxtime="time_interval"
    transferaudio="URI"
    analysis="boolean"
    connectwhen="analysis" | "answered" | "immediate"
    detectansweringmachine="boolean"
    aai="string"
    aaiexpr="ECMAScript_Expression"
    signalvar="ECMAScript_Object"
    consultexpr="ECMAScript_Expression">
  child elements
</transfer>

name

The name of this transfer.  This variable stores the result of the transfer, and can be referenced anywhere within the transfer's form.  Optional.  (Defaults to an inaccessible internal variable.)

• busy - The endpoint refused the call.
• noanswer - There was no answer within the time specified by the connecttimeout attribute.
• network_busy - Some intermediate network refused the call.
• near_end_disconnect - The call was completed and was terminated by the caller.
• far_end_disconnect - The call was completed and was terminated by the called party.
• network_disconnect - The call was completed and was terminated by the network.
• maxtime_disconnect - The call duration exceeded the value of the maxtime attribute and was terminated by the platform.
• far_end_machine - The platform detected an answering machine picking up, and immediately disconnected the call (only possible if the analysis and detectansweringmachine attributes are set to true).
• far_end_fax - The platform detected a fax machine picking up, and immediately disconnected the call (only possible if the analysis attribute is set to true).
• rejected - This result is only possible with multiphase transfers (i.e. when consultexpr is set); this result occurs when the child script exits without setting accepttransfer (or with it set to a value other than true).
• not_allowed - The document is not allowed to use the <transfer> element.
• unknown - The outcome of the transfer is unknown.

Note: If the transfer request is unacceptable and the transfer is not initiated at all, the transfer variable will not be set and the platform will throw an error, instead.

expr

An ECMAScript expression to be evaluated and used as the initial value of this transfer.  This transfer will be visited only if the expression evaluates to undefined.  Optional. (Defaults to undefined.)

cond

An ECMAScript expression to be evaluated and used as a boolean condition.  This transfer will be visited only if the expression evaluates to true.  Optional. (Defaults to true.)

dest

The URI of the destination phone.  Optional.  Exactly one of dest and destexpr may be specified.

In a PSTN environment, the format is:

• tel:number
• phone:number

In a VoIP environment, the format to call a phone number through an IP/PSTN gateway is:

• tel:number
• phone:number
• sip:number@gateway[:port]
• h323:number@gateway[:port]

In a VoIP environment, the format to call a VoIP endpoint device directly is:

• sip:[user@]host[:port]
• h323:[user@]host[:port]

In any of the above, forward slashes can optionally follow the protocol, although that is not standard for telephone URIs.  For example, tel://..., phone://..., etc.

In any of the above, number can be prefixed with +1.  For example: tel:+14167360905.  In any of the above, VoiceGenie supports two types of special syntax within the number:

• xextension - This can be used at the end of the phone number to specify an extension number (ex. tel:4167360905x111).
• commas (",") - These can be used within the phone number to generate pauses when the number is being dialed.

The format is extended to adhere to RFC 2806. This includes support for ";postd=extension" and the "p" (pause) wait-character within number.  Please see the System Reference Guide for complete details and limitations.  Note that the older format (proprietary syntax for extensions and pauses, above) is still supported, as long as it is not used in combination with syntax from the newer RFC 2806 format within a single address.  

destexpr

An ECMAScript expression to be evaluated and used as the URI of the destination phone, as documented under dest, above.  Optional.  Exactly one of dest and destexpr may be specified.

bridge

Determines what to do after the call is connected. Refer to the element description, above, for explanations of the 3 types of transfer. Optional.

• true - bridged transfer
• false - either blind or consultation transfer (depending on value of type attribute)

type

Specifies the transfer behaviour (from the VoiceXML application's perspective). Optional.

• bridge - The application will never be detached from the original inbound call, unless the original caller disconnects.  The control of the call will always return to the application when the transfer ends, regardless of the result.  Note: This type means bridge="true" (the application or default bridge setting will be overridden, if necessary).
• blind - The application will be detached from the original inbound call as soon as the transfer is initiated. That is, after the transfer request is made to the telephony network (assuming the request is acceptable), the platform throws a connection.disconnect.transfer/ telephone.disconnect.transfer, and the application detaches from the call and is unable to detect the progress or outcome of the transfer attempt. However, if the transfer request is unacceptable and the transfer is not initiated at all, the application will retain control of the call, and error events (ex. error.connection.baddestination/ error.telephone.baddestination) will be thrown. Note: This type means bridge="false" (the application or default bridge setting will be overridden, if necessary).
• consultation - The application will be detached from the original inbound call only if the transfer attempt finishes successfully.  That is, after the transfer request is made to the telephony network (assuming the request is acceptable), if the caller is successfully connected to the third party, the platform throws a connection.disconnect.transfer, and the application detaches from the call.  If the transfer attempt fails, the application will retain control of the call, and the failure reason will be handled either by assigning a value to the transfer name variable or by throwing an event.  And, as with blind transfers, if the transfer request is unacceptable and the transfer is not initiated at all, the application will retain control of the call, and error events (ex. error.connection.baddestination) will be thrown.  Note: This type means bridge="false" (the application or default bridge setting will be overridden, if necessary).

If bridge="true", this attribute defaults to bridge.  If bridge="false", it defaults to blind.
In v7.0+, if the <vxml> version attribute is set to 2.1, both bridge and type attributes cannot be specified at the same time.  (The default value will be used for whichever attribute is not specified.)

method

The transfer method to be used by the call manager; this is the actual mechanism to be used to perform the transfer at the telephony layer.

All platforms support the "bridge" method.  If additional methods are supported (and configured) as well, they will be listed under the following parameters in the Call Manager configuration:

• dlgc.transfermethods
• brooktrout.transfermethods
• BLIND_TRANSFER_TYPE
• sip.transfermethods
• h323.transfermethods

The value is not case-sensitive.  The empty string is treated as the default.

Optional.  (Default value depends on Call Manager configuration.)

A platform extension.

connecttimeout

The time to wait while trying to connect the call before returning, and setting the transfer variable to 'noanswer'. Minimum value allowed is 5s.  This attribute only affects the VoiceXML application behaviour in the cases of bridge or consultation transfers.  Optional. (Defaults to 30s.)

maxtime

The maximum time that the call is allowed to last. Minimum value is 30 seconds; maximum is one week.  A value of 0 represents no limit.  This attribute only applies for bridge transfers.  Optional.  (Defaults to 0.)

transferaudio

The URI of an audio file to be played while connecting the call.  Transfer audio cannot be played if connectwhen="immediate"; in this case, network ringing will be heard instead.  Optional.

analysis

Specifies whether or not the platform is enabled to detect who/what answered the call.  Optional.

If this attribute is set to true, and the call is answered, the behaviour is as follows:

• If the platform detects an answering machine, the behaviour depends on the value of the detectansweringmachine attribute, below.
• If the platform detects a fax machine, the transfer will be immediately disconnected, and the transfer variable will be set to 'far_end_fax'.
• If the platform detects that a human answered, the original caller will be connected to the called endpoint, and the transfer variable will be set when the call is disconnected (the value will depend on how the connection is terminated).

If this attribute is set to false, and the call is answered, the platform will not be able to differentiate between an answering machine, fax machine, or human.  The original caller will be connected to the called endpoint in all three cases, and the transfer variable will be set when the call is disconnected (the value will depend on how the connection is terminated).

Note that in some telephony environments, analysis must be set to true for the platform to be able to detect a busy tone.  In other environments (ex. SIP), the platform will be able to detect a busy tone regardless of the analysis setting.  For calls that are unsuccessful for other reasons, the platform will generally be able to report the failure reasons (ex. noanswer), regardless of the analysis setting.

(Defaults to true)

A platform extension.

connectwhen

Controls when the call is connected to the end point.   See Limitation, below.  Optional.

• analysis - connection is made after call is connected and analysis is completed (only applies when analysis="true")
• answered - connection is made after call is picked up
• immediate - connection is made immediately; user hears the ringing

If transferaudio is specified, this attribute defaults to answered. Otherwise, it defaults to immediate.

A platform extension.

detectansweringmachine

This feature is only supported if analysis="true".  If this attribute is set to true, the transfer will be immediately disconnected on detecting an answering machine, and the transfer variable will be set to 'far_end_machine'.  If this attribute is set to false, the original caller will be connected to the answering machine, and the transfer variable will be set when the call is disconnected (the value will depend on how the connection is terminated).  Optional.  (Defaults to false.)

A platform extension.

aai

A string containing Application-to-Application Information (AAI) data to be sent to an application on the far-end.

For example, if a <transfer> (or <call>), with aai set, is used to call another VoiceXML application (and if the network configuration supports the transmission of AAI data), then the AAI data string will be available in the session variable session.connection.aai in the called application.

AAI data is a string of limited length which is sent over the PSTN.  If the intent is to have the called party access this string, they must have a device that is capable of retrieving the sent data.  If you are looking for a way to allow the called party to access application data (possibly by hearing a message or audio file), try using VoiceGenie's call control features, instead.

Note: If neither aai nor aaiexpr is specified, VoiceGenie will send the aai data from the inbound line (i.e. session.connection.aai).  If there is no data from the inbound line (i.e. the session variable is undefined), then no AAI data is sent.

aaiexpr

An ECMAScript expression evaluating to the Application-to-Application Information (AAI) data string, to be sent to an application on the far-end, as documented under aai, above.

Note: If neither aai nor aaiexpr is specified, VoiceGenie will send the aai data from the inbound line (i.e. session.connection.aai).  If there is no data from the inbound line (i.e. the session variable is undefined), then no AAI data is sent.

signalvar

Sends an ECMAScript object containing a variable number of parameters associated with the call with the call request.  Optional.

Note: To make use of these outgoing signaling variables, the called party must have a switch that is capable of delivering the information.

A platform extension.

consultexpr

Use of this attribute specifies that the transfer should be multiphase.

Contains an ECMAScript expression evaluating to the URI (possibly including a #<form_id> fragment) of the child VoiceXML page that will be played for the callee at the beginning of the multiphase transfer.

If this attribute is empty ("") or set to the empty string literal ("''"), the attribute will be ignored and the transfer will not be multiphase. If this attribute is non-empty and the expression evaluates to an empty string (''), then the current VoiceXML page will be used.

For a list of transfer methods that this feature is supported with, please see the VoiceGenie Media Platform User's Guide (look for the section "Whisper Transfer").  Note that it is not supported with:

• TC1, TC2, TC3
• unsupervised hookflash
• SIP REFER
• H.450.2

Note: When performing a multiphase transfer with bridge="false", the type attribute should always be set to "consultation".  Setting the type to "blind" (or "unsupervised") does not make sense.

Optional.

A platform extension.

<name>$.duration

The duration of the call in seconds.  The duration is 0 if a call attempt was terminated by the caller (using a DTMF command) prior to being answered.  Note that in the case where the caller hangs up before the transfer is connected, the duration is timed from when the transfer request was made, and therefore will be greater than 0.

<name>$.inputmode

The mode (dtmf) of the input, if input terminated the transfer; otherwise, undefined.  Currently, only dtmf termination is supported (no voice termination).

<name>$.disconnect_reason

(VoiceGenie extension) The disconnect reason (ISDN disconnect cause code) passed back from the call manager after the outbound bridge transfer disconnects.

<name>$.result.<var_i>

(VoiceGenie extension) These only exist with multiphase transfers (i.e. when consultexpr is set); they are used to access any variables returned from the child script by <exit namelist="<var1> <var2> .../>.

<name>$.markname

(VoiceXML 2.1 feature) The name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred.  If no mark was executed, this variable is undefined.  This is only meaningful when the <transfer>'s prompts contain <mark>s.

<name>$.marktime

(VoiceXML 2.1 feature) The number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred.  If no mark was executed, this variable is undefined.  This is only meaningful when the <transfer>'s prompts contain <mark>s.

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <transfer name="newcall" dest="tel:4167360905x111" bridge="true">
      <filled>
        Your call lasted <value expr="newcall$.duration"/> seconds.
        <if cond="newcall == 'busy'">
          All our customer care agents are currently busy.
          Please call back later.
        </if>
      </filled>
    </transfer>
  </form>
</vxml>