transfer

transfer element

Transfers the caller to the specified telephone number.

Syntax

<transfer
aai = "string"
aaiexpr = "ECMAScript_Expression"
bridgeexpr = "ECMAScript_Expression"
cond = "string"
connecttimeout = "integer"
connecttimeoutexpr = "ECMAScript_Expression"
dest = "string"
destexpr = "ECMAScript_Expression"
expr = "ECMAScript_Expression"
maxtime = "integer"
maxtimeexpr = "ECMAScript_Expression"
name = "string"
transferaudio = "URI"
transferaudioexpr = "ECMAScript_Expression"
type = "string"
/>

Attributes

aai	A string containing data to be sent out-of-band to the application running on the far-end of a blind transfer. Successful transmission of application-to-application (AAI) data may depend upon the capabilities and configuration of signaling network gateways. Success or failure of the transmission of AAI data is unavailable to the sending application. For more information on sending and receiving AAI data, see the AAI tutorial.
aaiexpr	An ECMAScript expression evaluated at run-time that resolves to the string to be sent as AAI data.
bridge	DEPRECATED. Use type instead.
bridgeexpr	An ECMAScript expression that evaluates to the value for the bridge attribute. This attribute is a Tellme extension.
cond	A boolean condition that must also evaluate to true in order for the transfer element to be visited.
connecttimeout	A time designation (see Remarks) specifying the number of seconds (s) or milliseconds (ms) to wait while trying to connect the call during a bridged transfer. If the timeout is exceeded, the value of the name attribute is set to "noanswer" and the contents of the filled element contained by the transfer element is executed. The default value is 30s.
connecttimeoutexpr	An ECMAScript expression that evaluates to the connecttimeout value. This attribute is a Tellme extension.
dest	Required. Specifies the destination of the transfer. The value should be a tel: or sip: URL.
destexpr	An ECMAScript expression that evaluates to a valid destination.
expr	The initial value of the transfer form item variable. If initialized, the transfer element is not visited unless it is subsequently cleared. The default value is undefined.
maxtime	A time designation (see Remarks) specifying the number of seconds (s) or milliseconds (ms) the call is allowed to last during a bridged transfer. "0s" indicates the can be arbitrarily long. Call transfers executed on Tellme Studio are limited to one minute. The default value is 0s.
maxtimeexpr	An ECMAScript expression that evaluates to the maxtime value. This attribute is a Tellme extension.
name	Required. The variable that stores the outcome of a bridged transfer. Possible values include: busyThe party called refused the call. far_end_disconnectThe completed call was terminated by the called party. maxtime_disconnectThe completed call was terminated by the interpreter because the call duration reached the value of the maxtime attribute. near_end_disconnectThe completed call was terminated by the caller. network_busyAn intermediate network refused the call. network_disconnectThe completed call was terminated by the network. noanswerThere was no answer within the time specified by the connecttimeout attribute.
transferaudio	The URL to an audio file played to the caller during a bridged transfer. If the callee picks up, the interpreter terminates playback of the recorded audio immediately. If the end of the audio file is reached and the callee has not yet picked up, the interpreter plays the audio tones from the far end of the call (ringing, busy).
transferaudioexpr	An ECMAScript expression that evaluates to the URL of an audio file played to the caller during a bridged transfer. This attribute is a Tellme extension.
type	A string specifying the type of transfer, which determines whether or not the caller's session with the VoiceXML interpeter resumes after the call initiated by the transfer ends. Unless Tellme Networks has explicitly provisioned your voice application to support blind transfers, the transfer will fail if the attribute is omitted or its value is set to blind. For more information on blind transfers, customers should contact their Tellme Solutions Director. blindThe VoiceXML interpreter performs a blind transfer. Once the caller is handed off to the network, the caller's session with the VoiceXML application cannot be resumed. The VoiceXML interpreter throws a connection.disconnect.transfer event to the VoiceXML application. bridgeThe original caller resumes her session with the VoiceXML application that executed the transfer once the call initiated by the transfer terminates.

Shadow variables

The transfer element exposes the following shadow variables.

name$.duration	The duration of the bridged transfer in seconds. If the call is not completed, the value is 0.
name$.inputmode	The input mode (dtmf or voice) of the terminating command, or undefined if the transfer was not terminated by a grammar match.
name$.utterance	The utterance text used, if the transfer was terminated by speech-recognition input, or the DTMF result, if the transfer was terminated by DTMF input

Parents

form

Children

audio, catch, enumerate, error, filled, grammar, help, noinput, nomatch, prompt, property, value

Remarks

The aai and aiexpr attributes are mutually exclusive.

The bridge and bridgeexpr attributes are mutually exclusive.

The connecttimeout and connecttimeoutexpr attributes are mutually exclusive.

The dest and destexpr attributes are mutually exclusive.

The maxtime and maxtimeexpr attributes are mutually exclusive.

