1947_9.PDF

CallCenter@nywhere®

Web Services API User’s Guide

Preliminary Draft

CALLCENTER@NYWHERE USER GUIDE

The software described in this book is furnished under a license agreement and may be used only in accordance with the terms of the agreement.

COPYRIGHT NOTICE

USER GUIDE © 1998-2004 TELEPHONY@WORK, INC.

All Rights Reserved.

Released: 03/04 for CallCenter@nywhere 7.0 [X081R202M043]

All intellectual property rights in the CALLCENTER@NYWHRE USER GUIDE are owned by TELEPHONY@WORK, INC.

and are protected by United States copyright laws, other applicable copyright laws and international treaty provisions.

TELEPHONY@WORK, INC. retains all rights not expressly granted.

This document may not, in whole or in part, be copied, photocopied, reproduced, translated, stored in a retrieval system, reduced to any electronic medium or machine-readable form or transmitted by any means, without prior consent in writing from Telephony@Work, Inc., 4225 Executive Square, Suite 600, La Jolla, CA 92037.

ALL EXAMPLES WITH NAMES, PROJECTS, COMPANY NAMES, OR COMPANIES THAT APPEAR IN THIS MANUAL ARE IMAGINARY AND DO NOT REFER TO, OR PORTRAY, IN NAME OR SUBSTANCE, ANY ACTUAL NAME, PROJECT, COMPANIES, ENTITIES, OR INSTITUTIONS. ANY RESEMBLANCE TO ANY REAL PERSON, PROJECT, COMPANY, ENTITY OR INSTITUTION IS PURELY COINCIDENTAL.

TRADEMARKS

Telephony@Work, the Telephony@Work logo, CallCenter@nywhere, the CallCenter@nywhere logo, Interaction Manager, Supervision Manager, Administration Manager, Network Manager, Mail Manager, Programmers Not Required and Integration-By-Design are the trademarks, service marks and logos of Telephony@Work, Inc. in the United States and other countries. Use of these marks is not permitted without the prior written consent of Telephony@Work, Inc.

Proxy Gateway is a trademark of Funk Software, Inc. Other product names mentioned in this manual may be trademarks or registered trademarks of their respective companies and are the sole property of their respective owners.

DISCLAIMERS

Every effort has been made to ensure the accuracy of this user manual. However, information in this document is subject to change without notice and does not represent a commitment on the part of Telephony@Work, Inc. Telephony@Work, Inc.

provides this information on an “as is” basis and makes no warranties with respect to this documentation and disclaims any implied warranties, including, without limitation, implied warranties of merchantability and fitness for a particular purpose.

Telephony@Work, Inc. shall not be liable for any errors or for incidental or consequential damages in connection with the furnishing, performance, or use of this user manual or the examples herein.

TELEPHONY@WORK, INC. LICENSE AND WARRANTY

NOTICE: IF YOU HAVE SIGNED TELEPHONY@WORK, INC.'S STANDARD FORM SOFTWARE LICENSE

AGREEMENT THEN THE TERMS OF THAT AGREEMENT SHALL GOVERN.

IF TELEPHONY@WORK, INC.'S STANDARD FORM SOFTWARE LICENSE AGREEMENT HAS NOT BEEN SIGNED THEN TELEPHONY@WORK, INC. LICENSES THE ENCLOSED SOFTWARE TO YOU ONLY UPON THE CONDITION THAT YOU PAY ALL SOFTWARE LICENSE FEES AND ACCEPT ALL THE TERMS CONTAINED IN THIS LICENSE AGREEMENT. PLEASE READ THE TERMS CAREFULLY BEFORE OPENING THIS PACKAGE, AS OPENING THE PACKAGE WILL INDICATE YOUR ASSENT TO THEM. IF YOU DO NOT AGREE TO THESE TERMS, THEN TELEPHONY@WORK, INC. IS UNWILLING TO LICENSE THE SOFTWARE TO YOU, IN WHICH EVENT YOU SHOULD RETURN THE FULL PRODUCT WITH PROOF OF PURCHASE TO THE DEALER FROM WHOM IT WAS

ACQUIRED WITHIN THIRTY DAYS OF PURCHASE, AND YOUR MONEY WILL BE REFUNDED.

LICENSE

The software that accompanies this license (the “Software”) is the property of TELEPHONY@WORK, INC. or its licensors and is protected by copyright law. Except as may be modified by a license addendum which accompanies this license, your rights and obligations with respect to the use of this Software are as follows:

You may:

- use one copy of the Software contained on the enclosed CD on a single computer;

-use the Software on a network.

You shall not:

-copy the documentation which accompanies the Software;

-sublicense, rent or lease any portion of the Software;

-copy, reverse engineer, decompile, disassemble, modify, translate, make any attempt to discover the source code of the Software, or create derivative works from the Software; or

-use a previous version or copy of the Software after you have received a disk replacement set or an upgraded version as a replacement of the prior version. Upon upgrading the Software all copies of the prior version must be destroyed unless otherwise agreed in a written document that has been signed by both you and TELEPHONY@WORK, INC.

Any actions by you which violate the terms of this Agreement shall result in the immediate termination of this license with no refund to you of License Fees paid.

LIMITED WARRANTY

TELEPHONY@WORK, INC. warrants that the media on which the Software is distributed will be free from defects for a period of thirty (30) days from the date of delivery of the Software to you. Your sole remedy in the event of a breach of this warranty will be that TELEPHONY@WORK, INC. will replace any defective media returned to TELEPHONY@WORK, INC. within the warranty period. TELEPHONY@WORK, INC. does not warrant that the Software will meet your requirements or that the operation of the Software will be uninterrupted or that the Software will be error-free.

