<transfer>

Transfers the caller to another destination.

Attributes

This section describes the attributes you can set for this element.

aai

The aai attribute allows you to specify application-to-application information (AAI)—an ASCII string containing data that is sent to an application on the far-end of a transfer. For example:

<transfer name="TransferToAgent" dest="tel:1234567" aai="caller-ID=12345,product-ID=gizmo,tax-code=CT"/>

If the receiving end is a platform running a VoiceXML application, for example, Voice Platform, it can extract the AAI string using the session.connection.aai session variable.

Note: Support for the aai attribute and the session.connection.aai session variable depends on the underlying audio provider. At present, only the NMS audio provider on ISDN and the SIP audio provider support this feature. See session.connection.aai.

aaiexpr

The aaiexpr attribute specifies an ECMAScript expression that evaluates to the application-to-application information.

bridge

The bridge attribute specifies whether or not the system will remain connected when the caller is speaking with the called party. 

• If the bridge attribute is set to true, the system remains connected for the duration of the call.
• If the bridge attribute is set to false (the default), the call is disconnected and a connection.disconnect.transfer event is thrown as a result.

Note: Although the bridge attribute is supported in Voice Platform, the type attribute (Nuance extension) renders the bridge attribute unnecessary.

connecttimeout

The connecttimeout attribute specifies the amount of time that needs to elapse before a “no answer” response is returned to the caller.

dest

The dest attribute specifies the URI of the transfer destination, for example, a telephone number or an internet protocol (IP) telephone address. Voice Platform supports the tel protocol as described in RFC 2806.

The tel: URI syntax requires you to specify either an absolute telephone number or an exact telephone number. An absolute telephone number consists of a plus sign (+) followed by the country-code, an area code, and a local or main number. An exact telephone number can have any dial prefix, the number that must be dialed to reach an outside line. For example, if your system requires you to dial 9 to access an outside line, and you are in the 650 area code, you could write the same number using either one of the following formats:

• Absolute syntax = tel:+16505559999
• Exact syntax = tel:95559999

Nuance recommends that you use the absolute syntax because it makes VoiceXML more portable, leaving it up to the interpreter to determine how to place a call on a particular telephony network. Using the Voice Browser service telephony properties, you can configure the system to dial absolute and exact numbers the same way.

Voice Platform also supports sip: URIs when running on SIP. The syntax is:

sip:user@hostname[:port]

Where:

• user specifies the called party and is typically (but not always) an extension number. It varies depending on the type and configuration of the gateway.
• hostname and port are the hostname or IP address and port number of the SIP telephony gateway. If unspecified, port is 5060.

For example:

<transfer dest="sip:1234@10.0.00.0:5070"/>

You can also configure a dial plan on the Voice Browser service for sip: URIs with these restrictions: you must specify an absolute URI and include user=phone as part of the destination string. For example:

<transfer dest="sip:+18005551212@10.0.00.0:5070;user=phone"/>

SIP URIs on Windows

The hostname, if used instead of an IP address, must be a fully qualified domain name. For example:

<transfer dest="sip:1234@Gateway1.domain.com:5070"/>

If you add the environment variable LOCALDOMAIN and set it to the domain Voice Platform is running on (nuance.com), then you just have to specify the hostname in the SIP URI, for example, Gateway1. You don’t have to specify a fully qualified domain name if you use the IP address.

destexpr

The destexpr attribute specifies an ECMAScript expression that evaluates to the URI of the transfer destination. 

devicedetection

The devicedetection attribute is a Nuance extension that specifies the list of devices or tones that the system attempts to detect during a transfer. Supported devices are:

• answering-machine—Detects an answering machine.
• fax—Detects a fax machine.
• sit—Detects a special information tone, a three-beep signal heard at the beginning of a recorded announcement. The variation in the tones indicates why the call could not be completed.
• tty—Detects a teletypewriter device.
• all—Detects all supported devices.

If a specified device is detected, the transfer form-item variable is filled with the appropriate value and the transfer terminates. See the name attribute for details.

Please note:

• Currently, this attribute applies only for bridged transfers.
• You must have already enabled Tone detection by setting server.toneDetector.configFile to $NSSSVRSDK/config/tones.all, the location of the North American tones library, on the Nuance Speech Server in the Management Station.
• On SIP, you must also enable the Telephony Session service in the Management Station for audio forking. See Configuration settings that affect audio routing for more information.

farenddialog

The farenddialog attribute is a Nuance extension that allows you to specify the VoiceXML dialog to conduct with the called party before connecting the transfer. The VoiceXML dialog returns a Boolean which specifies whether or not to connect the caller to the called party.

• If the return variable is true, the call is connected.
• If the return variable is false, the callee is disconnected and the transfer form-item variable will be filled with the following value: refused. See the name attribute for details.

This attribute is supported only on bridged and consultation transfers. However, if you specify the farenddialog attribute on a blind transfer, the audio provider will simply ignore it and not throw an exception.

Note that the caller hears nothing while Voice Platform is interacting with the called party.

farenddialogexpr

The farenddialog attribute is a Nuance extension that specifies an ECMAScript expression that evaluates to the URI of the dialog to conduct with the called party before connecting the transfer.

farendhotword

The farendhotword attribute is a Nuance extension that specifies which end of a bridged transfer is to be monitored for a hot word. The attribute takes a boolean value.

Voice Platform can monitor the near end or the far end of the call for the hot word. The near end is from the caller (party A) to Voice Platform. The far end is from Voice Platform to the called party (party C). If no value is specified, Voice Platform monitors party A by default. If set to true, Voice Platform monitors party C.

Please note:

• To implement hot word recognition in bridged transfers, you must include a hot word grammar within the <transfer>. See Implementing the hot word within a transfer for more information.
• On SIP deployments, you must configure Voice Platform to support audio forking to use hot word in bridged transfers. See Understanding SIP audio routing for more information.

