Avaya Interaction Center, Interaction Center 6.1 Programmer's Manual

Avaya™ Interaction Center

Release 6.1
VTel Programmer Guide

585-248-220

Issue 2.1

August 2003

© 2003 Avaya Inc.
All Rights Reserved.

Notice

While reasonable efforts were made to ensure that the information in this
document was complete and accurate at the time of printing, Avaya Inc.
can assume no liability for any errors. Changes and corrections to the
information in this document may be incorporated in future releases.

Preventing toll fraud

"Toll fraud" is the unauthorized use of your telecommunications system
by an unauthorized party (for example, anyone who is not a corporate
employee, agent, subcontractor, or person working on your company's
behalf). Be aware that there may be a risk of toll fraud associated with
your system and that, if toll fraud occurs, it can result in substantial
additional charges for your telecommunications services.

Avaya fraud intervention

If you suspect that you are being victimized by toll fraud and you need
technical assistance or support, call Technical Service Center Toll Fraud
Intervention Hotline at [phone] for the United States and
Canada. For additional support telephone numbers, see the Avaya Web
site:

http://www.avaya.com

Select Support, then select Escalation Lists. This Web site includes
telephone numbers for escalation within the United States. For escalation
telephone numbers outside the United States, select Global Escalation

List.

Providing telecommunications security

Telecommunications security (of voice, data, and video communications)
is the prevention of any type of intrusion to (that is, either unauthorized or
malicious access to or use of) your company's telecommunications
equipment by some party.

Your company's "telecommunications equipment" includes both this
Avaya product and any other voice/data/video equipment that could be
accessed via this Avaya product (that is, "networked equipment").

An "outside party" is anyone who is not a corporate employee, agent,
subcontractor, or person working on your company's behalf. Whereas, a
"malicious party" is anyone (including someone who may be otherwise
authorized) who accesses your telecommunications equipment with
either malicious or mischievous intent.

Such intrusions may be either to/through synchronous (time-multiplexed
and/or circuit-based) or asynchronous (character-, message-, or
packet-based) equipment or interfaces for reasons of:

• Use (of capabilities special to the accessed equipment)

• Theft (such as, of intellectual property, financial assets, or
toll-facility access)

• Eavesdropping (privacy invasions to humans)

• Mischief (troubling, but apparently innocuous, tampering)

• Harm (such as harmful tampering, data loss or alteration,
regardless of motive or intent)

Be aware that there may be a risk of unauthorized intrusions associated
with your system and/or its networked equipment. Also realize that, if
such an intrusion should occur, it could result in a variety of losses to your
company (including, but not limited to, human and data privacy,
intellectual property, material assets, financial resources, labor costs, and
legal costs).

Your responsibility for your company's telecommunications
security

The final responsibility for securing both this system and its networked
equipment rests with you, an Avaya customer's system administrator,
your telecommunications peers, and your managers. Base the fulfillment
of your responsibility on acquired knowledge and resources from a
variety of sources, including, but not limited to:

• Installation documents

• System administration documents

• Security documents

• Hardware-/software-based security tools

• Shared information between you and your peers

• Telecommunications security experts

To prevent intrusions to your telecommunications equipment, you and
your peers should carefully program and configure:

• Your Avaya-provided telecommunications systems and their
interfaces

• Your Avaya-provided software applications, as well as their
underlying hardware/software platforms and interfaces

• Any other equipment networked to your Avaya products.

Warra nty

Avaya Inc. provides a limited warranty on this product. Refer to your
sales agreement to establish the terms of the limited warranty. In
addition, Avaya’s standard warranty language, as well as information
regarding support for this product, while under warranty, is available
through the following Web site:

http://www.avaya.com/support

Link disclaimer

Avaya Inc. is not responsible for the contents or reliability of any linked
Web sites and does not necessarily endorse the products, services, or
information described or offered within them. We cannot guarantee that
these links will work all of the time and we have no control over the
availability of the linked pages.

Trademarks

®

All trademarks identified by the
trademarks, respectively, of Avaya Inc. All other trademarks are the
property of their respective owners.

