Contents
Voice Interactions
The voice interaction service is the IInteractionVoiceService interface defined in the com.genesyslab.ail.ws.interaction.voice 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 voice interaction service is designed around a set of actions for managing voice interactions. Voice interactions are specific objects representing telephone calls, that is, interactions using the voice media (DNs). Voice interaction features may vary, one from another, depending on the capabilities of the underlying switch.
The voice interaction service manages the following tasks:
-
Creating and dialing a call.
-
Answering a call.
-
Transferring a call.
-
Holding and retrieving a call.
-
Beginning a conference.
-
Activating or deactivating the mute function during a call.
The voice interaction service only performs actions on voice interactions. The voice interaction service depends on the following other services:
-
The event service to subscribe and receive events.
-
The agent service.
-
Before working with voice interactions, your application first must use the agent service to log in an agent on a DN.
-
While the agent is logged on a DN, your application can use the IInteractionVoiceService interface to perform actions on voice interactions associated with the DN.
-
The interaction service:
-
To access IInteractionVoiceService attributes, your application uses the IInteractionService DTO methods.
-
There is no event associated with the IInteractionVoiceService interface: its attributes are published in events of type InteractionEvent which is described in the IInteractionService interface.
-
interaction.voice:ANI—The Automatic Number Identification parameter associated with a voice interaction.
-
interaction.voice:DNIS—The Dialed Number Identification Service parameter associated with a voice interaction.
-
interaction.voice:phoneNumber—The phone number(s) to which this interaction has been connected.
-
interaction.voice:duration—The call duration in seconds.
Voice Interaction Essentials
The IInteractionVoiceService interface exposes methods and pertinent attributes to let your application manage multiple simultaneous voice interactions, each identified by a unique interaction ID.
Each voice interaction follows a sequence of states, for example, beginning in a NEW state, transitioning to a DIALING state, through other states until its state is finally MARKED_DONE.
For any particular state, the voice interaction service permits use of only a small subset of its possible actions (available to your application as method calls). For any one voice interaction, your application may apply only one action at the same time.
After the voice interaction service successfully applies an action with respect to a particular voice interaction, the event service receives an InteractionEvent that carries the interactionId identifying the corresponding voice 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 InteractionEvent event, your application should test various attributes of the IInteractionVoiceService interface, including especially theinteraction.voice:actionsPossible attribute (to determine which actions have become possible to apply).
The following sections present the details behind the above general description.
Voice Attributes
For each voice interaction, the IInteractionVoiceService interface defines a set of attributes which are characteristic of phone call data. The following list is representative (but not exhaustive):
For each voice 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 voice 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 voice interaction.
The IInteractionVoiceService has no methods to read these attributes. Your application must call one of the IInteractionService.getInteractionDTO*() methods. See also Handling Interaction DTOs.
See the Agent Interaction SDK 7.6 Services API Reference for further details.
Voice Actions
The InteractionVoiceAction enumeration defines voice actions of the IInteractionVoiceService
interface. Constants each correspond to one voice interaction service method. For example, the ANSWER_CALL constant corresponds to the IInteractionVoiceService.answerCall() method. Each method call performs an action on one voice interaction. The method call does not apply do a set of interactions.
Possible actions for voice interactions can be accessed by reading the value of the interaction.voice:actionsPossible attribute of the IInteractionVoiceService.
The IInteractionVoiceService has no methods to read attributes. Your application must use one of the InteractionService.getInteractionsDTO*() methods. See also Handling Interaction DTOs.
Voice Interaction Status
The current state of a voice interaction is available as the value of the interaction:status attribute, which is defined in the IInteractionService. For a voice interaction, possible status values are listed in the InteractionStatus enumeration of the com.genesyslab.ws.interaction namespace.
The IInteractionVoiceService has no methods to read attributes. Your application must use one of the InteractionService.getInteractionsDTO*() methods. See also Handling Interaction DTOs.
Status Change
The status of a voice interaction changes if:
-
A successful action is confirmed by an event sent to the server-side application; for example, the held action has been performed on the call so the voice interaction status changes to InteractionStatus.HELD.
-
A CTI event changed it; for example, if a call is no longer dialing but now ringing, the voice interaction status changes to InteractionStatus.RINGING.
The following example diagram shows some transitions between interaction voice statuses.
Switch-Specific
Some statuses are switch-specific and not reachable for those switches for which the feature associated with this status is not available.
For example, if the held feature is not available on a particular switch, theInteractionVoiceAction.HELD action is not available impacting on InteractionStatus.HELD and InteractionStatus.DIALING_HELD
status:
-
If InteractionVoiceAction.HELD is unavailable, the InteractionStatus.HELD and InteractionStatus.DIALING_HELD status are not reachable.
-
Some switches have theInteractionStatus.HELD
feature but do not allow its use during the call dialing, in which case theInteractionStatus.DIALING_HELD status is not reachable.
As the possible statuses, transitions and event workflow differ from one switch to another.
Voice Events
The IInteractionVoiceService has no defined events. All events occurring on a voice interact ion are propagated in InteractionEvent only. Published attributes are IInteractionService attributes as well as those IInteractionVoiceService attributes that have the event property.
Your application must subscribe to a TopicsService defined for the IInteractionService. This TopicsService has to specify in its TopicsEvents the particular voice interaction DTOs to retrieve. Moreover, they must include a trigger on the agent or on the place where the agent is logged in.
The following code snippet shows how to receive InteractionEvent occurring on any interaction belonging to agent0 and how to be sure to have the voice interaction DTOs propagated for a voice interaction event.
TopicsService[] mytopicsServices = new TopicsService[1] ;
/// Defining a Topic Services
mytopicsServices[0] = new TopicsService() ;
mytopicsServices[0].serviceName = "InteractionService" ;
TopicsEvent[] mytopicsEvents = new TopicsEvent[1] ;
mytopicsEvents[0] = new TopicsEvent() ;
/// the targeted events are InteractionEvent
mytopicsEvents[0].eventName = "InteractionEvent" ;
mytopicsEvents[0].attributes = new String[]{ // interaction commons attributes to retrieve "interaction:interactionID", "interaction:status",
"interaction:interactionType", // the entire set of voice interaction attributes is retrieved
"interaction.voice:*"};
/// The InteractionEvent has to concern agent0 interactions
mytopicsEvents[0].triggers = new Topic[1];
mytopicsEvents[0].triggers[0] = new Topic();
mytopicsEvents[0].triggers[0].key = "AGENT";
mytopicsEvents[0].triggers[0].value = “agent0”;
/// ... Subscribe to the event service
See also The Event Service.
TEvent DTOs
An InteractionEvent event received for a voice interaction may correspond to an underlying TEvent coming from the T-Server side. The specific content of these TEvents may be copied in the InteractionEvent.
In this case you can access to T-Event specific attributes (if there are some):
-
interaction.voice:TEventExtensions: KeyValue pairs for TExtensions.
-
interaction.voice:TEventReasons: the reason for this TEvent.
Making and Answering Voice Calls
The most commonly used actions of the IInteractionVoiceService are presented in the following table.
Action |
InteractionVoiceAction |
IInteractionVoiceService |
---|---|---|
Make a call |
MAKE_CALL
|
makeCall()
|
Answer a call |
ANSWER_CALL
|
answerCall() |
Release a call |
RELEASE_CALL
|
releaseCall() |
Mark done a call |
MARK_DONE
|
markDone() |
Your application uses the IInteractionVoiceService
features to send requests to the server-side application to take some actions. After the server-side application (working with the Genesys framework and possibly other Genesys solutions) has performed a corresponding action, the event service receives InteractionEvents if it has subscribed with the correct topics.
An InteractionEvent event propagates status changes for a voice interaction, identified by the interaction:interactionId attribute. Your application should test the interaction.voice:actionsPossible attribute to determine which actions are currently possible to use on this interaction.
The following sections detail commonly used voice interaction actions along with sequence diagrams showing action sequences.
Making a Call
To make a call, your application needs to create a new voice interaction in order to dial the call.
The following sequence diagram presents the creation of a new voice interaction and how to dial a call.
All the InteractionEvent events received by the event service have a STATUS_CHANGED reason, and their labels indicate the current status of the associated voice interaction.
Creating a Voice Interaction
IInteractionVoiceService has two available methods for creating a voice interaction:
-
createInteractionFromPlaceDTO()—creates a voice interaction with a place identifier if:
-
An agent is logged on the place.
-
The place has an available DN to create the interaction.
-
createInteractionFromDnDTO()—creates a voice interaction with a DN identifier if an agent is logged on the DN.
The following code snippet shows a voice interaction created from a DN:
// Setting attributes to retrieve in InteractionVoiceErrorDTO
String[] atts = new String[]{ "interaction:agentId", //the id of the agent owning //the interaction
"interaction:status"}; // the status of the interaction //once created
// Creating the interaction
InteractionVoiceErrorDTO myVoiceErr = myInteractionVoiceService.createInteractionFromDnDTO( myDNID, // DN identifier
atts, // attributes from the creation to retrieve in a DTO
null, // destination number
null, // T-Server to use
null, // call type
null, // attached data
null, // reasons defined by the user
null); // tExtensions
The createInteractionFromDnDTO() method returns an InteractionVoiceErrorDTO object containing:
-
If the interaction is created, the InteractionVoiceErrorDTO.interactionDTO field contains:
-
The interaction ID.
-
The values of the attributes specified in the method call.
-
If the interaction creation failed, the corresponding error is available in the InteractionVoiceErrorDTO.voiceError field.
For example, you can choose to retrieve the interaction:agentId attribute at the time of interaction creation. The following code snippet displays the content of the retrieved InteractionVoiceErrorDTO object:
string myInteractionId=null;
// If an error occurred, displaying the errors
if(myVoiceErr.voiceError!=null)
{
// The creation has failed
System.Console.WriteLine("Creation failed.\n");
// Displaying the telephony error type
System.Console.WriteLine("Telephony Error: " +myVoiceErr.voiceError.telephonyErrorType.ToString() +"\n");
// Displaying the corresponding TServer error
System.Console.WriteLine("TServer Error: " +myVoiceErr.voiceError.TServerError +"\n");
}
else
{
// The creation is successful
System.Console.WriteLine("Creation OK.\n");
// Displaying the interaction id
myInteractionId = myVoiceErr.interactionDTO.interactionId;
System.Console.WriteLine("ID of the created interaction: " + myInteractionId+"\n");
}
Dialing a Call
To dial a call, use the IInteractionVoiceService.makeCall() method and specify the proper voice interaction identifier (interaction:interactionId) as shown in the following snippet.
// There is no attribute to specify before the method call
VoiceError err = myInteractionVoiceService.makeCall( myInteractionId, // voice interaction making the call destination, // phone number to call null, // T-Server to use MakeCallType.REGULAR, null, // attached data null, // reasons defined by the use null); // tExtensions
// If an error occurred, displaying the error
if(err!=null)
{
// The creation has failed
System.Console.WriteLine("Dial failed.\n");
// Displaying the telephony error type
System.Console.WriteLine("Telephony Error: " +err.telephonyErrorType.ToString() +"\n");
// Displaying the corresponding TServer error
System.Console.WriteLine("TServer Error: " +err.TServerError +"\n");
}
Answering a Call
Your application is likely to receive phone calls from external or internal contacts. In such cases, your application receives an InteractionEvent associated with a voice interaction that has a InteractionStatus.RINGING status as shown in the following diagram.
If the interaction.voice:actionsPossible attribute available through that event includes InteractionVoiceAction.ANSWER_CALL as one of its values, your application can call theIInteractionService.answerCall() method as presented in the following code snippet.
// There is no attribute to specify before the method call
VoiceError err = myInteractionVoiceService.answerCall( myInteractionId, // voice interaction making the call
null, // reasons defined by the user
null); // tExtensions
// If an error occurred, displaying the error
if(err!=null)
{
// The creation has failed
System.Console.WriteLine("Answer failed.\n");
// Displaying the telephony error type
System.Console.WriteLine("Telephony Error: " +err.telephonyErrorType.ToString() +"\n");
// Displaying the corresponding TServer error
System.Console.WriteLine("TServer Error: " +err.TServerError +"\n");
}
Terminating a Call
To terminate a call, your application must request two actions:
-
Release the call—The agent releases or the contact hangs up.
-
Mark the call done—The interaction is saved in the contact history and becomes inactive. The IInteractionService and IInteractionVoiceService can no longer access this interaction.
The following diagram shows the actions and InteractionEvent sequence when the agent desktop application hangs up.
If it is the contact that hangs up, the agent desktop application does not have to release.
Releasing the Call
To release the voice interaction, use the IInteractionVoiceService.
releaseCall() method and specify the corresponding voice interaction identifier (interaction:interactionId) as shown in the following code snippet.
VoiceError err = myInteractionVoiceService.releaseCall( myInteractionId, // voice interaction to release null, // reasons defined by the use null); // tExtensions
// If an error occured, displaying the errors
if(err!=null)
{
// The creation has failed
System.Console.WriteLine("Release failed.\n");
// Displaying the telephony error type
System.Console.WriteLine("Telephony Error: " +err.telephonyErrorType.ToString() +"\n");
// Displaying the corresponding TServer error
System.Console.WriteLine("TServer Error: " +err.TServerError +"\n");
}
Marking Done the Call
To mark a voice interaction as done, use the IInteractionVoiceService.
markDone() method and specify the appropriate voice interaction identifier (interaction:interactionId) as shown in the following code snippet.
// voice interaction to mark done
myInteractionVoiceService.markDone(myInteractionId);
Transferring Voice Calls
There are three types of transfer for a voice interaction:
-
Single-step transfer—This transfers the call directly to the agent who takes it over. If this type of Transfer is not available, a mute transfer is done instead.
-
Dual-step transfer—The agent can contact with the Agent receiving the call before completing it.
-
Mute transfer—The transfer is initialized then automatically completed.
These transfers may not be available, depending on the switch in charge of the interaction.
Design your application to test the possible actions provided in the interaction.voice:actionsPossible attribute to determine which transfers are available.
Single-Step and Mute Transfers
The single-step or mute transfers are direct transfers (shown in Direct Transfers) of a voice interaction, and can be performed in one method call.
Type of Transfer |
InteractionVoiceAction |
IInteractionVoiceService |
---|---|---|
Single-Step |
SINGLE_STEP_TRANSFER
|
singleStepTransfer()
|
Mute |
MUTE_TRANSFER
|
muteTransfer()
|
These transfers are performed in a single method call as shown in the following code snippet:
VoiceError err = myInteractionVoiceService.singleStepTransfer( string interactionId,
myDNIdReceivingTheTransfer,
null, // T-Server to use
"the agent reasons for this transfer",
null, //AttachData
null, // reasons defined by the user
null); // tExtensions
If the transfer—either mute or single-step—succeeds:
-
The voice interaction is released and your event service receives an InteractionEvent with InteractionStatus.IDLE.
-
The targeted agent application receives a InteractionEvent for a voice interaction with InteractionStatus.RINGING. This voice interaction is the transferred call.
The Dual-Step Transfer
The dual-step transfer, described in Steps of the Dual-Step Transfer is performed in two IInteractionVoiceService actions:
-
The first agent initiates the transfer by calling the second agent to whom the call is to be transferred.
-
The first agent completes the transfer, its voice interaction is released, and the call is transferred to the second agent, who is able to talk with the contact.
Steps |
InteractionVoiceAction |
IInteractionVoiceService |
---|---|---|
Initiate |
INIT_TRANSFER
|
initiateTransfer() |
Complete |
COMPLETE_TRANSFER
|
completeTransfer() |
Dual-Step InteractionEvent Sequence
The following figure shows the sequence diagram of method calls and InteractionEvent events received during the dual-step transfer.
On Agent1's Side
If Agent1 initiates the transfer, Agent1 deals with two interactions to perform the transfer:
- Call_1 is the original interaction to be transferred existing betweenAgent1 and the contact.
- Call_2 is the voice interaction existing between Agent1 and Agent2.
When Agent1 initiates the transfer, Call_1 is held and Call_2 is created so as to enter Phase 1—Agent1 calling Agent2. The two interactions are released whenAgent1 completes the transfer.
On Agent2's Side
Call_3 is the interaction originally created between Agent2 and Agent1: this interaction receives the transfer once it is completed byAgent1. As a result, Agent2 application receives an InteractionEvent for Call_3:
- The interaction:eventReason attribute is set to InteractionEventReason.INFO_CHANGED.
- The interaction.voice:parties value has changed.
- The interaction:extensions DTO contain extended information about the new party added. See the Agent Interaction SDK 7.6 Services API Reference for further information.
Implementation Example
The following code snippet shows the method implementation for dual-step transfer corresponding to the sequence diagram A Transfer Initiated by the Agent Desktop Application.
/// Agent1 initiates the transfer of Call_1 for Agent2
InteractionVoiceErrorDTO err0 = myInteractionVoiceService.initiateTransferDTO( "Call_1",
"DN_Agent2", // Dn of agent2 who receives the transfer
null, // T-Server to use "the agent reasons for this transfer",
null, // attached data
null, // reasons defined by the user
null, // tExtensions
null); // attributes
//...
/// Agent1 and Agent2 are talking
VoiceError err1 = myInteractionVoiceService.completeTransfer( "Call_1",
null, // reasons defined by the user
null); // tExtensions
Managing Conference Calls
There are two types of conference voice calls:
-
The single-step conference—A single method call performs a conference.
-
The dual-step conference—As with dual-step transfers, one agent first talks to the agent who is going to join the conference, then the first agent completes the conference.
Single-Step Conference
The single-step conference is available only if the InteractionVoiceAction.SINGLE_STEP_CONFERENCE is available in the interaction.voice:actionsPossible
attributes corresponding to the voice interaction.
The following diagram shows the sequence of method calls and received InteractionEvent events for the single-step conference.
The single-step conference is easy to deal with: the second agent receives a ringing voice interaction. If the second agent answers the call, the conference is established.
Your application receives an InteractionEvent event:
- The interaction:eventReason attribute is set to InteractionEventReason.INFO_CHANGED.
- The interaction.voice:parties value has changed.
- Theinteraction:extensions DTO contains extended information about the new party added. See the Agent Interaction SDK 7.6 Services API Reference for further information.
Dual-Step Conference
As with the dual-step transfer, the dual-step conference requires two actions:
-
The first agent initiates the conference by calling the second agent to be included in the conference. If the second agent answers the call, the consultation call starts.
-
The first agent completes the conference; the consultation call ends and the two agents are in conference with the contact.
Steps |
InteractionVoiceAction |
IInteractionVoiceService |
---|---|---|
Initiate |
INIT_CONFERENCE
|
initiateConference() |
Complete |
COMPLETE_CONFERENCE
|
completeConference() |
Dual-Step InteractionEvent Sequence
The following figure shows the sequence diagram showing method calls and InteractionEvent events received during the dual-step conference.
On Agent1's Side
In Dual-Step Conference, Agent1 deals with two interactions to establish the conference:
- Call_1 is the original interaction existing betweenAgent1 and the contact.
- Call_2 is the voice interaction existing between Agent1 and Agent2 who can be talking before entering in conference mode.
When Agent1 initiates the conference, Call_1 is held and Call_2 is created so as to enter Phase 1—Agent1 calling Agent2. When Agent2 answers Call_2, Agent1 and Agent2 are in Phase 2—they are talking.
WhenAgent1 completes the conference:
- Call_2 is released.
- A first InteractionEvent for Call_1 occurs: Call_1 is retrieved, with InteractionStatus.TALKING.
- The new party is added and the conference is established. An InteractionEvent occurs for Call_1:
- The interaction:eventReason attribute is set to InteractionEventReason.INFO_CHANGED.
- The interaction.voice:parties value has changed.
- The interaction:extensions attributes contains extended information about the new party added. See the Agent Interaction SDK 7.6 Services API Reference for further information.
- The interaction:eventReason attribute is set to InteractionEventReason.INFO_CHANGED.
On Agent2's side
Call_3 is the interaction originally created between Agent2 and Agent1 to perform the consultation call. This interaction is part of the conference once Agent1 requests a complete action. As a result, Agent2 application receives an InteractionEvent for Call_3:
- The interaction:eventReason attribute is set to InteractionEventReason.INFO_CHANGED.
- The interaction.voice:parties value has changed.
- The interaction:extensions attribute contains extended information about the new parties added to the interaction. See the Agent Interaction SDK 7.6 Web Services API Reference for further information.
Implementation Example
The following code snippet shows the method implementation for dual-step conference corresponding with Dual-Step Conference.
/// Agent1 initiates the transfer of Call_1 for Agent2
InteractionVoiceErrorDTO err0 = myInteractionVoiceService.initiateConferenceDTO( "Call_1",
"DN_Agent2", // Dn of agent2 who is concerned by the conference
null, // T-Server to use
null, // attached data
null, // reasons defined by the user
null, // tExtensions
null); // Attributes
//...
/// Agent1 and Agent2 are talking
VoiceError err1 = myInteractionVoiceService.completeConference( "Call_1",
null, // reasons defined by the user
null); // tExtensions
Leaving the Conference
When a party leaves a conference, the voice interaction for that party is released. Releasing the Call.
The other parties each receive an InteractionEvent:
-
The interaction:eventReason attribute is set to InteractionEventReason.INFO_CHANGED.
-
The interaction.voice:parties value has changed.
-
The interaction:extensions attribute contains extended information about the changed parties. See the Agent Interaction SDK Services API Reference for further information.
The following code snippet shows how to use the IInteractionVoiceService.leaveConference() method.
/// Agent1, Agent2 and Contact are in conference
// Agent1 is leaving
VoiceError err = myInteractionVoiceService.leaveConference( "Call_1",
null, // reasons defined by the user
null); // tExtensions