Supervised Transfers

Supervised transfers are also known as consultation transfers.  When a supervised transfer is initiated, the primary call is placed on hold and a consultation call is made to the party intended to receive the primary call.  The transfer may then be completed causing the consultation call to be hung up and the primary call to be transferred to the intended party.

A supervised transfer allows the receiving party to be consulted prior to accepting the call.  In a supervised or consultation call, some information is passed to the receiving party through the TAPI device such that an intelligent decision can be made as to the disposition of the call. With a blind transfer the receiving party is not informed of the call before it is sent.

Supervised transfers can be used to create attended applications that required a human to announce the pending transfer much like a typical office attendant does when they ring an extension and ask the receiving party if they would like to take the call.  Supervised transfers can also be used with an automated telephony device to create a Call Screening application.  In a call screening application, the caller might be asked to provide the answer to questions through pressing digits on the DTMF pad, or to record a short message such as their name.  With this system, the caller can be routed to the appropriate person or department and the intended party can either take the call or route it to voicemail.

Three-Way Calls and Call-Waiting

Many telephony devices can create three-way calls. Three way calls can be used with automated telephony devices to build a call recording application.  By routing the call through a TAPI device using three-way instead of directly to the intended party, the device is in charge of the call and can perform operations such as recording the conversation.

While some devices may have a function for handling conference calls directly, many devices require that a conference call be created as a three-way call after which it will allow other calls to be added to the conference.  The method demonstrated here will also work to answer a call that comes in using call-waiting and switching between calls.  So for people with Centrex or other systems that provide 3-Way calling and Call-Waiting features, you may use TeleTools' etLine.Transfer methods to make 3-Way conferences on outgoing calls and swap between held and connected calls on incoming calls. 

Continue reading.  This document explains this process in more details and includes examples using TeleTools and Telescope, and contains links to more information on the WEB page.  Also please take the time to read the “Using TeleScope” and the “How Do I Do That?” sections of the ExceleTel TeleTools Help File also available online.

The information in this white paper is intended to help you understand how supervised transfers work.  It is also useful for debugging problems with your application.  It can also be helpful when diagnosing configuration issues with your telephony device and even identifying problems with Telephone Service Providers (TSP) and drivers!

Why Use ExceleTel TeleTools?

ExceleTel TeleTools Enterprise v3.7 is designed to manage multiple calls. This is vital when working with supervised transfers and conferences. TeleTools takes care of the call handle management and call progress monitoring for each call.  This includes the management of dropped calls.

ExceleTel TeleTools Standard and Professional support blind transfers. While TeleTools Enterprise supports blind and supervised transfers.

Over the years ExceleTel has helped many telephony device manufacturers diagnose problems with their hardware, TSP, drivers and configurations.  Please feel free to share this information with the manufacturer!

When problems arise most telephony hardware manufactures are all to ready to point their finger at your code or even TeleTools.  For this reason we are supplying you with the information to use the Microsoft programmer’s utility known as TAPI Browser and our TeleScope utility.  With this you can perform the operations creating the problems and supply them with the logs!

Our intention is to give you tools to solve problems.  If you get into a situation with your telephony device manufacturer that we can help please let us know.  We are even available for conference calls.

Our customers have tested supervised transfers on a number of PBX’s and telephony devices:  Just to name a few:

PhoneRider

Dialogic

MUSIC Telecom

Vertial Networks

Intertel

Cisco

Panasonic

Ascom

Nitsuko

Lucent

Siemens

Alcatel

Toshiba

Nortel

Mitel

ECI_Telecom

Samsung

Altigen

Please remember that ExceleTel TeleTools and TAPI are limited to the capabilities of your telephony device.  Be sure to check with your telephony device manufacturer for the device capabilities and configuration information.

TAPI Functions

ExceleTel TeleTools uses the following TAPI function calls to perform supervised transfers:

  • LineSetupTransfer: This function is used to create the consultation call, it is called when the etLine.Transfer.Dial method is executed.  The primary call must be in the connected state when this function is executed.
  • LineDial: Once the TAPI reply message for the lineSetupTransfer function is received TeleTools executes the lineDial function to begin dialing the phone number.
  • LineCompleteTransfer: The etLine.Transfer.Complete and etLine.Transfer.ThreeWay methods call this function with the appropriate parameters to either complete the transfer or create a three-way call.
  • LineSwapHold: Once the consultation call has been connected the etLine.Transfer.SwapHold method uses this function to place the currently connected call on hold and the other call to the connected state.
    Not all telephony devices support this function.

