starting the call

To make or receive telephone calls the voice application uses the WVR class, which represents the base Blueworx Voice Response system. You can also use this class to cancel a waitForCall() method or makeCall() method or to delete, import or export single voice segments from within your application.

You generally only need one WVR object in your application. To create it, you need to pass into the constructor method a reference to the application itself as the first parameter, and an optional second parameter which consists of an ApplicationProperties object. (See Setting the application environment and The ApplicationProperties class for more information about application properties.)

For example:

public class MyVoiceApp extends WVRApplication {
	
  public void voiceMain() throws WVRException {
	
    // Create the application properties object
    ApplicationProperties appProperties = new ApplicationProperties();
		
    // Use the application properties to create the WVR object. The this
    // keyword registers the application as the owner of the WVR object
    WVR wvr = new WVR(this, appProperties);
    .
    .
    .
  }
  .
  .
  .
}

It is possible to create a WVR object without application properties, but you must set the properties before you can use it. You can do this by invoking the WVR.setApplicationProperties() method (not to be confused with the WVRApplication.setApplicationProperties() method).

Once the WVR object has been created and the application properties set, you can make or receive a call using the following methods, which should be included in a try–catch block so that you can handle any error conditions:

makeCall(String label, String number)

Makes a call to the specified number and waits the number of seconds specified by the ringTime property (see below) for an answer. If the call is answered, makeCall returns a Call object. The call label is an optional tag to enable the application to identify the call. You can use labels to gather call statistics or to identify recordings of calls received.

Exceptions thrown:

WVRException
WVRRequestCancelled exception: if the call request has been cancelled
WVRMakeCallException: if the outbound call is either not answered or answered by a machine. You can construct your application so that depending on the apparatus detected, a voice or fax message is played (for example a message left on the answering machine).

waitForCall(String label)

Waits the number of seconds specified by the waitTime property (see below) for an incoming call, and returns a Call object. The call label is an optional tag to enable the application to identify the call. You can use labels to gather call statistics or to identify recordings of calls received.

Exceptions thrown:

WVRException
WVRRequestCancelledException: if the call request has been cancelled
WVRInvalidApplicationPropertiesException: if the application properties are invalid
WVRWaitForCallTimeoutException: if a call has not been received in the specified time (see waitTime, below)

Both these methods return a Call object if successful. The Call object represents a single telephone call. It is used by the voice application to play prompts to the caller (or called party for an outbound call), get the caller's input, hand the call over to another application, transfer the call or return the call when your application has finished with it. The Call class will be dealt with in detail throughout the rest of this documentation.

The WVR class includes the following properties used when starting a call. Each property has get and set methods as appropriate:

waitTime(): the maximum time in seconds that a voice application waits for a call when using waitForCall() to receive an incoming telephone call. The default is -1 (wait forever).
ringTime(): the maximum time in seconds that a voice application waits for an answer when using makeCall() to make an outgoing telephone call. The default is -1 (wait forever). Specify 0 to use the system default, this is the Maximum Ring Time system parameter.

The WVR class has other properties and methods that will be covered later on in the documentation, for example, dynamically deleting, importing and exporting voice segments is covered in Handling voice segments dynamically.

Starting the call