<bevocal:dial>

Extension. Initiates an outbound call, allowing the user to talk to a third party at another destination.

Syntax

 <bevocal:dial
     name="string"
     dest="URI"
     destexpr="js_expression"
     silent="true"|"false" 
     ani="digit_string"
     aniexpr="js_expression"
     connecttimeout="time_interval"
     maxtime="time_interval"
     bevocal:maxtimeexpr="js_expression"
     bevocal:type="blind"|"bridge"|"supervised"
     type="blind"|"bridge"|"consultation"
     onhold="true"|"false"
     transferaudio="URI" 
 />

Description

To use this tag, the containing <vxml> tag must declare the XML namespace bevocal by including the following attribute:

 xmlns:bevocal="http://www.bevocal.com/"

The <bevocal:dial> tag may initiate a call 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.

Note: This and other call-control tags constitute a BeVocal VoiceXML extension. Committees are currently working to standardize call-control features for VoiceXML, and their current approach is different from the BeVocal VoiceXML implementation. Because the approval of any call-control standards will be quite some time in coming, however, BeVocal VoiceXML contains this extension to allow developers to start taking advantage of call-control features. BeVocal will continue to monitor the development within these committees. If the features in the BeVocal VoiceXML extension become a part of VoiceXML or a separate call-control standard, BeVocal VoiceXML will implement that standard. We will then deprecate the current extension and provide developers with information on how to convert their applications to the new standard.

Attribute	Description
name	Name of a variable to be set to a JavaScript object referring to the call. Optional. If no variable exists with the specified name, a new variable is defined in the current scope; for example, in the anonymous scope of the containing <block>.
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.
silent	Specifies whether the call-progress sounds are muted. Optional (default is false).  •  true--The call-progress sounds and all other sounds from the outbound call are muted until the post-dial digits have finished playing.  •  false--The user hears the call-progress sounds and a small snippet of the call after it is connected and before the post-dial digits are played.
ani	A sequence of digits to be passed as the ANI or Caller ID for the outbound call. Optional (default is the value of the session.telephone.ani variable). The ANI may contain up to 32 digits in either of the following forms:  •  A formatted phone number, with or without area code, for example, (201)555-1212  •  a string of ASCII digits, for example, 012345647830193856 ANI spoofing is disabled by default on Café for outbound calls via call control tags. A warning is thrown to VXML log. It is enabled by default on hosting servers. Contact BeVocal to enable ANI spoofing on Café. Note: You may specify either this attribute, or aniexpr, but not both.
aniexpr	JavaScript expression that evaluates to the sequence of digits to be passed as the ANI or Caller ID for the outbound call. Optional (default is the session.telephone.ani variable). Note: You may specify either this attribute, or ani, but not both.
connecttimeout	Time to wait for the outbound call to connect before throwing a connection.far_end.noanswer event. Optional (default is 20 seconds). Express time interval as an unsigned number followed by either s for time in seconds or ms for time in milliseconds (the default).
maxtime	How long the call is allowed to be in progress. Optional.  •  The default for Café customers is 60 seconds. This is an absolute maximum. If the time in this attribute is longer than 60 seconds, the interpreter uses 60 seconds as the limit.  •  The default for hosting customers is 0, signifying no limit. Express time interval as an unsigned number followed by either s for time in seconds or ms for time in milliseconds (the default). If the call exceeds the maximum duration, the outbound call is disconnected and a connection.far_end.disconnect.timeout event is thrown.
bevocal:maxtimeexpr	Extension. A JavaScript expression which evaluates to the maxtime value. Optional.  •  Again, the default for Café customers is 60 seconds. This is an absolute maximum. If the time in this attribute is longer than 60 seconds, the interpreter uses 60 seconds as the limit.  •  The default for hosting customers is 0, signifying no limit.
bevocal:type	Extension. 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 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 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 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.
onhold	Specifies whether the outbound call is put on hold immediately after it is answered and after any post-dial digits have been sent. Optional (default is false).  •  true--Put the called third party on hold until reconnected by a <bevocal:connect> tag.  •  false--Leave the call active with the user connected to the called third party. Setting this attribute to true is equivalent to executing a <bevocal:hold> tag immediately after executing the <bevocal:dial> tag.
transferaudio	Audio (specified by the URI) to play while the call connection attempt is in progress. Note: This attribute is valid only for VoIP calls.

The following events may be thrown by the execution of a <bevocal:dial> tag:

Event	Description
connection.far_end.busy	The call was refused by the endpoint (the number was busy).
connection.far_end.noanswer	There was no answer within the time allowed for making the connection.
connection.far_end.network_busy	The call was refused by an intermediate network.
connection.far_end.network_disconnect	The call completed and was terminated by the network.
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.
telephone.disconnect.hangup	The user hung up while the connection was being made; for example, before the outbound call was answered. VoiceXML 1.0 only.
connection.disconnect.hangup	The user hung up while the connection was being made; for example, before the outbound call was answered. New in VoiceXML 2.0.

	Tip:
	•  If a JavaScript expression contains any of the characters "<", ">", or "&", that character must be replaced with the corresponding escape sequence "&lt;", "&gt;", or "&amp;". For more information, see JavaScript Quick Reference.

Usage

Parents	Children
<bevocal:foreach> <block> <catch> <error> <filled> <help> <if> <noinput> <nomatch>	None

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>
     <var name="myCall"/>
 
     <!-- Establish an outbound call, then play a prompt to it -->
     <block>
       Placing an outbound call...
       <bevocal:dial name="myCall" dest="tel:4085551212"/>
       <bevocal:whisper call="myCall">
         <!-- This prompt is played to the called party -->
         Please hold for a call from the President
       </bevocal:whisper>
     </block>
 
     <!-- Listen in on the call, waiting for one of the hotwords 
          in the grammar below to be spoken. If the caller or callee 
          hangs up, an event will be thrown. -->
     <bevocal:listen name="hotword">
       <grammar type="application/x-nuance-gsl">
         <![CDATA[
           [
             (good bye) { return ("exit") }
             (one) { return ("1") }
             (two) { return ("2") }
             (three) { return ("3") }
           ]
         ]]>
       </grammar>
 
       <filled>
         <if cond="hotword == 'exit'">
           Good bye
           <bevocal:disconnect call="myCall"/>
         <else/>
           <!-- The other hotwords return single digits. 
                Echo them as DTMF to the called party -->
           <bevocal:whisper call="myCall">
             <audio expr="'dtmf_' + hotword + '_100.wav'">
             <value expr="hotword"/></audio>
           </bevocal:whisper>
           <clear namelist="hotword"/>
         </if>
       </filled>
 
       <catch event="connection.far_end.disconnect.timeout">
         I'm sorry. The outbound call has exceeded the maximum allowed time.
         <exit/>
       </catch> 
 
       </bevocal:listen>
         <catch event="connection.far_end.disconnect">
           <!-- The outbound caller hung up. Returning to where you left off.
           Continue with your application. -->
         </catch>
         <catch event="connection.disconnect.hangup">
           <!-- The inbound caller hung up. Disconnect the outbound call. 
           This isn't really required; it will happen automatically 
           if you don't do it. But it's good practice anyway. -->
           <bevocal:disconnect call="myCall"/>
         </catch> 
     </form>
 </vxml>

Café Home | Developer Agreement | Privacy Policy | Site Map | Terms & Conditions Part No. 520-0001-02 | © 1999-2007, BeVocal, Inc. All rights reserved | 1.877.33.VOCAL