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.
- Either
Dial or Answer a call.
- Select
the “transfer” tab.
- Select
the Call Handle from the list box adjacent to the “PrimaryCall”
button.
- Enter
a phone number in the edit box adjacent to the “Dial” button.
- Click
the “Dial” button.
The primary call will be placed in the state “On Hold Pending
Transfer”.
- Answer
the new call!
The consultation call will have the call state of “Connected”.
- 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
- Dial
the first call
- Select
the transfer tab
- Select
Cal Handle from the list box adjacent to the "Primary Call"
button
- Enter
a phone number in the edit box adjacent to the "Dial" button
- Click
the "Dial" Button, the call will be placed in the state,
"On Hold Pending Transfer"
- Answer
the new call! You will see the state of this call go to
"Connected"
- Click
the ThreeWay button
- 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.
- See the “Preparing TAPI”
section of the “Debugging with TAPI Browser” Topic of the ExceleTel
TeleTools help file.
- See the “making a Call”
section of the “Debugging with TAPI Browser” Topic of the ExceleTel
TeleTools help file.
- Answer the call!
The message “LINE_CALLSTATE” with the parameter “CONNECTED” will
be received for the primary call.
- Check the “Params”
checkbox.
- 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.
- Click the “OK” button.
The message “LINE_CALLSTATE” with the parameter
“ONHOLDPENDTRANSFER” will be received for the primary call.
- When the message
“LINE_CALLSTATE” with the parameter “DIALTONE” is received
double click on the TAPI function “lineDial”.
- In the Parameters list select
“lpszDestAddress”. The current value will be “55555”, change it
to the telephony number to be dialed. For example:“102”.
- Click the “OK” button.
- Answer the call!
The message “LINE_CALLSTATE” with the parameter “CONNECTED” will
be received for the consultation call.
- 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”!
- Select each call then click
the “Call-“ button to deallocate the calls.
- 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.
|