Avaya, CONVERSANT, CustomerQ, DEFINITY, DefinityOne,
MultiVantage, Nabnasset, Quintus, and WebQ are registered trademarks
or trademarks of Avaya Inc. in the United States or other countries or
both.

or ™ are registered trademarks or

Ordering information: Avaya Publications Center
Voi ce: [phone]

Fax: [phone]

Write: Globalware Solutions

Web: http://www.avayadocs.com
E-mail: [e-mail]

1-800-457-1764 (Toll-free, U.S. and Canada only)

1-800-457-1764 (Toll-free, U.S. and Canada only)

200 Ward Hill Avenue
Haverhill, MA 01835 USA
Attention: Avaya Account Manager

Order: Document No. 585-248-220, Issue 2.1

August 2003

Avaya support

Avaya provides a telephone number for you to use to report problems or
to ask questions about your contact center. The support telephone
number is 1-800-242-2121 in the United States. For additional support
telephone numbers, see the Avaya Web site:

http://www.avaya.com

Select Support, then select Escalation Lists. This Web site includes
telephone numbers for escalation within the United States. For escalation
telephone numbers outside the United States, select Global Escalation

List.

Avaya Training

Avaya provides training for Avaya Operational Analyst. For more
information, contact Avaya University at:

Web site: http://www.avaya-learning.com/logon_form.asp
E-mail address: [e-mail]
US telephone: [phone]
Outside US telephone: [phone]

Comments

To comment on this document, send e-mail to [e-mail]

Acknowledgment

This document was written by the CRM Information Development group.

.

Avaya™ Interaction Center

Release 6.1

VTel Programmer Guide

Contents

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 1: Definition of terms and concepts . . . . . . . . . . . . . . . . . . . . . . 13

What is VTel? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Phones, calls, and switches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Agent IDs and Telephony Login IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

The Agent ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

The Telephony Login ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Call routing and queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Phone states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Phone states after hang up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Preset style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Immediate style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Auto-In and Manual-In modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Contents

Chapter 2: Communicating with other applications. . . . . . . . . . . . . . . . . . . 21

Using DDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

DDE requests and event messages . . . . . . . . . . . . . . . . . . . . . . . . . . 22

DDE in C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

DDE in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

DDE in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Starting VTel from other applications. . . . . . . . . . . . . . . . . . . . . . . . . . . 24

The asynchronous nature of the system . . . . . . . . . . . . . . . . . . . . . . . . . 25

Race conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Requests and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Using the Ping() method to test the connection. . . . . . . . . . . . . . . . . . . . . . 28

Multiple concurrent telephone calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Socket usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 3: Initiating access to VTel . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Installing and running VTel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Dynamic IP addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Configuring VTel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Using Assign to connect to VTel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Logging in - access to Telephony resources . . . . . . . . . . . . . . . . . . . . . . . 35

Issue 2.1 August 2003 3

Contents

Logging out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Exiting VTel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 4: Message syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

DDE message syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Command name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Null Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Syntax examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Problem levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Communications path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Faulty request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Server not found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Method not found. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Method-specific problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Return code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Request IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Event messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Event ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Event type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Event name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

seqCouple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Syntax example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 5: Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Telephone switch dependency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Pass-through requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

DDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Initiating calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Terminating calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Querying and setting EDU values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Getting one value from the EDU. . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Getting multiple values from the EDU . . . . . . . . . . . . . . . . . . . . . . . . 46

Setting EDU values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Terminating an EDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

VTel command summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Interface Description Language (IDL) specification . . . . . . . . . . . . . . . . . . . . 50

VTel methods (requests from other applications) . . . . . . . . . . . . . . . . . . . . . 52

Answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Busy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

BusyOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4 VTel Programmer Guide

BusyPhoneset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

ChangePassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

ConferenceCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

ConferenceComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

ConferenceInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Deassign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Exit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

GetActive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

GetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

GetPhoneInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

GuiCallHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

GuiLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Hangup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Hold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

HoldReconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

LogEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

LoginACD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

LoginTelephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

LoginVESP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

LogoutTelephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

LogoutVESP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

MakeCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Ping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

ReadyOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