Capabilities

Before you begin writing code you can use the TeleScope to check the value of many of the properties to the etLine.Control.  The etLine.Address.Capabilities properties indicate which features the currently selected device supports.  These properties can also be used at runtime to make sure that the selected device has the capabilities to perform the desired operation.

  • The etLine.Transfer.Dial method is available when the bit flag LINECALLFEATURE_SETUPTRANSFER is set in the property etLine.Address.Capabilities.CallFeatures.
  • The etLine.Transfer.Complete method is available when the bit flag LINECALLFEATURE_COMPLETETRANSF is set in the property etLine.Address.Capabilities.CallFeatures and the bit flag LINETRANSFERMODE_TRANSFER is set in the property etLine.Address.Capabilities.TransferModes.
  • The etLine.Transfer.ThreeWay method is available when the bit flag LINECALLFEATURE_COMPLETETRANSF is set in the property etLine.Address.Capabilities.CallFeatures and the bit flag LINETRANSFERMODE_CONFERENCE is set in the property etLine.Address.Capabilities.TransferModes.
  • The etLine.Transfer.SwapHold method is available when the bit flag LINECALLFEATURE_SWAPHOLD is set in the property etLine.Address.Capabilities.CallFeatures.

The following image illustrates how to check the capabilities of the device.  Notice that the selected device supports:

LINECALLFEATURE_SETUPTRANSFER, 
LINECALLFEATURE_COMPLETETRANSF and 
LINECALLFEATURE_SWAPHOLD.

Configuration

Many telephony devices must be configured to support advanced features such as supervised transfers. For example Dialogic cards must have the proper DTMF tones entered into the configuration dialogic box:


Check with your telephony hardware manufacturer to make sure that you have your device configured properly. For 3-Way and Call-Waiting systems, you enter a flash "!" for things like HOLD, SWAPHOLD, CONFERENCE, etc.  For PBX's, you enter the actual codes and/or escape sequences found in the PBX manual.

Transfer Sample Application

The Transfer sample application provided with TeleTools demonstrates how to perform a supervised transfer.  A compiled version of this application is provided with the full installation of ExceleTel TeleTools and is available from the Sample Applications section of our WEB site.

When this application starts the etLine TeleScope is displayed.  This is a useful tool for experimenting with your telephony device.

Perform the following operations to begin using this application:

1.      Select a telephony device using the list box.
2.      Activate the telephony device by clicking the “Active” check box.
3.      Enter a phone number in the edit box adjacent to the “Dial” button.
4.      Click the “Dial” button to create the primary call.
5.      Once the primary call is connected enter a phone number in the edit box adjacent to the “TransferDial” button.
6.      Click the “TransferDial” button to create the consultation call.

Once the primary call has a call state of “On Hold Pending Transfer” and the consultation call is in the “Connected” state the following operations may be performed:

Swap: This will place the consultation call on hold and reconnected the primary call or visa versa. Remember, not all telephony devices support this feature.

Complete: This will hang up the primary call, completing the line transfer to the consultation call. In most cases all calls will no longer be available to the line device.
With most telephony devices the primary call must have a call state of “On Hold Pending Transfer” and the consultation call must be in the “Connected” state prior to completing the transfer or creating a three-way call.

ThreeWay: This will create a conference with the primary and consultation calls.

This sample program requires the primary call to be dialed. In a typical application the origin of the call may be an inbound call. We have provided this feature for demonstration purposes only. Most telephony devices do not care about the origin of the call.

TeleScope

The TeleScope utility supplied with ExceleTel TeleTools makes it easy to experiment with your telephony device.  Use it to learn how your device works and to debug problems with your code and even the telephony device, it’s drivers and Telephony Service Provider (TSP).

Please take the time to read the “Using TeleScope” and the “How Do I Do That?” sections of the ExceleTel TeleTools help file also available online.

 

 

  1. Either Dial or Answer a call.
  2. Select the “transfer” tab.
  3. Select the Call Handle from the list box adjacent to the “PrimaryCall” button.
  4. Enter a phone number in the edit box adjacent to the “Dial” button.
  5. Click the “Dial” button.
    The primary call will be placed in the state “On Hold Pending Transfer”.
  6. Answer the new call!
    The consultation call will have the call state of “Connected”.
  7. Click the “Complete” button.
    The primary call and the Consultation call will go idle. TeleTools will then no longer be aware either call. The two parties will be connected.

