Chat Interactions

The chat interaction service is the IInteractionChatService interface defined in the com.genesyslab.ail.ws.interaction.chat namespace. To use this service, your application works with classes and enumerations of this namespace, and with the classes and interface of the com.genesyslab.ail.ws.interaction namespace.

Introduction

The chat interaction service is designed around a set of actions for managing chat interactions. A chat interaction is a specific object representing chat message exchanges, that is, a chat session between an agent and other parties through a CHAT medium.
The chat interaction service manages the following tasks:

• Start and stop a chat session through a chat interaction.
  
• Send a message during a chat session.
  
• Transfer a chat interaction.

The chat interaction service performs actions only on chat interactions. The chat interaction service depends on the following other services:

• The event service:
  
  • Your application can receive events with the event service. Events are essentials in chat management.
• The agent service:
  • Before working with chat interactions, your application must first use the agent service to log in an agent on a chat medium.
    
  • While the agent is logged on a chat medium, your application can use the IInteractionChatService interface to perform actions on chat interactions associated with the chat medium. See The Agent Service.
• The interaction service:
  • To access IInteractionChatService attributes, your application uses the IInteractionService DTO methods.
  • Some chat attributes are published in events of type InteractionEvent which is described in the IInteractionService interface. For further information, see The Interaction Service.

Chat Interaction Essentials

The IInteractionChatService interface exposes methods and pertinent attributes to let your application manage multiple chat sessions with a multiple simultaneous chat interactions, each of which is identified by a unique interaction ID.

Each chat interaction follows a sequence of states—for example, beginning in a NEW state, transitioning to a DIALING state, and moving through other states until its final state is MARKED_DONE.

For any particular state, the chat interaction service permits use of only a small subset of its possible actions (available to your application as method calls). For any one chat interaction, your application may apply only one action at the same time.
During a chat session—handled by a particular chat interaction—, your application can use the chat service to send chat messages and manage the chat session.

After the chat interaction service successfully applies an action to a particular chat interaction, the event service can receive an InteractionEvent that carries the interactionId identifying the corresponding chat interaction, along with a variety of attributes reflecting new state (and other data). To receive InteractionEvent events, your application must subscribe to them.

For each incoming chat message, each chat session update, or each successful chat action, the event service may receive a ChatEvent event that can propagate the published chat attribute values in order that your application can take them into consideration. To receive ChatEvent events, your application must subscribe to them.

For each incoming InteractionEvent or ChatEvent event, your application should test various attributes of the IInteractionChatService interface, including especially the interaction.chat:actionsPossible attribute (to determine which actions the application can currently apply).

The following sections present the details behind the above general description.

Chat Interaction Attributes

The IInteractionChatService has no methods to read chat attributes. Your application must call one of the IInteractionService.getInteractionDTO*() methods. See also Opening a Workbin Interaction.

Chat Attributes

For each chat interaction, the IInteractionChatService interface defines a set of attributes that are characteristic of a chat session in the interaction:chat domain. The following list is representative (but not exhaustive):

• interaction.chat:parties—The parties of the session.
• interaction.chat:messages—The list of exchanged messages.
• interaction.chat:messageEvent—Published chat message.
• interaction.chat:duration—The time duration of the chat session in seconds.
• interaction.chat:actionsPossible—Array of chat actions currently possible on a session.

Common Interaction Attributes

For each chat interaction, the attributes of the IInteractionService interface are also available. Your application may often use the following:

• interaction:interactionId—The system interaction identifier, required in calls to the methods of the chat interaction service.
• interaction:status—The interaction status defined with the InteractionStatus enumeration.
• interaction:eventReason—The InteractionEventReason value published when an InteractionEvent event occurs for a chat interaction.

Chat Actions

The InteractionChatAction enumeration defines voice actions of the IInteractionChatService interface. Constants each correspond to one chat interaction service method. For example, the ANSWER_CALL constant corresponds to the IInteractionChatService.answerCall() method.

Important

Each method call performs an action on one chat interaction. The method call does not apply to a set of interactions.

Possible actions for chat interactions can be accessed by reading the value of the interaction.chat:actionsPossible attribute of the IInteractionChatService.
The IInteractionChatService has no methods to read attributes. Your application must use one of the InteractionService.getInteractionsDTO*() methods. See Handling Interaction DTOs.
Changes in possible actions can be propagated in both InteractionEvent and ChatEvent events. See Chat Interaction Events.

Chat Interaction Status

The current state of a chat interaction is available as the value of the interaction:status attribute, which is defined in the IInteractionService. For a chat interaction, possible status values are listed in the InteractionStatus enumeration of the com.genesyslab.ws.interaction namespace.
The IInteractionChatService has no methods to read attributes. Your application must use one of the InteractionService.getInteractionsDTO*() methods. See Handling Interaction DTOs.
The status of a chat interaction may change if a successful action is confirmed by an event sent to the server-side application. For example, if your application successfully answers a ringing chat interaction, the status of the chat interaction changes to InteractionStatus.TALKING. Changes in interaction status are propagated in InteractionEvent events. See Chat Interaction Events.
The following diagram shows the possible interaction statuses for a chat interaction.
 