ReadyPhoneset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

ResetPhones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

RestartServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

SwapHeld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Te rm i na t e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

TransferCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

TransferComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

TransferInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

VDUCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

VDUFindVDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

VDUGetActive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

VDUGetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

VDUGetOneValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

VDUGetValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

VDUSetCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

VDUSetValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

WrapUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

WrapUpOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

get_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

set_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Contents

Issue 2.1 August 2003 5

Contents

Chapter 6: Event notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Summary of events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Event messages to other applications . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Announcement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Busy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

BusyOutbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

BusyPreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Conference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

ConferenceCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

ConferenceComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

ConferenceInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

InCall. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

IncomingCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

LoginTelephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

LogoutTelephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

LogoutVESP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

MakeCall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

OnHold. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

ReadyPreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

ResetPhones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

RingOutbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

ServerFailed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

ServerRestart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

TerminateConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

TransferCancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

TransferComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

TransferInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

VDUChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

VDUCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

VDUTerminated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

WrapUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

WrapUpPreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 7: Server failure processing. . . . . . . . . . . . . . . . . . . . . . . . . . . 101

The configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

6 VTel Programmer Guide

ServerFailReconnectLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

ServerFailRetryWaitTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

ServerFailPrompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Resynchronizing with the phone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Appendix A: The vtel.ini configuration file. . . . . . . . . . . . . . . . . . . . . . . . 105

Annotated vtel.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Appendix B: VTel errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Reading a VTel error message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Alphabetical list of VTel errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Appendix C: VTel code tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

VTel WrapUp codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

WrapUp code storage in VDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Current scheme for WrapUp code storage in VDU . . . . . . . . . . . . . . . . . . . 129

Legacy scheme for WrapUp code storage in VDU. . . . . . . . . . . . . . . . . . . . 130

VTel DEFINITY reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Contents

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Issue 2.1 August 2003 7

Contents

8 VTel Programmer Guide

Before You Begin

Typographical Conventions

This guide uses the following font conventions:

Font Type Meaning

command This font signifies commands, information that you enter into the

computer, or information contained in a file on your computer.

commandvariable This font indicates variables in a command string.

italics This font is used to add emphasis to important words and for

references to other chapter names and manual titles.

Blue underlined text in online documents indicates a hypertext

link

jump to related information.
To view the related material, click the blue underlined text.

Notes, Tips, and Cautions

Note:

Note: A note calls attention to important information.

!

!

Important:

Important:

Important: An important note calls attention to a situation that has the potential to cause

serious inconvenience or other similar repercussions.

Tip:

Tip: A tip offers additional how-to advice.

!

CAUTION:

CAUTION: A caution points out actions that may lead to data loss or other serious

problems.

Issue 2.1 August 2003 9

Before You Begin

Contacting Technical Support

If you are having trouble using Avaya software, you should:

1. Retry the action. Carefully follow the instructions in written or online documentation.

2. Check the documentation that came with your hardware for maintenance or
hardware-related issues.

3. Note the sequence of events that led to the problem and the exact messages
displayed. Have the Avaya documentation available.

4. If you continue to have a problem, contact Avaya Technical Support by:

● Logging in to the Avaya Technical Support Web site

http://www.avaya.com/support/qq

● Calling or faxing one of the following numbers from 8:30 a.m. to 8:30 p.m. (Eastern

Standard Time), Monday through Friday (excluding holidays):

- Toll free in the U.S. and Canada: 1-888-TECH-SPT (1-888-832-4778)

- Direct line for international and domestic calls: 1-512-425-2201

- Direct line for faxes: 1-512-997-4330

● Sending email with your question or problem to [e-mail]. You may

be asked to email one or more files to Technical Support for analysis of your
application and its environment.

Note:

Note: If you have difficulty reaching Avaya Technical Support through the above

URL or email address, please go to http://www.avaya.com
information.

Product Documentation

Most Avaya product documentation is available in both printed and online form. However,
some reference material is available only online, and certain information is available only in
printed form. A PDF document with detailed information about all of the documentation for
the Avaya Interaction Center is included in the Doc directory on the product CD-ROM. This
PDF document is also included on the separate documentation CD-ROM.

