# <transfer>

Description

Transfers the caller to another phone number. There are 3 types of transfer:

- bridged transfer - The caller returns to the application after the transfer ends, i.e., after disconnecting from the third party.
- blind transfer - As soon as the transfer is initiated, the application is detached from the call, and has no way of knowing if the transfer attempt was successful or not. (However, if the transfer is not initiated at all, due to errors, the caller remains in the application, where the errors can be handled.)
- consultation transfer - Note that this functionality is not currently supported in IP Media Server release 2.4.
  Once the transfer attempt finishes successfully, i.e., the caller is connected to the third party, the application is detached from the call. (However, if the transfer either is not initiated at all, due to errors, or does not finish successfully, the caller remains in the application, where the errors/result can be handled.)

Syntax

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

Attributes

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. Optional. Exactly one of aai and aaiexpr may be specified.
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. Optional. Exactly one of aai and aaiexpr may be specified.
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. See RTP Codec Selection with <transfer/> for additional information.

Attribute Notes

- An `error` event may be thrown if a reserved ECMAScript word is used as the `name`.
- An `error.badfetch` event is thrown if more or less than one of `dest` and `destexpr` are specified, or if more than one of `aai` and `aaiexpr` are specified.

Shadow Variables

For each `<transfer>` whose `name` attribute is set to `<name>`, there is a shadow variable `<name>$` (in the same scope as the transfer name variable), containing the following properties after the transfer completes:

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.<vari> | (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.
<name>$.media | The media stream connections that are established as a result of a successful transfer. This can take on the following values: 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>

Shadow Variable Notes

- When any shadow variable is not set, its value will be ECMAScript `undefined`.

Events Thrown

The following events can be thrown during the execution of the `<transfer>` element:

- connection.disconnect.hangup/ telephone.disconnect.hangup
- connection.disconnect.transfer/ telephone.disconnect.transfer
- error.connection.baddestination/ error.telephone.baddestination
- error.connection.noauthorization/ error.telephone.noauthorization
- error.connection.nolicense/ error.telephone.nolicense
- error.connection.noresource/ error.telephone.noresource
- error.connection.noroute/ error.telephone.noroute
- error.connection.<protocol>.<nnn>
- error.unsupported.transfer.bridge
- error.unsupported.transfer.blind
- error.unsupported.transfer.consultation
- error.unsupported.uri

Event Notes

- When a `connection.disconnect.hangup`/ `telephone.disconnect.hangup` is caught, the following anonymous variable is available within the scope of the `<catch>` element: _disconnect_reason

Parents

<form>

Children

<audio>, <catch>, <dtmf>, <error>, <filled>, <grammar>, <help>, <noinput>, <nomatch>, <prompt>, <property>, <value>, #PCDATA

Extensions

- Added return values for transfer variable: 'not_allowed', 'far_end_machine', 'far_end_fax', 'reject'.
- Added "local"/"network"/"unsupervised"/"supervised" values for `type` attribute.
- Added `method` attribute.
- Added `analysis` attribute.
- Added `connectwhen` attribute.
- Added `detectansweringmachine` attribute.
- Added `signalvar` attribute.
- Added `consultexpr` attribute.
- Added `<dtmf>` as a child, to be used like `<grammar>`.
- Added `disconnect_reason` and `result.*` shadow variables.
- Added `error.connection.nolicense`/`error.telephone.nolicense` events.

Limitations/Restrictions

- Speech grammars are not supported within `<transfer>`.
- DTMF grammars are fully supported within `<transfer>`. Only dtmf/grammar elements within a `<transfer>` can be used to specify DTMF grammar that will terminate the transfer. DTMF grammars outside of the scope of `<transfer>` are not enabled (as defined in the W3C VoiceXML 2.0 specification).
- While the VoiceGennie browser supports full grammar semantics for terminating an already initiated/established transfer, for prompts that reside in a transfer which are played before the transfer is initiated, the behaviour is slightly different than what the W3C specification suggests. The prompt playback is terminated with the first DTMF digit entered, i.e., regardless of a partial/complete/mis-match. If any DTMF digit is entered during a prompt playback, the VoiceGennie browser interrupts the prompt, ignores the DTMF digit and initiates the transfer. Any additional DTMF digits that come in at this point are subject to proper grammar processing.
- Support is as follows:
  - The pause feature (adding pauses during dialing) is not supported.
  - Non-bridged transfers are only supported if the initial calling device supports them.
  - The analysis attribute is not supported.
- Some notes related to blind transfers:
  - Extension dialing is generally not supported with blind transfers. Adding extra pauses to the dial string (ex. `number,,,extension`) as a workaround to dial extensions will only work for hookflash transfers.
  - `transferaudio` will not play in the case of blind transfers.
- With some call-release technologies, only certain attribute values make sense. For example, currently with some hookflash transfers, only `type="blind"` (or `"unsupervised"`) would make sense. Also, some transfer methods may not be supported for all transfer types, due to the transfer methods' mechanisms.
- See related FAQs.

Example

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