<transfer>

<transfer
    name="string"
    expr="ECMAScript_Expression"
    cond="ECMAScript_Expression"
    dest="URI"
    destexpr="ECMAScript_Expression"
    bridge="boolean"
    type="bridge" | "blind" | "consultation" | "local" | "network" | "unsupervised" | "supervised"
    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>

Attribute

Description

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).
• reject - 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. Exactly one of dest and destexpr may be specified.

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

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)

In standards compliance mode, this attribute defaults to false. If the com.voicegenie.STRICTCONFORMANCE property is set to FALSE, it defaults to true.

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.)

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/ telephone.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/ error.telephone.baddestination) will be thrown. Note: This type means bridge="false" (the application or default bridge setting will be overridden, if necessary).

The following values are deprecated, and "bridge"/"blind"/"consultation" should be used instead, wherever possible.

• local -
  • If bridge="true", the local type has the same behaviour as type="bridge". If bridge="false", the local type will be overridden with type="blind", instead.
    
• network -
  • Use the method attribute instead, to specify Conference and Transfer. If type="network" is used, it will just be overridden with type="bridge" (if bridge="true"), or type="blind" (if bridge="false").
    
• unsupervised:
  • If bridge="false", the unsupervised type has the same behaviour as type="blind". If bridge="true", the unsupervised type will be overridden with type="bridge", instead.
    
• supervised:
  • If bridge="false", the supervised type has the same behaviour as type="consultation". If bridge="true", the supervised type will be overridden with type="bridge", instead.

If bridge="true", this attribute defaults to bridge. If bridge="false", it defaults to blind.
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 SIP stack; this is the actual mechanism to be used to perform the transfer at the telephony layer. The Dialogic IP Media Server supports bridged transfers.

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 applies for 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 for unsuccessful calls, the platform will generally be able to report the failure reasons (ex. busy, noanswer), regardless of the analysis setting.

In standards compliance mode, this attribute defaults to true. If the com.voicegenie.STRICTCONFORMANCE property is set to FALSE, it defaults to false.

connectwhen

Controls when the call is connected to the end point. See Limitations 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.

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.)

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.

Note: If neither aai nor aaiexpr is specified, the IP Media Server 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, the IP Media Server 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.

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.

Supported with:

• bridge
• consultative hookflash
• consultative SIP REFER
• consultative H.450.2

Unsupported with:

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

(In addition, this feature should work with RLT/TBCT/ECT, but those have not been tested.)

Note: When performing a multiphase transfer with bridge="false", type="supervised" should always be set (unsupervised does not make sense).

longdigit

To ensure a call transfer can be terminated with a long DTMF using the new “longdigit” attribute of <transfer> as well as using DTMF grammar under <transfer>.

requri

The SIP URI to be used as the Request-URI in an outbound INVITE. The value must be compliant with the grammar for a SIP URI. If this attribute is not present, the Request-URI will have the same value as the To header. The To URI value is determined by the dest attribute. This attribute and the requriexpr attribute enable you to route outbound calls to a proxy. The proxy will modify the request as needed based on the URI parameters placed in the INVITE and relevant network and subscriber data.

requriexpr

An ECMAscript expression that evaluates to a SIP URI.

video

It is possible to make an outbound call which supports video. The video attribute is added as an extension to specify whether the transfer should be video-enabled or not.

Whether the transfer should be video-enabled or not. Valid values are:

• allow (default)
• suppress

Setting the video attribute to “allow” does not guarantee that the established transfer will have a video stream. It is up to the capabilities and configuration of the underlying platform. Setting the attribute to “suppress” will guarantee that only an audio stream will be available. In the absence of this attribute, video streams will be allowed.

Property

Description

<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. It is an ECMAScript number.

<name>$.inputmode

The mode (dtmf) of the input, if input terminated the transfer; otherwise, undefined. Currently, only dtmf termination is supported (no voice termination).
In standards compliance mode, the value will be "dtmf" (lowercase). If the com.voicegenie.STRICTCONFORMANCE property is set to FALSE, it will be "DTMF" (uppercase).

<name>$.utterance

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

<name>$.disconnect_reason

(extension) The disconnect reason passed back from the SIP stack after the outbound bridge transfer disconnects. .

<name>$.result.<var_i>

(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.

• audio


• audio+video

"Audio" means that only an audio stream was established. "Audio+video" means that both an audio and a video stream were established. In the latter case, the order in which the stream names appear in the variable's value is fixed. Therefore, VoiceXML applications do not have to anticipate a value of "video+audio". The following example illustrates how this feature can be used in a VoiceXML application:

<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">

<form>
<transfer name="xfer" dest="sip:1234@192.168.0.142" video="suppress"
type="bridge">
<prompt>Please wait while I make a call</prompt>
<filled>
<if cond="xfer == ‘far_end_disconnect'">
<if cond="xfer$.media == ‘audio'">
<log>Audio stream was used</log>
<elseif cond="xfer$.media == ‘audio+video'"/>
<log>Video stream shouldn’t have been used!</log>
<else/>
<log>Invalid media shadow variable value!</log>
</if>
</if>
</filled>
</transfer>
</form>

</vxml>

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