Readme File

for further

The Readme file is a PDF file included on the Avaya Interaction Center software CD-ROM.
This file contains important information that was collected too late for inclusion in the
printed documentation. The Readme file can include installation instructions, system

10 VTel Programmer Guide

requirements, information on new product features and enhancements, suggested
work-arounds to known problems, and other information critical to successfully installing
and using your Avaya software. Avaya may also deliver an Addendum to the Readme,
which will be posted on the Avaya Technical Support Website. The Readme Addendum will
contain similar information uncovered after the manufacture of the product CD-ROM.
Review the Readme file and the Readme Addendum before you install your new Avaya
software.

Electronic Documentation

The electronic documentation (in PDF or HTML format) for each Avaya Interaction Center
product is installed automatically with the program. Electronic documentation for the entire
Avaya product suite is included on the product CD-ROM and the documentation CD-ROM.

You can also view the documentation set online at http://www.avayadocs.com

Printed Documentation

You can purchase printed copies of these manuals separately. For details, see Ordering

information: Avaya Publications Center on the back of this manual’s title page.

License to Print the Electronic Documentation

Online copies of documentation are included on the CD-ROM that accompanies every
software release. An Avaya customer who has licensed software (a “Licensee”) is entitled
to make this online documentation available on an internal network or “intranet” solely for
the Licensee's use for internal business purposes. Licensees are granted the right to print
the documentation corresponding to the software they have purchased solely for such
purposes.

Right-To-Print License Terms

Documents must be printed “as-is” from the provided online versions. Making changes to
documents is not permitted. Documents may be printed only by any employee or
contractor of Licensee that has been given access to the online documentation versions
solely for Licensee's internal business purposes and subject to all applicable license
agreements with Avaya. Both online and printed versions of the documents may not be
distributed outside of Licensee enterprise or used as part of commercial time-sharing,
rental, outsourcing, or service bureau use, or to train persons other than Licensee's
employees and contractors for Licensee's internal business purposes, unless previously
agreed to in writing by Avaya. If Licensee reproduces copies of printed documents for
Licensee's internal business purposes, then these copies should be marked “For internal
use only within <Licensee> only.” on the first page or cover (where <Licensee> is the name
of Licensee). Licensee must fully and faithfully reproduce any proprietary notices contained

.

Issue 2.1 August 2003 11

Before You Begin

in the documentation. The copyrights to all documentation provided by Avaya are owned
by Avaya and its licensors. By printing any copy of online documentation Licensee
indicates its acceptance of these terms and conditions. This license only governs terms
and conditions of printing online documentation. Please reference the appropriate license
agreement for terms and conditions applicable to any other use, reproduction,
modification, distribution or display of Avaya software and documentation.

Educational Services

Avaya University provides excellent training courses on a variety of topics. For the latest
course descriptions, schedules, and online registration, you can get in touch with us:

● Through the web at http://www.avaya-learning.com/logon_form.asp

● Over the telephone at 800-288-5327 (within the U.S.) +001 303-406-6089 (outside of

the U.S.)

● Through email at [e-mail]

12 VTel Programmer Guide

What is VTel?

Chapter 1: Definition of terms and concepts

This section defines some of the terms used in this manual and describes concepts
involved in telephony call management. This information is general in nature; refer to your
telephone switch documentation to determine which items apply to your system.

This section includes the following topics:

● What is VTel? on page 13

● Phones, calls, and switches on page 14

● Agent IDs and Telephony Login IDs on page 15

● Call routing and queues on page 16

● Phone states on page 17

● Phone states after hang up on page 18

What is VTel?

VTel (Virtual Telephone) is a client application that provides a means of performing
standard telephony functions such as answering calls, handling conference calls, and
transferring calls. VTel is part of Avaya Computer Telephony for IC. VTel consists of:

● the basic VTel engine. The VTel engine has an API of methods that can be used by

developers creating their own user interface for call management, or to access VTel or
Telephony Server resources directly. This manual contains a description of the VTel
engine methods and events.

● the VTel graphical user interface (GUI). The VTel GUI is described in VTel User's Guide.

