<transfer>
Transfers the user's call to a third party at another destination.
Syntax
<transfer
name="string"
expr="js_expression"
cond="js_expression"
dest="URI"
destexpr="js_expression"
connecttimeout="time_interval"
maxtime="time_interval"
bevocal:maxtimeexpr="js_expression"
bridge="boolean"
bevocal:type="blind"|"bridge"|"supervised"
type="blind"|"bridge"|"consultation"
transferaudio="URI"
aai="string"
aaiexpr="js_expression"
>
Child Elements
</transfer>
Description
Input item for transferring the user to another phone number. The transfer may be done in one of three ways:
| Transfer Method |
Description |
Bridge transfer
|
The current session with the interpreter resumes after the call with the third party completes.
|
Blind transfer
|
The current session terminates as soon as it starts the transfer, regardless of the success of the transfer.
|
Supervised or consultation transfer
|
The current session terminates as soon as the transfer successfully connects the outbound call. If the transfer is unsuccessful, control returns to the application.
|
Note: To use blind or supervised transfers, contact BeVocal Customer Support.
Only one outbound call can be in progress at a given time. The call placed by one <transfer> or <bevocal:dial> tag must be terminated before another <transfer> or <bevocal:dial> tag can be executed.
Café customers can use a <transfer> tag to place local and long-distance calls only; international calls are not allowed. (Hosting customers are allowed to make international calls.)
During execution of the <transfer> element, the user and the called third party talk to each other. The application is quiet. No universal grammars or grammars in higher scopes are active.
During a bridge transfer, if the <transfer> element includes any child grammars, the application listens to the user. If a user utterance matches a child grammar, the transfer is terminated and the input variable is set to the status near_end_disconnect. The bevocal.hotwordmin and bevocal.hotwordmax properties specify the minimum and maximum time duration, respectively, for an utterance that can terminate the call.
During execution of the <transfer> element, the bargein type is always hotword. That is, the interpreter ignores the value of the bargeintype property and the value of the bargeintype attribute of any enclosed <prompt> element.
The application ignores all speech and DTMF signals from the called third party.
| Attribute |
Description |
name
|
Name of the input variable used to store the result of the transfer. The variable name may not be a JavaScript reserved keyword.
The input variable has dialog (form) scope; its name must be unique among all VoiceXML and JavaScript variables within the form's scope.
Possible values for the variable are:
| • | busy--The call was refused by the endpoint (the number was busy). |
| • | noanswer--There was no answer within the time allowed for making the connection. |
| • | network_busy--The call was refused by an intermediate network. |
| • | near_end_disconnect--The call completed because the user hung up or said something that matched a child grammar. |
| • | far_end_disconnect--The call completed because the called third party hung up. |
| • | network_disconnect--The call completed and was terminated by the network. |
| • | maxtime_disconnect--The call was terminated because the maximum time (specified by the maxtime attribute) was exceeded. |
|
expr
|
JavaScript expression that assigns the initial value of the input variable. Optional (default is undefined).
If you set the input variable to a value other than undefined, you'll need to clear it before the <transfer> can execute.
|
cond
|
JavaScript boolean expression that also must evaluate to true for the <transfer> to execute. Optional (default is true).
If not specified, the value of the input variable alone determines whether or not the <transfer> can execute.
|
dest
|
URI of the destination (for example, phone, IP telephony address). Optional (as alternative to destexpr).
You can specify the URI using any of the following formats:
| • | phone://8005551212 |
| • | 800-555-1212 |
| • | phone://800-555-1212 |
| • | tel:800-555-1212 |
| • | tel:800-555-1212;postd=1234 |
This format allows you to specify an extension as post-dial digits (postd). After the call is answered, the specified digits (1234 in this example) are sent to the called third party as DTMF.
| • | sip:+16506414924@fwd.pulver.com |
SIP URIs are specified as:
sip:<destination number>@<domain value>:<port>
where the default port is 5060. SIP URIs are valid only for VoIP calls.
Note: A leading "1" on the phone number is optional and will be ignored.
Note: You must specify one of dest or destexpr, but not both.
|
destexpr
|
JavaScript expression that evaluates to the URI of the destination. Optional (as alternative to dest).
Note: You must specify one of dest or destexpr, but not both.
|
connecttimeout
|
Time to wait for the outbound call to connect before returning a value of noanswer. Optional (default is 20 seconds).
Express the time interval as an unsigned number followed by s for time in seconds; ms for time in milliseconds (the default).
|
maxtime
|
How long the outbound call is allowed to last. Optional:
| • | The default for Café customers is 60 seconds. This is an absolute maximum. If the time specified with this attribute is longer than 60 seconds, the interpreter sets the limit to 60 seconds. |
| • | The default for hosting customers is 0, signifying no limit. |
Express a time interval as an unsigned number followed by s for time in seconds; ms for time in milliseconds (the default).
|
bevocal:maxtimeexpr
|
Extension. A JavaScript expression which resolves to the maxtime value. Optional.
| • | Again, the default for Café customers is 60 seconds. This is an absolute maximum. If the time specified with this attribute is longer than 60 seconds, the interpreter sets the limit to 60 seconds. |
| • | The default for hosting customers is 0, signifying no limit. |
|
bridge
|
Determines whether the current session will resume after the transferred call completed. For more flexibility, you can instead specify a value for the bevocal:type attribute. Optional .
The default value is false. However, to use blind transfers, you must make special arrangements with BeVocal Customer Support.
| • | If you set this attribute to false and arrangements have not been made to support blind transfers, an error.unsupported.transfer.blind event is generated. |
| • | If you set this attribute to false and arrangements have been made to support blind transers, the current session terminates by throwing a transfer event (connection.disconnect.transfer in VoiceXML 2.0, telephone.disconnect.transfer in VoiceXML 1.0) when the transfer is made. |
|
bevocal:type
|
Extension. Determines how much control the platform retains over a transferred call. Optional; if not specified, the platform uses the value of the bridge attribute.
| • | If the value is blind, as soon as the transfer starts, the current VoiceXML session ends and relinquishes control to the outbound call. Even if the transfer does not connect the call, the session is over. |
| • | If the value is bridge, then the current VoiceXML session remains active. At the end of the outbound call, the session returns control to the application to resume processing. |
| • | If the value is supervised, an intermediate path occurs. The current VoiceXML session monitors the progress of the outbound call until it is connected. If the call cannot be connected for some reason such as no answer or line busy, the session remains active and returns control to the application. If the call is connected, then the session ends, just as for a blind transfer. |
You cannot specify both the bridge and bevocal:type attributes.
You can specify either bevocal:type or type, but not both. If you specify both, a parse error is thrown.
Note: To use blind or supervised transfers, please contact BeVocal Customer Support.
|
type
|
Determines how much control the platform retains over a transferred call. Optional. The default is bridge.
If the value is blind, as soon as the transfer starts, the current VoiceXML session ends and relinquishes control to the outbound call. Even if the transfer does not connect the call, the session is over.
If the value is bridge, then the current VoiceXML session remains active. At the end of the outbound call, the session returns control to the application to resume processing.
If the value is consultation, an intermediate path occurs. The current VoiceXML session monitors the progress of the outbound call until it is connected. If the call cannot be connected for some reason such as no answer or line busy, the session remains active and returns control to the application. If the call is connected, then the session ends, just as for a blind transfer.
You cannot specify both the bridge and type attributes.
You can specify either bevocal:type or type, but not both. If you specify both, a parse error is thrown.
Note: To use blind or consultation transfers, please contact BeVocal Customer Support.
|
transferaudio
|
The audio specified by the URI is played while the call connection attempt is in progress.
Note: This attribute is available only for VoIP calls.
|
aai
|
Application-to-application information. A string containing data sent to an application on the far-end, available in the session variable session.connection.aai.
The transmission of aai data may depend upon signaling network gateways and data translation (for example, ISDN to SIP); the status of data sent to a remote site is not known or reported.
On the BeVocal platform, on ISDN calls, the value transmitted is UUI (User-to-User Information)
|
aaiexpr
|
A JavaScript expression yielding the AAI data.
|
Exactly one of dest or destexpr must be specified.
Properties of the Shadow Variable
Corresponding to the input variable name is a "shadow variable" called name$. After the input variable is filled, some additional information is available in the following properties of this shadow variable:
| Property |
Description |
utterance
|
A string representation of the words actually spoken by the user.
|
inputmode
|
The mode in which input was provided, one of voice or dtmf.
|
duration
|
After the transfer is complete, the floating point duration of the call in milliseconds.
|
recording
|
If the recordutterance or bevocal.audio.capture property is set to true and the user's speech matched the field grammar, the recording property contains an audio capture of the user's speech. If no audio is collected, this variable is undefined.
You can send the captured audio to a server using a <data> element. Doing so is useful if you need a record of the user's speech for legal reasons.
|
recordingsize
|
The size of the recording in bytes, or undefined if no audio is collected.
|
recordduration
|
The duration of the recording in milliseconds, or undefined if no audio is collected.
|
For a field whose name is name, you access the property propName of the shadow variable with the syntax:
name$.propName
For example, you access the duration property for a field named services field as:
services$.duration
Events
The following events may be thrown during the execution of a <transfer> element:
| Event |
Description |
connection.disconnect.hangup
|
The user hung up. New in VoiceXML 2.0.
|
connection.disconnect.transfer
|
The user was transferred unconditionally to another line and will not return. New in VoiceXML 2.0.
|
telephone.disconnect.hangup
|
The user hung up. VoiceXML 1.0 only.
|
telephone.disconnect.transfer
|
The user was transferred unconditionally to another line and will not return. VoiceXML 1.0 only.
|
error.badfetch
|
The application specified a value for both bridge and bevocal:type.
|
error.connection.baddestination
|
The destination URI specified by dest or destexpr is not valid. New in VoiceXML 2.0.
|
error.telephone.baddestination
|
The destination URI specified by dest or destexpr is not valid. VoiceXML 1.0 only.
|
error.connection.noauthorization
|
A Café customer attempted to make an international call. (The outbound call is not placed.) New in VoiceXML 2.0.
|
error.telephone.noauthorization
|
A Café customer attempted to make an international call. (The outbound call is not placed.) VoiceXML 1.0 only.
|
error.connection.noresource
|
Another outbound call is already in progress. (A new outbound call is not placed.) New in VoiceXML 2.0.
|
error.telephone.noresource
|
Another outbound call is already in progress. (A new outbound call is not placed.) VoiceXML 1.0 only.
|
|
|
Tip:
|
| • | If a JavaScript expression contains any of the characters "<", ">", or "&", that character must be replaced with the corresponding escape sequence "<", ">", or "&". For more information, see JavaScript Quick Reference. |
|
Usage
See Also
Examples
<?xml version="1.0" ?>
<!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
"http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form id="foo">
<block>
Now taking you to BeVocal Consumer Services.
</block>
<transfer name="services" bridge="true"
connecttimeout="300" dest="phone://14088502255" />
<block>
Welcome back to Cafe!
</block>
</form>
</vxml>
[Show Frames] [FIRST] [PREVIOUS] [NEXT]
