Jump to: navigation, search

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.
    • Tip
      See the Agent Service for further details.
  • 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.

    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):

  • 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.

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.

Warning
It is recommended to use callable numbers to access CTI features. See DN Callable Number.

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.    

Generalized Example of a Voice State Diagram (Incomplete)
Warning
This figure is provided as an informative example. It does not include all possible statuses and transitions.

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.

Warning
Do not assume any particular transition sequence. You should base your application design on the status and not on the associated InteractionEventReason of the InteractionEvent received.

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.

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

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.
  • Important
    TEvents attributes are switch-specific. For further information on TEvent, refer to your T-Server documentation.

Making and Answering Voice Calls

The most commonly used actions of the IInteractionVoiceService are presented in the following table.
 

Standard Features for a Voice Interaction

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.

Warning
Do not use the sequence diagrams to make assumptions of possible actions. Your application always should always use the InteractionVoiceAction possible actions provided in DTOs.

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.
 

Making 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.
  • Important
    To test if a voice interaction can be created for an agent on a DN, use the agent:dnsActionsPossible attribute of the IAgentService interface to determine if the AgentDnAction.CREATE_INTERACTION action is possible at this time for this 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
Important
If you specify the destination number of a call in the IInteractionVoiceService.createInteractionFrom*() method parameters, the call is dialed as soon the voice interaction is created. If you do not specify a destination number, the method does not take into account the following parameters: location, call type, attached data, reasons, and T-Extensions.

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.
 

Answering a Call

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.
 

Releasing and Marking Done a Call

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.
 

Direct Transfers

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 of the Dual-Step Transfer

    Steps

    InteractionVoiceAction

    IInteractionVoiceService

    Initiate

    INIT_TRANSFER

    initiateTransfer()

    Complete

    COMPLETE_TRANSFER

    completeTransfer()

    Important
    Steps of the Dual-Step TransferStepsInteractionVoiceActionIInteractionVoiceServiceInitiateINIT_TRANSFERinitiateTransfer()CompleteCOMPLETE_TRANSFERcompleteTransfer()To test if the dual-step transfer is available, the InteractionVoiceAction.INIT_TRANSFER has to be available in the interaction.voice:actionsPossible DTO of the voice interaction.

Dual-Step InteractionEvent Sequence

The following figure shows the sequence diagram of method calls and InteractionEvent events received during the dual-step transfer.
 

A Transfer Initiated by the Agent Desktop Application
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.

Important
To determine if your application can complete the transfer, test if the InteractionVoiceAction.COMPLETE_TRANSFER action is available in the interaction.voice:actionsPossible attribute.
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.
 

Single-Step Conference Sequence

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 of the Dual-Step Conference

Steps

InteractionVoiceAction

IInteractionVoiceService

Initiate

INIT_CONFERENCE

initiateConference()

Complete

COMPLETE_CONFERENCE

completeConference()

Important
To know if the dual-step conference action is possible, the InteractionVoiceAction.INIT_CONFERENCE has to be available in the interaction.voice:actionsPossible attribute of the voice interaction.

Dual-Step InteractionEvent Sequence

The following figure shows the sequence diagram showing method calls and InteractionEvent events received during the dual-step conference.
 

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.
Important
To determine when your application can complete the conference, test if the InteractionVoiceAction.COMPLETE_CONFERENCE is available in the interaction.voice:actionsPossible attributes propagated in InteractionEvent.
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
This page was last edited on January 8, 2014, at 16:22.
Comments or questions about this documentation? Contact us for support!