● the VTel OLE automation server. The VTel OLE automation server is described in VTel

Automation Server Programmer's Guide.

● the VTel utility programs, including VTelX, Simulator and Event Simulator. The utility

programs are described in VTel Utility Programs Guide

.

Issue 2.1 August 2003 13

Definition of terms and concepts

Phones, calls, and switches

The terms call, call type, phone, line appearance, and switch, as used in this manual, are
defined in the following table.

Term Definition

Call An active connection between two or more parties that

allows transmission of speech

Call type One of two different types of calls:

● direct calls, which are calls placed to a specific

equipment phone number

● ACD calls, which are calls placed to a phone number

controlled by an Automatic Call Distribution (ACD)
system.

Phone A phone number that can accept or make calls and has

at least one line appearance available. There are two
types of phones discussed in this manual:

● simple phones, which can only accept direct calls

● ACD phones, which can accept both direct calls and

ACD calls.

Line appearance The number of simultaneous calls possible on a phone.

Available line appearances for a phone can be inbound
or outbound, internal or external, and can have mixed
limits for different call types.

Switch A telephone switching system, such as a Private Branch

Exchange (PBX) or an ACD system.The term ACD is
often used in this manual to refer to any switch or
system, such as the Expert Agent Selection (EAS) on
the Avaya DEFINITY switch, capable of routing calls
through a queue.

14 VTel Programmer Guide

Agent IDs and Telephony Login IDs

Call center agents can identify themselves to the system in two ways: with an Agent ID or
with a Telephony Login ID.

The Agent ID

An Agent ID is used with ACD phones. Agents log into the phone system using Agent IDs
and assign IDs to the phoneset currently used by the agent. The switch automatically
routes calls for that Agent ID to that phone set.

The login procedure varies for each system. For example, using the Aspect switch, agents
must physically log into the phoneset. From Avaya Computer Telephony for IC, agents can
then be called through their Telephony IDs, Agent IDs, or the queue. With the DEFINITY
switch, agents can log in physically or through Avaya Computer Telephony for IC. Agents
then be called through Telephony IDs, Agent IDs, the queue, or the equipment number of
the phone set.

Agent IDs and Telephony Login IDs

The Telephony Login ID

In the Telephony system, agents log in using a Telephony Login ID. For a simple phone,
Avaya Computer Telephony for IC maps this Login ID to the physical phoneset. There is
no switch involvement with the login of a simple phone. For an ACD phone, Avaya
Computer Telephony for IC maps this Login ID to an Agent ID.

With some phone systems, IC Manager can be used to establish default assignments in
the Directory Server, so that only the Telephony Login ID (and password) is needed.
These assignments can be overridden during a VTel Login.

Issue 2.1 August 2003 15

Definition of terms and concepts

Call routing and queues

Calls can be routed:

● directly to a phone when the specific phone number assigned to the physical phone set

is called (a direct call).

● using a logical phone number which is mapped to the physical one by an external

resource (also considered a direct call).

● indirectly through a call queue (a queued call).

A queue is a means of routing calls to any one of a number of agents qualified to handle
the call. Each queue is often oriented toward a specific product, service, or particular skill
set. In some systems, each time agents log into the system, the skills associated with each
Agent ID are used to place the agents in a queue. In other systems, agents must directly
specify the queue. Depending on the telephone switch used, agents can be in several
queues at once, or can be changed to other queues by a supervisor to meet changing
needs during the day.

All ACD calls are handled through a queue. When an ACD call is transferred directly to
another agent (not another queue), it generally becomes a direct call.

16 VTel Programmer Guide

Phone states

Some telephone switches support a variety of states for ACD phones, inclluding Ready,
Busy, and WrapUp, and can provide statistics on the time spent in each state. Other
switches cannot support these states, or the rules may vary.

Phone states

The VTel configuration file (see Configuring VTel

on page 33) accommodates and supports
the variation among switches. Each installation will require its own description of possible
phone states and transitions between them.

Note:

Note: The terms used to describe phone states vary from call center to call center.

For example, Ready may be known as Available, Busy as Auxiliary Work or
Idle, and WrapUp as After Call Work.