The transferaudio and transferaudioexpr attributes are mutually exclusive.

The connecttimeout, connecttimeoutexpr, maxtime, maxtimeexpr, and transferaudio attributes apply to bridged transfers only.

To allow the user to terminate the call during a bridged transfer, include a grammar that contains the utterances and DTMF input that allow the user to terminate the call. If the user terminates the call by uttering or typing something in the grammar, the filled is executed, and the transfer item variable contains the value "near_end_disconnect". The example below includes a transfer grammar.

If you do not want the VoiceXML interpreter to listen for spoken or DTMF input during the transfer, set the inputmodes property to the appropriate value. The example below sets the inputmodes property to dtmf, so that voice input is ignored during the transfer.

Properties that accept time designations should be set to a non-negative real number followed by a time unit identifier - either "ms" for milliseconds or "s" for seconds. For example, "3s" represents 3 seconds; "3000ms" represents 3000 milliseconds, and "1.5s" represents 1.5 seconds.

Prior to Revision 2, if the dest or destExpr attribute does not specify a destination with a prefix containing a valid transfer destination URI type (tel or "sip:"), then the transfer fails and the transfer form item is filled with "busy" or "near_end_disconnect". In Revision 2, in that situation the interpreter throws error.connection.baddestination. In Revision 3 and later, the interpreter throws error.unsupported.uri.

The type and bridge attributes are mutually exclusive. If both are specified, the VoiceXML interpreter throws error.badfetch.

Examples

The following example requests a telephone number from the user, performs a bridged transfer to the number, plays back the duration of the call, and finally exits.

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

  <var name="phone_number"/>

  <!-- get a phone number from the user -->
<form id="get_number">  
  <field name="phone_number">
     <prompt>
     What number do you wanna call?
     <audio 
       src="http://naturalsound.svc.tellme.com/common-audio/intellipause.wav"/>
     </prompt>

      <grammar src="builtin:digits?length=10"/>

     <catch event="noinput nomatch">
        Sorry. I didn't get that.
        <reprompt/>
     </catch>

     <filled>
        <!-- store the number at document scope to be used 
          by the call_number dialog -->
        <assign name="document.phone_number" expr="'tel:+1' + phone_number"/>
        <goto next="#call_number"/>
     </filled>
  </field>
</form>

  <!-- call the phone number specified by the caller -->
<form id="call_number">
 <block>
   <prompt>testing transfer</prompt>
   <log>calling: <value expr="phone_number"/></log>
 </block>

 <!-- must explicitly set bridge to true for bridged transfers -->
  <transfer name="theCall" destexpr="phone_number" 
    connecttimeout="30s" type="bridge"
    transferaudio="http://naturalsound.svc.tellme.com/common-audio/intellipause.wav">

    <!-- only allow DTMF input during this transfer -->
    <property name="inputmodes" value="dtmf"/>

   <prompt>
       transferring...
       <break size="small"/>
       Press star star to cancel.
   </prompt>

   <!-- the call is terminated when the user types star-star (**) -->
   <!-- the "abort" value is arbitrary. any syntactically legal value works 
        so long as one is provided (#12832) -->
   
   <grammar mode="dtmf"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0">
      <rule id="root_rule" scope="public">
         <one-of>
            <item>
               <one-of>
                  <item>
                  </item>
               </one-of>
            </item>
         </one-of>
      </rule>

   </grammar>


   <filled>
     <log>transfer returned: <value expr="theCall"/></log>

     <if cond="theCall == 'busy'">
        <prompt>The line was busy. Please try again later.</prompt>
     <elseif cond="theCall == 'noanswer'" />
       <prompt>Noone is answering.</prompt>
     <elseif cond="theCall == 'network_busy'" />
       <prompt>The network is busy!</prompt>
     <elseif cond="theCall == 'near_end_disconnect'" />
       <prompt>The call was completed, and you terminated it with dtmf input.</prompt>
     <elseif cond="theCall == 'far_end_disconnect'" />
       <prompt>The call was completed, and the callee terminated it.</prompt>
     <elseif cond="theCall == 'maxtime_disconnect'" />
       <prompt>The call was completed, and it exceeded the maximum time allowed.</prompt>
     <elseif cond="theCall == 'network_disconnect'" />
       <prompt>The call was completed, but it was terminated by the network.</prompt>
     </if>
   </filled>

   <error>
   <!-- receive notification of transfer failure -->
   <log><value expr="_event"/> occurred while attempting 
      transfer to 
      <value expr="theNumber"/>.
   </log>
   </error>

 </transfer>

 <block>
   <prompt>The call lasted approximately 
      <value expr="Math.round(theCall$.duration)"/> seconds.
   </prompt>
   <!-- navigate to the main menu - or anywhere else. 
        you can also disconnect to simulate a blind (non-bridging) transfer -->
   <exit />
 </block>
</form>
</vxml>