Telephony@Work, Inc., Confidential and Proprietary Information iiiPRELIMINARY DRAFT

THE ABOVE LIMITED WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE

OTHER RIGHTS THAT VARY FROM STATE TO STATE.

DISCLAIMER OF DAMAGES

TELEPHONY@WORK, INC. SHALL NOT BE LIABLE TO YOU FOR INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL DAMAGES OR SIMILAR DAMAGES (INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOST DATA) RELATED TO THIS AGREEMENT OR RESULTING FROM CUSTOMER'S USE OR INABILITY TO USE THE SOFTWARE, ARISING FROM ANY CAUSE OF ACTION WHATSOEVER, INCLUDING CONTRACT, WARRANTY, STRICT LIABILITY, OR NEGLIGENCE, EVEN IF TELEPHONY@WORK, INC. HAS BEEN NOTIFIED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL DAMAGES OR SIMILAR DAMAGES SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT APPLY TO YOU. IN NO CASE SHALL TELEPHONY@WORK, INC.'S LIABILITY EXCEED THE PURCHASE PRICE FOR THE SOFTWARE. The disclaimers and limitations set forth above will apply regardless of whether you accept the Software.

GENERAL

The laws of the State of California will govern this Agreement. This Agreement may only be modified by a license addendum that accompanies this license or a written document that has been signed by both you and TELEPHONY@WORK, INC. Should you have any questions about this Agreement, or if you desire to contact TELEPHONY@WORK, INC. for any reason, please write: Telephony@Work, Inc. Customer Sales, 4225 Executive Square, Suite 600, La Jolla, CA 92037 or call 1-888-854-4224.

iv CallCenter@nywhere - Interaction Manager PRELIMINARY DRAFT

1 Overview of the Web Services API Architecture Organizing a Client Application

Initialization Section The Main Section The Termination Section

Working with Messages Find the Message Group Find the Message Type Get the Message Data

2 How Do I?

Session

How Do I Open a Session and Login?

How Do I Logout an Agent?

How Do I Change an Agent’s Status?

How Do I Re-Open a Session?

How Do I Create a Loop to Parse Messages?

Working with Agent Receiving Agent Messages Sending Agent Requests

Working with Interactions Receiving Interaction Messages Sending Interaction Requests

Data

A Message Groups

A Interaction Messages Types

A Interaction Types

A Interaction States

A Agent Messages

1PRELIMINARY DRAFT

A Language Identifiers

A Phone States

2 CallCenter@nywhere - Interaction Manager PRELIMINARY DRAFT

Overview of the Web Services API 1

Architecture

Organizing a Client Application A typical client application might consist of three sections:

• Initialization

• Main

• Termination or cleanup

Initialization Section

1. Open a Session.

Call the Session.Open( ) method. The client application supplies a username, password, and company alias. Those credentials are validated, a session object is created on the web server and an activity timer is started.

2. Load static data.

Overview of the Web Services API 1-1PRELIMINARY DRAFT

After opening a session most client applications will load some “static” data using the methods in the IWorkgroup, IProject, or other web services. This data might consist of information about a Company, Projects, Workgroups, Agents, Outcomes, Statuses, etc.

• For efficiency, the client application usually loads this data before logging in, although your application can load static data at any time.

• Your application only has to load the data that it requires to perform some task. For example, if your application is a utility used by Agents, you might not want to load company information.

3. Login.

Your client application can login by calling two methods in the IAgent web service:

• getConfiguration( ) getConfiguration( ) allows you to gather important information about the Agent, including their phone type and preferences.

• login( )

After logging in, your application will only get messages that are appropriate for the user credentials that you supplied. For example, if your application logs in with the credentials of a certain Agent, you will only have access to Interactions that have been routed to that Agent.

After logging in you can create and receive Interactions and receive all messages.

The Main Section

The main block of a client application will typically:

1-2 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

• Process user requests that don’t involve the TAW system. For example, your application might allow users to open a corporate intranet site, but this feature doesn’t require access to the TAW web services.

• Receive information from the TAW system. For example, the application might receive a message that there is a new inbound call

• Take some action in the TAW system. For example, your client application might place a new call on hold.

The most important job of the main section is to create an infinite loop that frequently checks (polls) the web service for messages using the IMessageProvider.getMessages method.

Client applications should call getMessages( ) at least once every 30 seconds. If a client application does not check for messages at least once during this time period, the session will be automatically closed.

A good practice is to have an application thread that is dedicated to the job of getting messages. If you don’t create a thread like this, the application might encounter a situation where it must do a lot of local processing (handling user requests that don’t involve TAW features) which could prevent it from checking messages frequently enough.

The Termination Section

The last part of a client application has to close the TAW session and logout by calling the IAgent.logout( ).

Working with Messages Messages announce an event and give you information about the event.

For example, the event might be a new Interaction. Information related to the new Interaction could be the Interaction type, the originator (caller ID or email address), priority, etc.

Overview of the Web Services API 1-3PRELIMINARY DRAFT

At this point your application has logged into the system and you have a dedicated thread with an infinite loop that calls IMessageProvider.getMessages at least every 30 seconds. getMessages( ) returns an object of type SessionMessageResult, which has two important methods:

• getServiceResult( ) returns a ServiceResult object that describes whether the last call to getMessages succeeded or failed. Most objects returned by the API will contain a ServiceResult object.

• An array of SessionMessage objects. By digging into each SessionMessage object, you can find out what events have happened and get all of the important information associated with each event. The rest of this section describes exactly how to do this.

Find the Message Group

CallCenter@nywhere has a lot of different messages, representing a lot of different events. To organize them, related messages are grouped together. For example, there is a group for any type of Interaction message, a group for Agent related messages, etc.