An ACD phone can be in one of three states:

● the Ready state, which makes the phone available to receive another call

● the Busy state, which prevents the queue from sending a new ACD call, but will

generally allow new direct calls if additional inbound line appearances are available

● the WrapUp state, which follows completion of a call (on hook, hangup) and where the

agent is still processing information related to that call or customer

When the phone is in WrapUp state, it is usually implicitly busy and will not accept another
ACD call, but will accept direct calls if additional inbound line appearances are available.
For direct calls, it is possible to set some phone switches into WrapUp mode, but this is not
generally available.

While a direct call is active, you generally cannot make the phone Ready for another ACD
call. Although VTel may remain in the Ready state, the switch will prevent the queue from
dispatching another call until the phone is idle.

Issue 2.1 August 2003 17

Definition of terms and concepts

Phone states after hang up

VTel allows agents to override the predetermined default state to which an ACD phone will
be set after a call is hung up. There are two styles of changing this default phone state:
preset style and immediate style.

The PresetState variable in the VTel configuration file (vtel.ini) determines whether
the phone state can be changed in the preset style (PresetState=true) or in the
immediate style (PresetState=false).

Preset style

Upon receipt of a call, the default preset state is indicated as part of the VTel GUI's
description of the line appearance. This state will occur by default after hang up.

To override this default, the agent clicks the Ready, WrapUp, or Busy button during the
course of the call. After this selection, the call continues uninterrupted. However, when the
customer hangs up, or the agent clicks the Hang up button, the phone goes to the state
selected during the course of the call.

Immediate style

Upon receipt of a call, no default hangup state is indicated as part of the VTel GUI's
description of the line appearance.

To override the after-hangup default state, the agent clicks the Ready, WrapUp, or Busy
button when the agent wishes to hang up. VTel issues a Hangup and the phone goes
immediately to the selected state. The disadvantage of this style is that if the customer
hangs up first (or if the agent clicks the Hang up button), the agent can only go to the
default state.

!

!

Important:

Important:

Important: For switches that allow presets, the telephone switch should be set for

WrapUp after Hangup (or Busy, if WrapUp is not available on the switch).
This allows VTel to determine the subsequent phone state.

If the telephone switch were set for a Ready state after a hangup sequence (AutoReady),
VTel would not be able to override this without allowing a small window of time during
which another call can be sent from the phone queue to the agent. Further, in such a case
it may not be possible to return from the Ready state to the WrapUp state in the phone
switch.

18 VTel Programmer Guide

By using the VTel configuration file to control the preset option, it can easily be changed at
any time and the option selected can vary for each agent.

Note:

Note: The configuration file is read when the VTel Login window opens. If a

parameter is changed, the agent must exit and reenter VTel before the new
configuration becomes effective.

Auto-In and Manual-In modes

The DEFINITY switch allows an agent's profile to be set to either Auto-In mode or Manual­In mode (on disconnecting from a call, the agent must manually make the phone
available). In Auto-In mode, the agent’s phone is automatically made available (that is, put
in the Ready state) to take the next ACD call on disconnectiong from a call. In Manual-in
mode, the agent must manually make the phone available.

Agents can override their profile settings for their current sessions by using the physical
phoneset. The VTel softphone does not allow overriding in this manner.

Phone states after hang up

If an agent is configured for Auto-In, VTel cannot control the agent's availability.

If an agent is configured for Manual-In (either because the agent’s profile is set to Manual­In, or because the agent altered the setting for the current session), VTel can control the
agent's availability. This control from VTel provides more flexibility than that provided by the
switch's Auto-In mode.

To be in Manual-In mode, the Auto-Available Split (AAS) field in both the Hunt Group and
the Agent LoginID (EAS only) should be set to N. To enable Auto-In mode, the AutoIn and
PhonePresetAcd file options in the vtel.ini file must be set to Y.

!

CAUTION:

CAUTION: In order to avoid conflicts, all clients within the Avaya Interaction Center

environment must share the same settings.

When Auto-In is enabled, VTel issues preset states (TS.ReadyAuto(), TS.Busy(), or
TS.Wrapup()) to the Telephony Server immediately, instead of after a call is completed.
When calls are completed, no requests are made to the Telephony Server.