For Three-Way Calls

  1. Dial the first call
  2. Select the transfer tab
  3. Select Cal Handle from the list box adjacent to the "Primary Call" button
  4. Enter a phone number in the edit box adjacent to the "Dial" button
  5. Click the "Dial" Button, the call will be placed in the state, "On Hold Pending Transfer"
  6. Answer the new call!  You will see the state of this call go to "Connected"
  7. Click the ThreeWay button
  8. You will have a ThreeWay conference and maintain control of each call by it's Call Handle

TeleScope Log

Below is the etLine TeleScope log created while performing the supervised transfer above.  We have added a number of comments in red.

The primary call is created!

CallHandle = 00000000
      
CallHangup - Returned = True
CallDial [00000000]
      
CallPhoneNumber = 101
CallHandle = 0001006A
OnCallBegin [0001006A]
      
CallBegan = 18:26:08
      
CallDial - Returned = True
OnDialTone [0001006A]
OnCalledID [0001006A]
      
CallCalledIDBlocked = False
      
CallCalledIDName = ""
      
CallCalledIDNumber = "101
      
CallCalledIDOutOfArea = False
      
CallCalledIDFlags = [00000008]
             
LINECALLPARTYID_ADDRESS
OnDialing [0001006A]
The primary call is answered!
OnConnected [0001006A]
CallHandle = 00000000

The consultation call is created!

TransferDial [0001006A]

      
TransferPhoneNumber = 102

The primary call is placed on hold!

OnHoldPendingTransfer [0001006A]
CallHandle = 0001036B
OnCallBegin [0001036B]

      
CallBegan = 18:28:57
OnDialTone [0001036B]
OnCalledID [0001036B]
      
CallCalledIDBlocked = False
      
CallCalledIDName = ""
      
CallCalledIDNumber = "102
      
CallCalledIDOutOfArea = False
      
CallCalledIDFlags = [00000008]
             
LINECALLPARTYID_ADDRESS
OnDialing [0001036B]
      
TransferDial - Returned = True
The consultation call is answered!
OnConnected [0001036B]
The transfer is completed!
Notice that the Primary call is “Onhold Pending Transfer” and the consultation call is “Connected”!

TransferComplete [0001006A]
OnCallEnd [0001036B]

      
CallEnded = 18:31:04
The consultation call goes idle!
OnCallIdle [0001036B]

TeleTools automaticly selects the next call in the list!
CallHandle = 0001006A
<< Error >> LINEERR_INVALCALLHANDLE [80000018]
Remember ExceleTel TeleTools takes care of Call Handle management for you. In some cases this error will occur after completing a transfer because etLine.OnIdle event has not been received for all of the calls.  This is nothing to worry about.
CallHandle = 00000000
OnCallEnd [0001006A]

      
CallEnded = 18:31:05
The primary call goes idle!
OnCallIdle [0001006A]

      
TransferComplete - Returned = True

TAPI Browser

TAPI Browser is a programmer’s utility supplied by Microsoft.  Using this you can perform many of the operations available through TeleTools however you need to understand TAPI!  Don’t worry; we have come up with the step-by-step instructions you’ll need to perform the Supervised Transfer test. Please reference the “Debugging with TAPI Browser” Topic of the ExceleTel TeleTools help file.

  1. See the “Preparing TAPI” section of the “Debugging with TAPI Browser” Topic of the ExceleTel TeleTools help file.
  2. See the “making a Call” section of the “Debugging with TAPI Browser” Topic of the ExceleTel TeleTools help file.
  3. Answer the call!
    The message “LINE_CALLSTATE” with the parameter “CONNECTED” will be received for the primary call.
  4. Check the “Params” checkbox.
  5. Locate the TAPI function "lineSetupTransfer” in the left column and single click on it. TAPI Browser will automatically select the only call as the primary call.
  6. Click the “OK” button.
    The message “LINE_CALLSTATE” with the parameter “ONHOLDPENDTRANSFER” will be received for the primary call.
  7. When the message “LINE_CALLSTATE” with the parameter “DIALTONE” is received double click on the TAPI function “lineDial”.
  8. In the Parameters list select “lpszDestAddress”. The current value will be “55555”, change it to the telephony number to be dialed. For example:“102”.
  9. Click the “OK” button.
  10. Answer the call!
    The message “LINE_CALLSTATE” with the parameter “CONNECTED” will be received for the consultation call.
  11. Locate the TAPI function "lineCompleteTransfer” in the left column and single click on it. TAPI Browser will automatically select the primary and consultation calls. Notice that the Primary call is “Onhold Pending Transfer” and the consultation call is “Connected”!
  12. Select each call then click the “Call-“ button to deallocate the calls.
  13. Just for grins, compare this to the simple, short process if you had used TeleTools!