The inifite loop in our client application is constantly calling

IMessageProvider.getMessages( ) which returns a SessionMessageResult object. By calling

SessionMessageResult.getMessages( ) we can get an array of SessionMessage objects that contain all of the messages that were waiting for us on the web server since our last call.

Next we take the first SessionMessage object and call

SessionMessage[i].getGroup( ) which returns a constant that tells us which group the message belongs to (see below for the list of message groups).

1-4 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

Find the Message Type The message group tells you “this message is related to Interactions” or “this message is related to statistics”, but the message type tells you exactly what kind of event occurred. For example, the message group might tell you that some kind of Interaction event occurred, but the message type can tell you that the Interaction is new, or has just ended, or that the wrapup time has just started.

First look at the constant that was returned by

SessionMessage.getGroup( ) and then:

• Call one of the SessionMessage.get<message>( ) methods to retrieve the message object

• Call <message>.getType( )

If SessionMessage.get Group( ) Returns... Call...

GROUP_AGENT SessionMessage.getAgentMessage( ) AgentMessage-> getType( )

GROUP_DATA SessionMessage.getDataMessage DataMessage.getType( )

GROUP_ERROR Error messages are simpler and don’t need a call to getType( ). See below.

GROUP_INTERACTION SessionMessage.getInteractionMessage( ) InteractionMessage.getType( )

GROUP_PHONE_TERMI

NAL

Error messages are simpler and don’t need a call to getType( ). See below.

GROUP_STATISTICS SessionMessage.getStatisticsMessage( ) StatisticsMessage.getType( )

GROUP_UNKNOWN SessionMessage.getUnknownMessage( ) UnknownMessage.getType( )

GROUP_USER SessionMessage.getUserMessage( ) UserMessage.getType( ) Overview of the Web Services API 1-5PRELIMINARY DRAFT

There are two exceptions for calling getType( ).

If SessionMessage.getGroup( ) returns

• GROUP_ERROR or

• GROUP_PHONE_TERMINAL

you don’t need to call a getType( ) method. Actually, neither the ErrorMessage object or the PhoneTerminalMessage object have a getType( ) method.

If SessionMessage.getGroup( ) returns GROUP_ERROR

• call SessionMessage.getErrorMessage( ) which returns an ErrorMessage object. The ErrorMessage object has methods to find all of the information about the error.

If SessionMessage.getGroup( ) returns GROUP_PHONE_TERMINAL

• call SessionMessage.getPhoneTerminalMessage( ) which returns an PhoneTerminalMessage object. The PhoneTerminalMessage object has methods to find all of the information about the phone line.

Get the Message Data

To retrieve the data in a message object, look at the constant that was returned by getType( ) and call the method that will return the “top-level” message object.

Here’s an example for retrieving Interaction messages. In this example:

• SessionMessage.getGroup( ) returned GROUP_INTERACTION, which told us we’re dealing with a message related to Interactions.

• SessionMessage.getInteractionMessage( ) returns an InteractionMessage object.

1-6 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

• InteractionMessage.getType( ) returns one of the following:

Let’s say that our call to InteractionMessage.getType( ) returned TYPE_NEW. Now we know we’re being alerted that a new Interaction has arrived at the call center.

We call InteractionMessage.getInteractionNew( ), which returns an InteractionNew object. Using the methods of the InteractionNew object, we can find all of the information about the new Interaction that we might be interested in, such as the customer’s name, the Project that the customer reached, etc.

(Example)

If InteractionMessage.getType( ) Returns... Call...

TYPE_CHAT_MESSAGE InteractionMessage.getInteractionChatMessage( )

TYPE_CHAT_TRANSFER InteractionMessage.getInteractionChatTransferMessage( )

TYPE_END InteractionMessage.getInteractionEnd( )

TYPE_NEW InteractionMessage.getInteractionNew( )

TYPE_PUSH_URL InteractionMessage.getInteractionPushURL( )

TYPE_SMART_RESPONSE InteractionMessage.getInteractionSmartResponse( )

TYPE_STATE InteractionMessage.getInteractionState( )

TYPE_WRAPUP InteractionMessage.getInteractionWrapup( ) Overview of the Web Services API 1-7PRELIMINARY DRAFT

1-8 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

How Do I? 2

Session

How Do I Open a Session and Login?

// Open the Session private void OpenSession()

Session.SessionOpeningResult OpenResult = m_session.open(system,m_username,m_password);

// Verify that the session opened correctly.

// If the result code is 0, then no errors occurred.

if(OpenResult.serviceResult.resultCode == 0)

// Get session Information m_sessionInformation = OpenResult.sessionInformation;

// Get the session ID m_sessionId = OpenResult.sessionInformation.sessionId;

// Get the user’s configuration.

Agent.UserConfigurationResult getConfigResult = m_agent.getConfiguration(m_sessionId);

// Verify that a valid user configuration object was returned.

How Do I? 2-1PRELIMINARY DRAFT

2-2 if(getConfigResult.serviceResult.resultCode == 0))

// Login to the system m_agent.login(m_sessionId,getConfigResult.userConfigur ation);

// Start a loop that constantly waits for messages.

startMessageLoop();

How Do I Logout an Agent?

private void logoutAgent()

ServiceResult serviceResult = m_agent.logout(m_sessionId);

if (serviceResult.code == 0)

// Agent was logged out successfully.

// close browser or do neccessary update

How Do I Change an Agent’s Status?

// The statusId value is taken from the list of statuses // that is received when the static data is loaded.

private void changeStatus(int statusId)

ServiceResult serviceResult = m_agent.changeStatus(m_sessionId, statusId);

if (serviceResult.code == 0)

// Service result was received without problem

CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

How Do I Re-Open a Session?