Note:

Note: VTel will not send requests to the Telephony Server if the agent is in an

active call and Auto-In is not enabled.

Issue 2.1 August 2003 19

Definition of terms and concepts

20 VTel Programmer Guide

Chapter 2: Communicating with other

applications

This section describes the communication path between VTel and other applications. This
section contains the following topics:

● Using DDE on page 22

● Starting VTel from other applications on page 24

● The asynchronous nature of the system on page 25

● Race conditions on page 26

● Requests and errors on page 27

● Using the Ping() method to test the connection on page 28

● Multiple concurrent telephone calls on page 29

● Socket usage on page 30

Issue 2.1 August 2003 21

Communicating with other applications

Using DDE

Three types of messages are sent between VTel and applications:

● requests., which perform an action or get information

● responses, which are always sent to the requester

● events, which are sent to all applications connected to VTel whenever there is a

significant change within VTel.

Your application is also required to process and respond to certain VTel requests.

This bi-directional communication is accomplished through use of Dynamic Data
Exchange (DDE). The communication techniques, syntax, and command set are designed
to be extensible to other communication methods.

DDE requests and event messages

When using DDE, requests to VTel are made by sending DDE Execute commands, as in
the Visual Basic LinkExecute method, and responses and event messages are sent
from VTel using DDE. An external application may send a DDE Execute command to VTel
requesting that VTel perform a specific function. VTel will respond by sending back another
DDE Execute command. To function in both directions, both the external application and
VTel must function as both DDE servers and DDE clients.

To support this bi-directional communication, the first message from an application must
always be an Assign() request, which establishes the return link to the other application
for sending all responses and events.

Note: Before most work can be performed, there must also be a Login request.

This section discusses some programming language-specific issues.

DDE in C

C uses the Microsoft DDEML library of functions, which is documented with the Microsoft
SDK library. This is preferred over the older Microsoft DDE library.

DDE in C++

Note:

While C++ uses the Microsoft DDEML library for basic operations, several class libraries
are available to ease the development effort.

22 VTel Programmer Guide

DDE in Visual Basic

The necessary commands, such as the LinkExecute method, are built into the Visual
Basic Language.

Because of the design of Microsoft Visual Basic, a program may not send a DDE
command while simultaneously processing another DDE command. This limitation can
generally be avoided by using a timer-driven queue to send the responses to DDE
commands. for additional information on the asynchronous nature of the system and its
affect on application design. please see The asynchronous nature of the system
page 25.

Using DDE

on

Issue 2.1 August 2003 23

Communicating with other applications

Starting VTel from other applications

VTel is designed to be started from other applications under Microsoft Windows, Windows
95, Microsoft NT, or OS/2. For example, the following could be used for a Visual Basic
application:

x = Shell("VTel",6) ’VTel started minimized, without focus’

Because the Shell function is asynchronous, the application starting VTel must wait a
short interval and verify that VTel is successfully started before attempting to communicate
with VTel. The method depends on the communication medium selected.

For more information on using VTel as an OLE automation server, see VTel Automation

Server Programmer's Guide.

24 VTel Programmer Guide

The asynchronous nature of the system

The asynchronous nature of the system

The asynchronous design of Avaya Computer Telephony for IC presents situations that
must be anticipated by connected applications.

While some requests are processed locally, others may involve distributed components of
the Telephony system. These distributed components may be connected through a LAN or
a WAN. Some requests may wait for another user’s response or for communication delays
in a phone system.

All applications that process events must be designed to manage these situations. For
example, VDUChange events may be reported from various sources at various times in
any order.

In general, applications should not make a request and postpone all other operations until
the response to that request is received. For example, if Logout and Exit commands
arrive at VTel just before a MakeCall request, the application may never receive a
response, since VTel will no longer be available.

Designing for asynchronous processes is more difficult than designing for synchronous
processes, and requires careful attention during the initial application design.Most
applications are generally more complex than originally envisioned.

When programming asynchronous processes, you may want to:

● establish queues for both requests and events

● affix a unique identifier to each request to allow its response to be easily distinguished