TAPI Browser Log

 

lineInitialize returned SUCCESS
 
num line devs = 53
lineOpen returned SUCCESS

The primary call is created!

lineMakeCall returned x10327
received LINE_REPLY

 
device=x0
 
cbInst=x0
 
param1=x10327, 
 
param2=x0, 
 
param3=x10347, 
received LINE_CALLSTATE
 
device=x10347
 
cbInst=x0
 
param1=x8000, UNKNOWN 
 
param2=x0, 
 
param3=x0, 
received LINE_CALLSTATE
 
device=x10347
 
cbInst=x0
 
param1=x8, DIALTONE 
 
param2=x20, UNAVAIL 
 
param3=x0, 
received LINE_CALLINFO
 
device=x10347
 
cbInst=x0
 
param1=x10000, CALLEDID 
 
param2=x0, 
 
param3=x0, 
received LINE_CALLSTATE
 
device=x10347
 
cbInst=x0
 
param1=x10, DIALING 
 
param2=x0, 
 
param3=x0, 
The primary call is answered!
received LINE_CALLSTATE

 
device=x10347
 
cbInst=x0
 
param1=x100, CONNECTED 
 
param2=x0, 
 
param3=x0, 

The consultation call is created!

lineSetupTransfer returned x1016b
received LINE_REPLY

 
device=x0
 
cbInst=x0
 
param1=x1016b, 
 
param2=x0, 
 
param3=x10238, 
received LINE_CALLSTATE
 
device=x10347
 
cbInst=x0
 
param1=x2000, ONHOLDPENDTRANSFER 
 
param2=x0, 
 
param3=x0, 
received LINE_CALLSTATE
 
device=x10238
 
cbInst=x0
 
param1=x8000, UNKNOWN 
 
param2=x0, 
 
param3=x0, 
received LINE_CALLSTATE
 
device=x10238
 
cbInst=x0
 
param1=x8, DIALTONE 
 
param2=x20, UNAVAIL 
 
param3=x0, 

The consultation call is dialed!

lineDial returned x1029e
received LINE_CALLINFO

 
device=x10238
 
cbInst=x0
 
param1=x10000, CALLEDID 
 
param2=x0, 
 
param3=x0, 
received LINE_CALLSTATE
 
device=x10238
 
cbInst=x0
 
param1=x10, DIALING 
 
param2=x0, 
 
param3=x0, 
received LINE_REPLY
 
device=x0
 
cbInst=x0
 
param1=x1029e, 
 
param2=x0, 
 
param3=x0, 
The consultation call is answered!
received LINE_CALLSTATE

 
device=x10238
 
cbInst=x0
 
param1=x100, CONNECTED 
 
param2=x0, 
 
param3=x0, 
The transfer is completed!
Notice that the Primary call is “Onhold Pending Transfer” and the consultation call is “Connected”!

lineCompleteTransfer returned x102af
received LINE_REPLY

 
device=x0
 
cbInst=x0
 
param1=x102af, 
 
param2=x0, 
 
param3=x0, 
   
NOTE: *lphCall==NULL, freeing call data structure
The consultation call goes idle!
received LINE_CALLSTATE

 
device=x10238
 
cbInst=x0
 
param1=x1, IDLE 
 
param2=x0, 
 
param3=x0, 
lineGetCallStatus returned SUCCESS
The primary call goes idle!
received LINE_CALLSTATE

 
device=x10347
 
cbInst=x0
 
param1=x1, IDLE 
 
param2=x0, 
 
param3=x0, 
lineGetCallStatus returned SUCCESS
The primary and consultation call are deallocated!
lineDeallocateCall returned SUCCESS
lineDeallocateCall returned SUCCESS

Notes

With most telephony devices the primary call must have a call state of “On Hold Pending Transfer” and the consultation call must be in the “Connected” state prior to completing the transfer or creating a three-way call.