Note: Enabling far-end hot word disables warningaudio.

localuri

The localuri attribute is a Nuance extension that allows you to specify the local URI to use on a transfer attempt.

localuriexpr

The localuriexpr attribute is a Nuance extension that specifies an ECMAScript expression that evaluates to the local URI to use on a transfer attempt.

maxtime

The maxtime attribute specifies the maximum amount of time bridged transfer calls can last. The default is 0, meaning no limit. 

transferaudio

The transferaudio attribute specifies the URL of a customized audio file to play during a transfer. For example:

<transfer transferaudio="http://my-machine/vxml/myprompt.wav"/>

If the audio file is not found, for example, it doesn’t exist or the URL is specified incorrectly, the caller hears silence. If the transferaudio attribute is not specified, the Voice Browser service plays a default file which contains ringback tones.

See <audio> for supported formats.

type

The type attribute, implemented as a Nuance extension in VoiceXML 2.0, is now compliant with VoiceXML 2.1 specifications.

This attribute specifies the type of transfer to perform.

• Blind—During a blind transfer, the application connects the caller to the called party and drops the connection. Blind transfers do not monitor call outcomes. The syntax is:

<transfer...>

<transfer type="blind"...> 

<transfer bridge="false">

• Bridge—During a bridge transfer, the application connects the caller to the called party and stays connected for the duration of the transferred call. The syntax is:

<transfer type="bridge"...>

<transfer bridge="true"...>  

• Consultation—During a consultation transfer, the application attempts to connect the caller to the called party. If the attempt fails, document interpretation proceeds with the caller. If the attempt succeeds, the application completes the transfer and disconnects from the call. The syntax is:

<transfer type="consultation"...>

• Conditional—This Nuance extension is supported for compatibility with previous Voice Platform releases. During a conditional transfer, the application waits to hear a ring before completing the transfer. If the attempt fails, document interpretation proceeds with the caller. If the attempt succeeds, the application completes the transfer and disconnects from the call. The syntax is:

<transfer type="conditional"...>

Conditional vs. consultation

This table summarizes the major differences between conditional and consultation transfers:

Type	Transfer on	Far-end dialog	Notes
Conditional	Ring	Not supported	Nuance extension
Consultation	Connect	Supported	VoiceXML 2.1-compliant

If the selected audio provider does not support the requested transfer type, an event will be generated. See Event types for details.

warningaudio

The warningaudio attribute specifies the URL of an audio file to play when the warningtime fires. This attribute has no effect unless the maximum call duration (maxtime) and warningtime have been set.

Note: Enabling farendhotword disables warningaudio.

warningtime

The warningtime attribute specifies the amount of time prior to maxtime when the warningaudio prompt is played. For example, if maxtime is set to 100s and warningtime is set to 10s, then the warning prompt will fire 90s into the call. This attribute has no effect unless the maximum call duration (maxtime) and warningaudio have been set.

Form item attributes

Being a form item, the <transfer> element also supports the form item attributes listed in this section.

cond

The cond attribute specifies a Boolean expression. The expression must evaluate to true before the form item is available for selection within the Form Interpretation Algorithm (FIA).

expr

The expr attribute specifies the initial value of the form item variable. The default value of the expr attribute is undefined. If you set the attribute to a value other than the default, you must clear this value before the content of the form item element can be executed.

name

The name attribute specifies the name of the form item's guard variable. The Form Interpretation Algorithm (FIA) initializes this variable with the value specified by the expr attribute. If the form item comes up for selection at a later time, it will be populated by the pre-defined type for that element. Note that the resulting value is a call status code.

This table lists the possible call status code values:

Nuance also supports the following values:

• far_end_answering-machine
• far_end_fax
• far_end_sit
• far_end_tty
• refused

These values are only returned if the corresponding device (answering-machine, fax, tty, and so on...) is specified by the devicedetection attribute and detected as the callee (party C).

Note: The refused value is only returned if the VoiceXML dialog specified using the farenddialog or farenddialogexpr attributes returns false (signaling that the callee refused to receive the call).

An undefined result

The transfer variable may remain undefined for many different reasons. When this happens, you can deduce the exact cause from the event thrown.

The table below summarizes the meaning of events thrown for undefined transfers:

Event thrown	Description
connection.disconnect.hangup	The caller hung up before the transfer took place.
connection.disconnect.transfer	The transfer completed, and the session was terminated.
error.connection.baddestination	The destination URI was malformed, or referred to a non-valid destination. The destination is specified in the dest or destexpr attribute.
error.connection.noauthorization	Transfers are disabled in the Voice Browser service.
error.connection.noresource	Sufficient resources to place the call were not available.
error.unsupported.transfer.blind	The system is not configured to support blind transfers. To fix this problem, in the Management Station go to the Properties tab set of the Voice Browser service. In the Telephony tab, check the Enable call transfers check box.

Children

• Parsed character data
• <audio>
• <catch>
• <enumerate>
• <error>
• <filled>
• <grammar>
• <help>
• <noinput>
• <nomatch>
• <prompt>
• <property>
• <value>

Parents

• <form>

Sample code

<form>

    <var name="mydur" expr="0"/>

    <transfer name="mycall" dest="tel:+18005551234"

        connecttimeout="30s" type="bridge">

        <filled>

            <assign name="mydur" expr="mycall$.duration"/>

            <if cond="mycall == 'busy'">

                <prompt> Sorry, our lines are busy. Please try

                    again later.</prompt>

            <elseif cond="mycall == 'noanswer'"/>

                <prompt> Sorry, our business hours are 9 am to 7 pm,

                    monday through friday</prompt>

            </if>

        </filled>

    </transfer>

</form>