from others

● use time outs to allow your application to recover from problems elsewhere

Issue 2.1 August 2003 25

Communicating with other applications

Race conditions

Because telephone functions occur in real time, most operations are subject to race
conditions.

A race condition exists when two competing events "race" and the result is determined by
which comes in first. In such a situation an external event may occur that temporarily
invalidates an application’s state information. For example, at any time during a telephone
call the caller may hang up, the agent may perform functions on the telephone set, or the
agent may perform functions using VTel that cause a state change.

Applications interacting with VTel should never assume that any state information that they
hold about a call remains valid. The state information received from event messages is
accurate at that time, but may change before an application can act on it. A request to
release a call, place a call on hold, or transfer a call may fail because the call has already
been disconnected. In this case the failure is not a hard error, but is due to a temporary
loss of synchronization.

26 VTel Programmer Guide

Requests and errors

Because of the real time behavior described above, certain requests may return a normal
response even if the request is not successful. In these cases you must rely on the events
returned to determine if the request was ultimately successful.

In general, those requests that immediately return specific information can be relied upon
as being correct at that point in time. For example, a MakeCall() request returns the
EDU ID of the outbound call that was created. Once you have this EDU ID you know that
an outbound call was created successfully.

Requests that perform an action without returning information must be judged in terms of
the events that follow. For example, if there is an incoming call and you submit an
Answer() to respond, one of these scenarios may result:

● the Answer() request may succeed and the agent will receive a

TS.IncomingCall.event.

● the Answer() request may fail because the call has ended before the request reaches

the telephone switch and the EDU ID no longer exists. You may not know that the
Answer() request did not succeed until some later time.

Requests and errors

● the Answer() request may succeed at the telephone switch, but the call ends before

the TS.IncomingCall.event can be sent, resulting in the EDU ID being invalidated.

● Various other race conditions may occur at the Telephony Server or EDU Server to

prevent the TS.IncomingCall.event from being issued.

● The Answer() request waits in the queue for preceding requests to be issued, and the

state changes during this time period.

In all cases, the only real guarantee is receiving the TS.IncomingCall.event. Since a
normal response to an Answer() request cannot guarantee that it actually succeeded,
errors are only returned for syntactical problems with the request, or if Telephony returns
an error. If the call no longer exists at the point that VTel processes the request, it is
ignored.

Note:

Note: VTel does not return an error when an answer or hangup fails, because the

information may not be correct or useful.

Issue 2.1 August 2003 27

Communicating with other applications

Using the Ping() method to test the connection

The Ping() method simply echoes a response. This is especially useful during early
development for testing the communication path to VTel. Since this is a non-destructive
internal command, you do not need a valid login. However, since Contact Engine servers
also respond to this command, a valid login allows you to quickly test communication to
both VTel and major Contact Engine servers. For more information about pass-through
requests, see Pass-through requests

During later use, an external application can occasionally use the Ping() method to
validate the connection during periods of low activity, as shown in this example:

[VTel.Ping()][45]
[VTel.Ping.response(,)][45]

on page 44.

28 VTel Programmer Guide

Multiple concurrent telephone calls

VTel allows an agent to handle multiple telephone calls concurrently, subject to the
limitations of the telephone switch. Generally, an agent handles only one telephone call at
a time. In some cases, however, it is useful to have more than one call open in VTel:

● an agent with multiple line appearances places one call on hold while placing another

call for consultation

● an agent with multiple line appearances places one call on hold while answering

another direct call

● an agent continues wrap-up activities after disconnecting a call and another direct call

comes in

An external application must be able to handle multiple simultaneous calls from Avaya
Computer Telephony for IC. The EDU ID uniquely identifies each call and is used to
associate messages with the correct call.

Multiple concurrent telephone calls

Issue 2.1 August 2003 29

Communicating with other applications

Socket usage

Generally, VTel uses three (3) TCP sockets, one each for:

● the Telephony Server

● the EDU Server

● a default Telephony session.

If an agent has more than one phone number, one (1) additional socket is required for each
additional phone number. Socket connections for additional sessions are created and
destroyed as needed.

30 VTel Programmer Guide