Example of Possible Transitions due to InteractionEventReason

Warning

This figure is provided as an informative example. It does not include all possible statuses and transitions.

Chat Interaction Events

When changes occur on a chat interaction and involve only the chat management of a chat interaction, the event service of your application receives ChatEvent events.
To properly take into account chat events, the published interaction.chat:eventType attribute value indicates the reason for a chat event. The ChatEventType enumeration lists the possible reasons for an occurring ChatEvent event.
ChatEvent events can propagate any published attribute, that is, any attribute of the interaction.chat domains that has the event property. The eventType attribute indicates attributes to test, as listed in the following table.

Chat Event Types and Attributes

ChatEventType	Attributes	Description
DISCONNECTED	interaction.chat:*	The chat session is terminated.
ERROR_RECEIVED	interaction.chat:*	An error occured.
MESSAGE_RECEIVED	interaction.chat: messageEvent	The messageEvent attribute contain the new incoming chat message.
USER_JOINED	interaction.chat: partyEvent	The partyEvent attribute contains the name of a new party who has joined the session.
USER_LEFT	interaction.chat: partyEvent	The partyEvent attribute contains the name of a party who has left the session.

When changes occur on a chat interaction, the event service of your application may also receive InteractionEvent events. Published attributes are IInteractionService attributes as well as those IInteractionChatService attributes that have the event property. A modification propagated with an InteractionEvent may include changes on that chat interaction’s attributes, for example, interaction.chat:actionsPossible.
Your application must subscribe to the TopicsService objects defined for both IInteractionService and IInteractionChatService. Those TopicsService objects have to specify in their TopicsEvents the DTOs to retrieve. Moreover, they must include a trigger on the agent or on the place where the agent is logged in.

Important

For further details on the InteractionEvent mechanism, see Using IInteractionService.

The following code snippet shows how to receive InteractionEvent and ChatEvent events occurring on any chat interaction belonging to agent0.

 
/// Defining two TopicsService
TopicsService[] myTopicsServices = new TopicsService[2] ;
 
/// Defining a Topic Service for the chat service
myTopicsServices[0] = new TopicsService() ;
myTopicsServices[0].serviceName = "ChatService" ;
/// Defining a topic event
myTopicsServices[0].topicsEvents = new TopicsEvent[1] ;
myTopicsServices[0].topicsEvents[0] = new TopicsEvent() ;
 
/// the targeted events are ChatEvents
myTopicsServices[0].topicsEvents[0].eventName = "ChatEvent" ;
/// all the event attributes values are propagated in event objects
myTopicsServices[0].topicsEvents[0].attributes = new String[]{ "interaction.chat:*"};
/// Triggering ChatEvent for agent0
myTopicsServices[0].topicsEvents[0].triggers = new Topic[1];
myTopicsServices[0].topicsEvents[0].triggers[0] = new Topic();
myTopicsServices[0].topicsEvents[0].triggers[0].key = "AGENT";
myTopicsServices[0].topicsEvents[0].triggers[0].value = "agent0";
 
/// Defining a Topic Service for the interaction service
myTopicsServices[1] = new TopicsService() ;
myTopicsServices[1].serviceName = "InteractionService" ;
 
myTopicsServices[1].topicsEvents = new TopicsEvent[1] ;
myTopicsServices[1].topicsEvents[0] = new TopicsEvent() ;
 
/// the targeted events are InteractionEvent
myTopicsServices[1].topicsEvents[0].eventName = "InteractionEvent" ;
 
/// in case of a chat interaction, the interaction,
/// and chat attributes values are propagated in the Event object
myTopicsServices[1].topicsEvents[0].attributes = new String[]{ "interaction:*", "interaction.chat:*"};
 
/// To receive those events for agent0, your application must
/// trigger events on agent0
myTopicsServices[1].topicsEvents[0].triggers = new Topic[1];
myTopicsServices[1].topicsEvents[0].triggers[0] = new Topic()
myTopicsServices[1].topicsEvents[0].triggers[0].key = "AGENT";
myTopicsServices[1].topicsEvents[0].triggers[0].value = "agent0";
 

For further information about events, see The Event Service.

Managing a Chat Session

Your application uses the chat service to manage chat interactions. Each chat interaction corresponds to a chat session.
To deal with chat interactions, your application must log in an agent on a CHAT medium, and must subscribe to interactions and chat events with the event service (see Chat Interaction Events). When subscribing to those events, your application must trigger on the targeted agent or on the place where its agent is logged.
When a ringing chat interaction occurs on the place, your application must answer the chat interaction to start the chat session. Then your application receives events for chat incoming messages and can send messages with the chat interaction service. To leave the session, your application can release the session and then mark it as done.
The following table presents the corresponding actions to perform on a chat interaction.

Management Actions for a Chat Interaction

Action	InteractionChatAction	IInteractionChatService Methods
Answer a chat interaction	ANSWER_CALL	answer()
Release a chat interaction	RELEASE_CALL	release()
Mark a chat interaction as done	MARK_DONE	markDone()

The following subsections detail these management steps for a chat session.

Answering a Chat Interaction