private void reOpenSession()

SessionOpeningResult openingResult = m_agent.reOpen(companyAlias,m_username,m_password);

if (openingResult.serviceResult.resultCode == 0)

//Successfully Reopened session // Get session Information m_sessionInformation = OpenResult.sessionInformation;

// Get the session ID m_sessionId = OpenResult.sessionInformation.sessionId;

How Do I Create a Loop to Parse Messages?

// Start a thread to receive messages private void startMessageLoop()

Thread messageThread = new Thread(new ThreadStart(this.getMessages));

messageThread.Name = m_username;

messageThread.Start();

// Create a loop to constantly wait and handle new // messages from the web server.

private void getMessages()

// Get the current request Id to identify the call // to get messages.

int vRequestId = m_sessionInformation.requestId;

How Do I? 2-3PRELIMINARY DRAFT

2-4 while(true)

// Get messages for the current user MessageProvider.GetMessagesResult result = m_messageProvider.getMessages(m_sessionInformation.compan yId,m_sessionInformation.sessionId,m_sessionInformation.p ermissions,vRequestId++);

// Verify the result code if(result.serviceResult.resultCode == 0) // HandleMessages(result.messages);

Thread.Sleep(3000);

// For each message, find the group type, then pass the // message to a routine that can process that message type.

private void HandleMessages(MessageProvider.Message[] avMessages) for(int i =0; i< avMessages.Length; i++) switch(avMessages[i].group) case GROUP_AGENT:

// EVENT_GROUP 1

HandleAgentMessage(avMessages[i].getAgentMessage());

break;

case GROUP_DATA:

// EVENT_GROUP 2

HandleDataMessage(avMessages[i].getDataMessage);

break;

case GROUP_INTERACTION:

// EVENT_GROUP = 3;

HandleInteractionMessage(avMessages[i].getInteractionM essage);

break;

// Code for other message groups goes here.

Working with Agent

Receiving Agent Messages

Interpreting a message gives you basic information about the Agent, such as the Agent’s state and user information. In this section we assume that the message group is GROUP_AGENT (a message type related to Agent.)

After discovering that the message group is an Agent type, you need to find out what type of Agent’s state has changed:

• getGroup( ) told us that this was an Agent message.

• Now we can call getAgentMessage.getType( ) which returns one of the following message types:

Agent Message Type Description

TYPE_SESSION_CHAN

GE

Indicates that a change has occured to the user's session. The included information should be retrieved through the getSessionInformation() method.

TYPE_LOGIN_SUCCESS Indicates that the user successfully logged in the system.

TYPE_LOGIN_AGAIN Indicates that the user should log in the system again.

How Do I? 2-5PRELIMINARY DRAFT

2-6 The client application now knows what kind of Agent state change took place and will usually take some action by sending a request to the Web Server.

TYPE_LOGOUT_BY_SU

PERVISOR

Indicates that the user was logged out by a supervisor.

TYPE_LOGOUT_BY_SE

COND_LOGIN

Indicates that the user was logged out due to another login using the same identity.

TYPE_STATUS Indicates that a change has occured to the agent's status. The included information should be retrieved through the getStatusInformation() method.

TYPE_CONFERENCE Indicates that a change has occured to the agent's conference state. The included information should be retrieved through the getConferenceInformation() method.

TYPE_PREDICTIVE Indicates that a change has occured to the agent's predictive state. The included information should be retrieved through the getPredictiveInformation() method.

TYPE_LBROADCAST_M

ESSAGE

Indicates that the user has received a broadcasted message from another entity in the system

TYPE_AGENTS_STATU

S

Indicates that the user has received the status information of all agents.

TYPE_SUPERVISOR_M

ESSAGE

Indicates that the agent has received a message from the supervisor.

TYPE_MAX_AGENT_LO

GIN_SYSTEM_OVERFL

OW

Indicates an overflow has occured as the maximum number of agents logged in to the system is reached.

TYPE_MAX_AGENT_LO

GIN_COMPANY_OVERF

LOW

Indicates an overflow has occured as the maximum number of agents logged in under a company is reached.

TYPE_AGENT_SESSION

_TIMEOUT

Indicates that the agent will be logged out of the system as the session is timed out.

Agent Message Type Description

The tables below show all of the requests, or actions, that a client application can take on an Agent state change, and which action applies to which message type.

How Do I Handle Agent Messages?

import com.taw.cca.messageprovider.agent.*;

// Handle messages whose *group* type was Agent.

private void HandleAgentMessage(AgentMessage agentMessage)

// Set up a switch statement to take some action based on // the *message* type.

switch(agentMessage.getType()) case TYPE_SESSION_CHANGE :

// Application needs to reopen session();

// See How Do I Re-Open a Session?

break;

case TYPE_LOGIN_SUCCESS:

// Handle Agent Login // See How Do I Open a Session and Login?

break;

case TYPE_LOGOUT_BY_SUPERVISOR:

// Agent is logged out by supervisor.

// See How Do I Logout an Agent?

break;

case TYPE_LOGOUT_BY_SECOND_LOGIN:

// Agent is logged out by supervisor.

// See How Do I Logout an Agent?

break;

case TYPE_STATUS:

// Handle new Agent Status AgentStatusInformation agentStatusInformation = agentMessage.getStatusInformation();

// See How Do I Change an Agent’s Status?

How Do I? 2-7PRELIMINARY DRAFT

2-8 case TYPE_CONFERENCE:

// HANDLE AGENT CONFERENCE INFORMATION.

AgentConferenceInformation agentConferenceInformation = agentMessage.getConferenceInformation();

if (agentConferenceInformation.getIsInConference())

// Agent is in conference. Do something.

break;

case TYPE_LBROADCAST_MESSAGE:

BroadcastMessage broadcastMessage = agentMessage.getbroadcastMessage();

// Receive the Message.

broadcastMessage.getMessage();

// Message sent by broadcastMessage.getPeerId();

break;

case TYPE_AGENTS_STATUS:

// Handle Agents statuses for supervisors // Contains all agents’ status information when user logs // in.

AgentStatusInformation[] agentStatusInformation = avMessage.getAgentsStatusInformation().getAgentsStatusInf ormation();

//Agent Id agentStatusInformation.id //Agent Status agentStatusInformation.statusId break;

case TYPE_AGENT_SESSION_TIMEOUT:

// Handle Agent’s session time out // See How Do I Logout an Agent?

case TYPE_SUPERVISOR_MESSAGE:

// Not implemented in current version

Sending Agent Requests

Agent Request (IAgent) Description login( ) Logs in an agent to the system. The agent can start handling interactions. The session identifier and the user configuration is sent as parameters.

logout( ) Logs out an agent from the system.

The system can call this method when the agent’s session is timed out.

The Agent can no longer handle interactions.

changeStatus( ) The Agent can change change status when logged on to the system. This method provides information on what the agent is currently working on. The administrator can add different statuses for the Agent. The supervisor of the agent can view the current status of the agent.

joinConference( ) Enables an Agent to join conference by passing the conference identifier as a parameter.

leaveConference( ) Enables an Agent to leave the conference by passing the conference identifier as a parameter. The Agent must first join the conference to be able to leave it.

loginToPredictive( ) Enables the Agent to log in to predictive server. The Agent then starts receiving calls from the system.