When a customer requests a chat session, an agent receives a chat interaction in a RINGING status. If the agent successfully answers this chat interaction, he starts a chat session between himself and the customer.
The following figure presents the corresponding sequence diagram involving the chat and event services of your application.
 

Answering a Chat Interaction

The InteractionEvent events received by the event service have a STATUS_CHANGED reason, and their labels indicate the current status of the associated chat interaction.
Retrieve in the received InteractionEvent event the interaction ID and the updated possible actions of the chat interaction. Update your application with the possible chat actions.
If the InteractionChatAction.ANSWER_CALL is available in the interaction’sinteraction.chat:actionsPossible attribute, call the IInteractionChatService.answer() method, as shown in the following code snippet.

 
myInteractionChatService.answer(myInteractionID);

Getting Parties

A party is identified by his or her nickname during the chat session. The ChatParty class associates the party’s information with its nickname. Its fields are the following:

• nickname—A party nickname, used as an identifier during the chat session.
  
• connected—True, if the party is connected.
  
• type—A string for the type of party.
  
• visibility—The chat party’s visibility; a value of the ChatPartyVisibility enumeration.
  

The chat interaction service exposes the parties of a chat session in the interaction.chat:parties attribute of the chat interaction that handles the chat session. This attribute value contains an array of ChatParty objects. For example, your application can retrieve this attribute value with the IInteractionService.getInteractionsDTO() method as shown in the following code snippet.
 

InteractionDTO[] myChatInteractionDTO = myInteractionService.getInteractionsDTO( new string[]{myInteractionId},
new string[]{"interaction.chat:parties"});
 
// The DTO array contains one DT which contains one attribute
/// Getting the parties:
KeyValue myAttrKeyValue = myChatInteractionDTO[0].data[0];
ChatParty[] myParties = (ChatParty[]) myAttrKeyValue.value;
 
/// Displaying information about parties
foreach(ChatParty myParty in myParties)
{
   String connected = "not connected";
   if(myParty.connected)
      connected = "connected";
   System.Console.WriteLine(myParty.nickname +" is " + connected + " (visibility="+ myParty.visibility.ToString()+")\n");
}

Sending Chat Messages

A chat message is a simple string to send. To send the message, call the IInteractionChatService.sendMessage() method as shown in the following code snippet:

 
myInteractionChatService.sendMessage( myInteractionId,//ID of the chat interaction handling the session 
"My message is sent to all parties"); // message to send

Conferences

During a chat session, an agent might invite another agent to join, or an agent or supervisor might want to join. The IInteractionChatService interface offers two methods for this purpose:

• conferenceAgent()—An agent is invited to join by receiving a RINGING chat interaction.
  
• conferencePlace()—A RINGING chat interaction is sent to a place.
  

If an application handling the target (agent or place) answers the RINGING interaction, your application event service receives a ChatEvent event specifying that a user has joined.
Your application specifies what is the visibility of the new invited party in the method call, as shown in the following code snippet.
 

myInteractionChatService.conferenceAgent(
   myInteractionID,// ID of the chat interaction // handling the session to join
   myTargetAgentId, // invited agent
   ChatPartyVisibility.ALL, //visibility if the target agent joins
   "Need information about defects"); // reason for joining

Releasing a Chat Interaction

To leave a chat session, your application must release the chat interaction with the IInteractionChatService.release() method. If the call is successful, the chat interaction’s status changes to InteractionStatus.IDLE as shown in Releasing a Chat Interaction.
 

Releasing a Chat Interaction

To release a chat interaction, call the IInteractionChatService.release() method if the InteractionChatAction.RELEASE_CALL action belongs to the interaction.chat:actionsPossible attribute of the chat interaction:

myInteractionChatService.release(myInteractionId);

Marking a Chat Interaction as Done

When an agent has finished working with a chat session and has released this chat session, he can mark an interaction as done, so that the interaction is saved in the contact’s history.
To mark a chat interaction as done, call the IInteractionChatService.markDone() method if the InteractionChatAction.MARK_DONE action belongs to the interaction.chat:actionsPossible attribute of the chat interaction:

myInteractionChatService.markDone(myInteractionId);

Transferring a Chat Interaction

Your agent application can transfer a chat interaction to another agent or to another place using the chat interaction service. These transfers are direct, that is, in a single step.
If the interaction.chat:actionsPossible attribute of a chat interaction includes the InteractionChatAction.TRANSFER action, your application can use one of the chat service transfer methods detailed in the following subsections.

Transferring to an Agent

Your agent application enable the user to enter the employee ID of the agent to whom the chat interaction should be transferred. In this case, use the IInteractionChatService.transferAgent() method, as shown in the following code snippet:

myInteractionChatService.transferAgent( myInteractionId, myTargetEmployeeId, "A message justifying the interaction transfer");

Transferring to a Place

Your agent application can enable the user to choose a place (having a CHAT medium) to which to transfer the chat interaction. In this case, use the IInteractionChatService.transferPlace() method, as shown in the following code snippet:

myInteractionChatService.transferPlace( myInteractionId, myTargetPlaceId, "A message justifying the interaction transfer");