logoutFromPredictive(

Enables the Agent to log out of the predictive server. The Agent must first be logged on to the predictive server to be a able to log out of it.

setSelectedInteraction(

Sets the interaction which the agent selects.

offHook( ) Indicates that the phone is currently off hook.

onHook( ) Indicates that the phone is currently on hook.

How Do I? 2-9PRELIMINARY DRAFT

2-1 How Do I Make an Agent Join Conference?

// The conferenceId is not valid with the current version as // each agent can participate in only one conference.

mute( ) Indicates that the phone is muted unMute( ) Indicates that the phone is unmuted listenToAgent( ) Enables a supervisor to listen to an agent while the agent is on a call.

whisperToAgent( ) Enables a supervisor to whisper to an agent while the agent is on a call.

HangupAgentLine( ) Enables a supervisor to hang up an Agent’s line while the Agent is on call.

joinAgent( ) Enables a supervisor to join an Agent on an interaction.

startRecordingAgent( ) Enables a supervisor to start recording the conversation of an agent.

stopRecordingAgent( ) Enables a supervisor to stop recording the conversation of an agent.

supervisorTakeOver( ) Enables a supervisor to take over the conversation of an agent.

supervisorLogoutAgent

Enables a supervisor to log out an agent.

setApplicationPreferen ces( )

Configures the agents prefences for the application.

sendBroadcastMessag e( )

Enables the agent to broadcast a message.

sendMessage() Returns the results of the web service request to send a message from the supervisor to the agent.

getAlarms() Returns Alarms set for the supervisor of the agent.

recordVoiceMailPromp t()

Enables the agent to record the voice mail prompt.

getConfiguration() The agent configuration is returned.

Agent Request (IAgent) Description 0 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

// conferenceId can be any integer value with current version.

private void joinConference()

ServiceResult serviceResult = m_agent.joinConference(m_sessionId, -1/*conferenceId*/);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Make an Agent Leave Conference?

// The conferenceId is not valid with the current version as // each agent can participate in only one conference.

// conferenceId can be any integer value with current version.

private void leaveConference()

ServiceResult serviceResult = m_agent.leaveConference(m_sessionId, -1/*conferenceId*/);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Log in an Agent to the Predictive Server?

private void loginToPredictive()

ServiceResult serviceResult = m_agent.loginToPredictive(m_sessionId);

if (serviceResult.getResultCode() == 0)

How Do I? 2-11PRELIMINARY DRAFT

// Service result was received without problem

How Do I Logout an Agent from the Predictive Server?

private void logoutFromPredictive()

ServiceResult serviceResult = m_agent.logoutFromPredictive(m_sessionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Select an Interaction for an Agent?

private void selectInteraction(String interactionId)

ServiceResult serviceResult = m_agent.setSelectedInteraction(m_sessionId, interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Place the Phone Off Hook for an Agent?

private void offHook()

ServiceResult serviceResult = m_agent.offHook(m_sessionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem 2 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

How Do I Place the Phone On Hook for an Agent?

private void onHook()

ServiceResult serviceResult = m_agent.onHook(m_sessionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Mute the Call for an Agent?

private void mute()

ServiceResult serviceResult = m_agent.mute(m_sessionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Unmute the Call for an Agent?

private void unMute()

ServiceResult serviceResult = m_agent.unMute(m_sessionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I? 2-13PRELIMINARY DRAFT

2- How Do I Make the Supervisor Listen to an Agent?

// The agentId value is taken from the list of agents // that is received when the static data is loaded.

private void listenToAgent(int agentId)

ServiceResult serviceResult = m_agent.listenToAgent(m_sessionId, agentId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

Working with Interactions

Receiving Interaction Messages

Interpreting a message gives you basic information about the Interaction, such as the Interaction type and ID. In this section we assume that the message group is GROUP_INTERACTION (a message type related to an Interaction.)

After discovering that the message group is an Interaction, you need to find out what type of Interaction event has occurred:

• getGroup( ) told us that this was an Interaction message.

• Now we can call getInteractionMessage.getType( ) which returns one of the following message types:

14 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

Interaction Message Type See “Interaction Messages Types” on page A-1. Description

TYPE_NEW A new Interaction has occurred. The message has information such as the Interaction type, id, priority, workgroup, etc.

TYPE_WRAPUP Indicates that the wrapup period has started. The client application cannot control calls after wrapup starts. For example, the client application cannot transfer, put on hold, conference, etc. The only call control function that the client application can perform after wrapup begins is to end the wrapup. The client application can still do non-call control actions such as set a note, assign a contact, etc.

TYPE_END The Interaction has ended. Calling InteractionEnd.getReason( ) can tell you if:

• The call was dropped or

• Requires an outcome to be set.

getReason( ) can also return the enum reason_dropped, which indicates that the customer hung up before the Interaction was accepted.

How Do I? 2-15PRELIMINARY DRAFT

TYPE_STATE A message of TYPE_STATE is generated any time that the state of an Interaction changes. For example, when a new call reaches the call center, the Interaction state is Incoming. If an Agent accepts the call, the Interaction state will change to Active and will generate a message of

TYPE_STATE.

The TYPE_STATE message can also indicate that your last attempt to change the state of the Interaction (e.g. from “New” to “On Hold”) failed and that you must change the state of the Interaction in some other way before your change can work. For example, you cannot put a new ACD Call Interaction on hold, you must first accept the Interaction and then put the Interaction on hold.

TYPE_CHAT_TRANSFE

R

Indicates that a Chat Interaction has been transferred to the client application. The message contains the entire text of the chat.

TYPE_CHAT_MESSAGE If your client application has Chat features and the client application recieves a chat message, the text of that message will be in

TYPE_CHAT_MESSAGE.

TYPE_PUSH_URL Indicates that an URL has been pushed to the client application. Basically this message tells the client application that it should display the provided URL.

TYPE_SMART_RESPON

SE

Indicates that the client application has received one or more URLs and scores as the result of an intelligent chat or email scan.

Interaction Message Type See “Interaction Messages Types” on page A-1. Description 6 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

The client application now knows what kind of Interaction took place and will usually take some action by sending a request to the Web Server. The most common actions that the client application would take are to either accept or decline the Interaction.

If the client application declines the Interaction, nothing more needs to be done with that Interaction. ACD Interactions that are declined return to a queue. Direct Inbound calls that are declined go to the user’s voicemail.

If the client application accepts the Interaction, there are other actions (Interaction Requests) that the client application can make during the life of the Interaction. For example, after accepting an Interaction, the client application can send a request to transfer or end the Interaction.

The tables below show all of the requests, or actions, that a client application can take on an Interaction, and which action applies to which message type.

How Do I Handle Interaction Messages?

import com.taw.cca.messageprovider.interactions.*;

// Handle messages whose *group* type was Interaction.

private void HandleInteractionMessage(InteractionMessage interactionMessage)

// Set up a switch statement to take some action based on // the *message* type.

switch(interactionMessage.getType()) case TYPE_NEW:

// See “A new Interaction is received” on page A-1.

//Interaction Id interactionMessage.getInteractionNew().getId();

How Do I? 2-17PRELIMINARY DRAFT interpretInteractionType(interactionMessage.getInteractio nNew().getType());

break;

// End an interaction case TYPE_END:

// See “Interaction Ended” on page A-1.

// Interaction ID interactionMessage.getInteractionEnd().getId();

// See How Do I Disconnect an interaction?

// If outcomes are to be selected see How Do I SetOutcomes?

break;

// Wrap up an interaction after ending it.

case TYPE_WRAPUP :

// See “A wrapup time message is received for interaction” on page A-1.

// Interaction Id interactionMessage.getInteractionWrapup().getId();

// wait for the wrap up time.

int wrapupTime = interactionMessage.getInteractionWrapup().getWrapupTime() // do neccessary updates // See How Do I End Wrapup of an interaction?

break;

// To change the state of an interaction case TYPE_STATE:

// See “A change in interaction State” on page A-1.

interpretInteractionState(interactionMessage.getInteracti onState().getState());

break;

public void interpretInteractionType(int interactionType) 2-18 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT switch(interactionType) case TYPE_UNKNOWN:

// See “Unknown Interaction type” on page A-1.

break;

case TYPE_WORKGROUP_CALL:

// Inbound workgroup call.

// See “Workgroup call” on page A-1.

break;

case TYPE_WORKGROUP_CHAT:

// Inbound Workgroup chat // See “Workgroup Chat” on page A-1.

break;

case TYPE_WORKGROUP_EMAIL:

// Inbound workgroup email // See “Workgroup Email” on page A-1.

break;

case TYPE_WORKGROUP_FAX:

// Inbound workgroup fax // See “Workgroup Fax” on page A-1.

break;

case TYPE_WORKGROUP_CALLBACK:

// Inbound workgroup callback // See “Workgroup Callback” on page A-1.

break;

case TYPE_WORKGROUP_WEB_CALLBACK:

// Inbound workgroup web callback // See “Workgroup web callback” on page A-1.

break;

case TYPE_WORKGROUP_VOICEMAIL:

// See “Workgroup voicemail” on page A-1.

break;

case TYPE_INBOUND_EXTENSION:

// See “Inbound Extension” on page A-1.

break;

case TYPE_OUTBOUND_EXTENSION:

// See “Outbound Extension” on page A-1.

// Do GUI updates, etc;

How Do I? 2-19PRELIMINARY DRAFT case TYPE_INBOUND_CALL:

/* After receiving a new interaction, do GUI and other updates. The user may accept/decline/place on hold/transfer/enter conference/disconnect the interaction. */ case TYPE_OUTBOUND_CALL:

// To make a outbound call, see How Do I Dial a Call?

// Do GUI updates, etc;

/*New interaction: do GUI and other updates. The user may place on hold/transfer/enter conference/disconnect the interaction.

break;

case TYPE_DIRECT_CHAT:

break;

case TYPE_OUTBOUND_EMAIL:

break;

public void interpretInteractionState(int interactionState) switch(interactionState)

// Make an interaction active case STATE_ACTIVE:

// See “Interaction is active” on page A-1.

// An interaction enters the active state(eg., the phone rings).

break;

// To hold a call case STATE_HOLD:

// See “Interaction is on hold” on page A-1.

// do neccessary updates 2-20 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

// See How Do I Place a Call On Hold?

// To send an interaction to voicemail case STATE_VOICEMAIL:

// See “Interaction is in voicemail” on page A-1.

// do neccessary updates // See How Do I Send an Interaction to VoiceMail?

break;

// To send an interaction to a conference case STATE_CONFERENCE:

// See “Interaction is in conference” on page A-1.

// do neccessary updates // See How Do I Send an Interaction to Conference?

break;

case STATE_SELECTING_OUTCOME:

// See “Outcome selection” on page A-1.

// do neccessary updates // See How Do I SetOutcomes?

break;

How Do I? 2-21PRELIMINARY DRAFT

Sending Interaction Requests

Interaction Request (IInteraction) Description accept( ) Used to accept any type of Interaction.

• You can only accept an Interaction if the state is New .

• If the Interaction is an inbound call (ACD or direct inbound) the accept( ) request will fail if the user’s phone is not off-hook.

The client application must accept a new Interaction within a timeout period:

• Calls: The timeout period for any call is the time it takes for the maximum number of rings to occur. For example, you can configure Administration Manager so that the Agent’s phone will ring a certain number of times. The client application must accept the Interaction before this number of rings occurs. The exact amount of time this takes can vary because the length of a ring time varies from country to country.

• ACD Email/ACD voice/ACD Fax: the client application must accept the Interaction within five minutes.

• ACD Chat/ACD Callback/ACD Web Callback: the timeout for these types of interactions is 1 minute.

assignCustomId( ) Associate your own customer ID with an Interaction. This can allow you to integrate features of your own contact system or have a means to find Interactions even if they were never assigned to a TAW Contact.

decline( ) Decline new Interactions of any type. ACD Interactions that are declined will go back to a queue. Direct inbound calls that are declined will be sent to the user’s voicemail.

discard( ) Discard an email Interaction. After calling discard( ), the email Interaction is removed from the system.

2-22 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT disconnect( ) • You must accept an ACD Interaction before you can disconnect it.

• You can decline a call by calling IInteractionControl.decline( ). The Interaction will remain in the queue.

• You can discard a call by calling IInteractionControl.discard( ). The Interaction will be removed from the system.

endWrapup( ) After the client application receives a message indicating that wrapup has begun, the client application can call endWrapup( ) to end the wrapup time.

getSmartRespons e( )

Invokes the smart response algorithm on a given string.

The system will analyse the string and will send a message (InteractionSmartResponse) with the list of possible responses and their scores.

pushUrl( ) Push an URL to a customer during a chat Interaction.

saveNote( ) Associate the text of a note with the current Interaction History.

sendChatMessage

Send a chat message to a customer during an ACD Chat Interaction.

sendDirectChatMe ssage( )

Send a chat message to an Agent or Supervisor during Agent/Supervisor chat. sendDirectChatMessage( ) is not used during an ACD Chat Interaction.

sendToActive( ) Make an Interaction that is currently on hold or in voicemail into the active Interaction.

sendToConferenc e( )

Send the current Interaction into conference mode.

sendToHold( ) Send the current Interaction to Hold. See also sendToActive( ).

sendToVoicemail(

Send the current Interaction to Voicemail. See also sendToActive( ).

• New direct inbound calls (not ACD) can be sent to voicemail without accepting the interaction.

• All type of calls can be send to voicemail after being accepted.

Interaction Request (IInteraction) Description How Do I? 2-23PRELIMINARY DRAFT

How Do I Accept an Interaction?

private void accept(String m_sessionId, String interactionId)

ServiceResult serviceResult = m_interactions.accept(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem setOutcome( ) At the end of call, if required, you can associate an outcome with the interaction by calling Iinteraction.setOutcome( ).

You can look in the userConfiguration object (Iagent.getUserConfiguration( ) ) to find out if the agent is required to set an outcome at the end of an interaction.

startRecording( ) Use Iinteraction.startRecording( ) to start recording a call.

You can look in the userConfiguration object (Iagent.getUserConfiguration( ) ) to find out if the user has recording permissions.

stopRecording( ) Stop recording a call.

transferToExtensi on( )

Transfer any call to any internal extension.

transferToExternal Number( )

Transfer any call to any external number.

transferToH323Ad dress( )

Transfer a call to an IP address using H323 Protocal.

transferToSipAddr ess( )

Transfer a call to a SIP address.

transferToWorkgro up( )

Transfer a chat or call to any Workgroup.

Interaction Request (IInteraction) Description 2-24 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

How Do I Reject an Interaction?

private void decline(String m_sessionId, String interactionId)

ServiceResult serviceResult = m_interactions.decline(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Discard an Email?

private void discard(String m_sessionId, String interactionId)

ServiceResult serviceResult = m_interactions.discard(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I End Wrapup of an interaction?

private void disconnect(String interactionId)

ServiceResult serviceResult = //To end Wrapup m_interactions.endWrapup(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I? 2-25PRELIMINARY DRAFT

How Do I Send an Interaction to Conference?

private void sendToConference(String m_sessionId, String interactionId)

ServiceResult serviceResult = m_interactions.sendToConference(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Send an Interaction to VoiceMail?

private void sendToVoicemail(String m_sessionId, String interactionId)

ServiceResult serviceResult = m_interactions.sendToVoicemail(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Send an Interaction to Active state?

private void sendToActive(String m_sessionId, String interactionId)

ServiceResult serviceResult = m_interactions.sendToActive(m_sessionId,interactionId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

2-26 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

How Do I Dial a Call?

private void dialcall(String m_sessionId, String countryCode, String NumberToDial, int billingProjectId)

// The user can dial an outbound call in one of the // following ways.

// dialExtension // dialExternalNumber // dialSIPAddress // dialH323Address ServiceResult serviceResult = m_interactions.dialxxx(m_sessionId, countryCode, NumberToDial, billingProjectId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Place a Call On Hold?

private void putOnHold(string interactionId)

ServiceResult serviceResult = m_interaction.sendToHold(m_sessionId, interactionId) if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Transfer an Interaction?

private void transfer(String m_sessionId, int transferId, String address, int contactId)

How Do I? 2-27PRELIMINARY DRAFT

//Transferring an interaction can be done in one of the //following ways //transferToExtension //transferToWorkgroup //transferSupervised ServiceResult serviceResult = m_interaction.transferToxxxx(m_sessionId, transferId, contactId);

//OR externally //transferToExternalNumber //transferToSipAddress //transferToH323Address ServiceResult serviceResult = m_interaction.transferToxxxx(m_sessionId, address, contactId);

if (serviceResult.getResultCode() == 0)

// Service result was received without problem

How Do I Disconnect an interaction?

private void hangUp(String interactionId)

ServiceResult serviceResult = m_interactions.disconnect(m_sessionId, interactionId);

if (serviceResult.getResultCode() == 0)

// Interaction disconnected // If outcomes are to be selected see How Do I SetOutcomes?

2-28 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

How Do I SetOutcomes?

private void outcomes(String interactionId, int outcomeId,String outcomeName, int type, int userId, int projectId, int workgroupId, boolean discard)

ServiceResult serviceResult = m_interactions.

setOutcome(m_sessionId, interactionId, outcomeId, outcomeName, type, agentId, projectId, workgroupId, discard);

if (serviceResult.getResultCode() == 0)

// Outcomes selected}

How Do I Retrieve History of an Interaction?

public void getHistory(String interactionId)

InteractionHistoryResult interactionHistoryResult = interactions.getHistory(m_sessionId, interactionId);

if (interactionHistoryResult.getServiceResult().getResultCode() == 0)

// History of Interactions retrieved successfully

InteractionHistory interactionHistory = interactionHistoryResult.getInteractionHistory();

listInteractionActions(interactionHistory);

How Do I Search Interaction History?

public void getInteractionHistoryList(int userId, int projectId, int workgroupId, String originator, How Do I? 2-29PRELIMINARY DRAFT

String from, int fromTime, String to, int toTime, String interactionId, int maxRecords)

InteractionHistoryListResult interactionHistoryListResult = interactions.getInteractionHistoryList(sessionInformation.ge tSessionId(), userId, projectId, workgroupId, originator, from, fromTime, to, toTime, interactionId, maxRecords);

if (interactionHistoryListResult.getServiceResult().getResultCo de() == 0)

InteractionHistory[] interactionHistory = interactionHistoryListResult.getInteractionHistories();

for (int i = 0; i < interactionHistory.length; i++) listInteractionActions(interactionHistory[i]);

How Do I List Interaction Actions?

private void listInteractionActions(InteractionHistory interactionHistory)

// Retrive an array of Interaction actions.

InteractionAction[] interactionActions = interactionHistory.getInteractionActions();

for (int i =0; i < interactionActions.length; i++)

// The sequence id can be used to arrange the history // of interactions.

interactionActions[i].getSequence();

interpretInteractionType(interactionActions[i].getInterac tionType());

// See public void interpretInteractionType(int interactionType) 2-30 CallCenter@nywhere - Web Services API PRELIMINARY DRAFT

// The Action Id determines the type of interaction // action.

switch(interactionActions[i].getActionId()) case HISTORY_ACTION_INTERACTION_OFFERED:

break;

case HISTORY_ACTION_INTERACTION_ANSWERED:

break;

Ending an Interaction

Interactions usually end in one of two ways:

• The customer ends the Interaction (for example, by hanging up their phone). The client application will be alerted when it receives an Interaction message of TYPE_END.

• A client application can end an Interaction by sending a IInteraction.disconnect( ) request.

Regardless of whether the client application or the customer ended the Interaction, the client application may have do some GUI cleanup, e.g., update the screen to indicate that the user’s status is now available. But the client application may also have to set an Outcome.

The call to IAgent.getConfiguration( ), which is usually made during login, tells you if Outcomes are required for the current user.

The client application can set an Outcome by calling IOutcome.setOutcome( ).

How Do I? 2-31PRELIMINARY DRAFT

Data

How Do I Handle Dynamic Data Messages?

// Handle messages whose *group* type was DATA.

private void HandleDataMessage(Data.DataMessage avMessage)

// Set up a switch statement to take some action based on // the *message* type.

switch(avMessage.type) case TYPE_PREVIEW_NEW_CONTACT:

users.UserConfiguration userConfiguration = avMessage.DynamicUserConfiguration;

// Overwrite the users list.

break;

case TYPE_DYNAMIC_CHANGE_COMPANY:

companyConfigurations.CompanyConfiguration companyConfiguration = avMessage.dynamicCompanyConfiguration;

if (companyConfiguration.isDeleted)

// Do GUI updates for company deleted.

else // CompanyConfiguration is updated or added

// Do GUI updates break;

case TYPE_DYNAMIC_CHANGE_USER:

users.User user =…