Service Client API

From Genesys Documentation
Jump to: navigation, search
This topic is part of the manual Service Client API Reference for version Current of Developer.

Learn how to use the Service Client API to customize the way your web application integrates with Agent Workspace.

Important
Depending on your environment, you might need to contact your Genesys representative to complete the configuration described on this page.

Use the Service Client API to customize how your web application or website integrates with Agent Workspace. This JavaScript API is based on window.postMessage and provides methods your application can use to communicate cross domain with Agent Workspace while maintaining secured isolation.

Getting started

Here's an overview of the steps to access the API:

  1. You have a web application that you've integrated in Agent Workspace. See Enabling integration of web applications in the agent interface.
  2. Download the sample application from GitHub.
  3. Copy the wwe-service-client-api.js file in the sample application to a location your web application can access.
  4. Set configuration options related to security. See Security configuration.
  5. Review Working with the API for more information about how to use the API.
  6. Review the methods and types available in each namespace:
  7. See Common actions with Service Client API for ideas about how to use the API.

Security configuration

The Service Client API involves two parties inside the agent's web browser: the service (the main web page) and the client (in an iframe on the same web page as the service). In order for the client web page to access the API, you need to set a few configuration options to work around web browser security restrictions for cross-origin requests and to enable request limits. You set these options on the WWEWS Cluster application only at the Application level; you can't set these options at the Agent or Agent Group level. Check out the Enabling the Service Client API topic in the Workspace Web Edition Configuration Guide for a full list of the options available to configure the API.

Origin

First, to work around web browser security restrictions set the service-client-api.accepted-web-content-origins option to the domain you want to be able to access to the API. For example, if you want to give access to a web page located at http://my-web-server/path/page.html, then you would set service-client-api.accepted-web-content-origins to http://my-web-server.

If you have several pages that need access to the API and they're located at different domains, you can also provide service-client-api.accepted-web-content-origins with a list. For example: http://my-web-server, http://my-second-web-server, http://my-third-web-server.

Finally, if you want to allow any page to access the API, just set service-client-api.accepted-web-content-origins to *.

You can also set the service-client-api.accepted-web-content-origins option to values that filter by API request, using any of the following keywords:

  • agent.get
  • agent.getState
  • agent.getStateList
  • agent.setState
  • email.create
  • interaction.deleteUserData
  • interaction.getByInteractionId
  • interaction.getInteractions
  • interaction.selectCaseByCaseId
  • interaction.setUserData
  • interaction.singleStepTransfer(interactionId, targetQuery, userData, extensions, succeeded, failed)
  • interaction.singleStepConference(interactionId, targetQuery, userData, extensions, succeeded, failed)
  • interaction.consult(interactionId, targetQuery, userData, extensions, succeeded, failed)
  • interaction.completeTransfer(consultInteractionId, succeeded, failed)
  • interaction.completeConference(consultInteractionId, succeeded, failed)
  • media.getMediaList
  • media.setState
  • voice.dial
  • voice.dialEx(destination, userData, extensions, succeeded, failed)
  • voice.pauseCallRecording
  • voice.resumeCallRecording
  • voice.startCallRecording
  • voice.stopCallRecording

For example, you could set service-client-api.accepted-web-content-origins to http://my-web-server0, http://my-web-server1 (*), http://my-web-server2 (agent.*, voice.dial), http://my-web-server3 (agent.*, interaction.*). In this example, everything is allowed for the http://my-web-server0 and http://my-web-server1. For the http://my-web-server2 domain, only the agent.get, agent.getStateList, agent.setState, agent.getState and voice.dial requests are allowed.

As seen in the example above, you can also filter by wildcards, using the asterisk in parenthesis. For example, http://my-web-server1 (*) or http://my-web-server3 (agent.*, interaction.*).

Rate Limit

You can limit the maximum number of requests per minute on any Service Client API request by setting the service-client-api.rate-limit option. For example, setting the value to 50 would restrict the number of requests to 50 per minute. Set the value to 0 for unlimited requests.

If you want to limit the maximum number of requests per minute on a particular Service Client API request, use service-client-api.rate-limit.<service-name>.

Consider the following sample configuration: 

service-client-api.rate-limit=0
service-client-api.rate-limit.voice.dial=4
service-client-api.rate-limit.email.create=2

In this example, there are no limits globally, but voice.dial requests are limited to 4 requests per minute and email.create requests are limited to 2 requests per minute.

Workspace calculates the limitation as a fixed interval of time, each minute (this is not calculated on a costly sliding window).

When the number of requests reaches the limit, Workspace ignores all further requests of the same type for a configurable period of time, known as the quarantine delay. In response, Workspace Web Edition sends a result with an explicit error message to the first request it receives after the limit is reached: 

{
    "errorMessage": "The rate limit for the request 'voice.dial' has been reached.\nFurther requests of the same type will be ignored for 30 seconds.",
    "request": "agent.getState"
}

To specify the global quarantine delay, set the service-client-api.rate-limit-quarantine-delay option. For example, setting the option to 60 means that Workspace Web Edition ignores requests for 60 seconds after the limit is reached. A value of 0 means that Workspace Web Edition ignores further requests forever, so use this value carefully.

Attached Data Access

Workspace offers two configuration options to limit the read or write access to the key/value pairs in user data:

For example, consider the following configuration: 

service-client-api.user-data.write-allowed=Key1,Key3
service-client-api.user-data.read-allowed=Key1,Key2,Key3

This configuration lets you read the attached data with they keys Key1, Key2, and Key3, but only allows writes on keys Key1, and Key3.

Working with the API

After you've completed the setup and security steps, you're ready to start working with the Service Client API. The first thing you need to do is add a <script> tag to your web application that points to the wwe-service-client-api.js file (remember, you stored it somewhere accessible in Step 3 above).

Now you can access the API through the genesys.wwe.service namespace. For example:
<html>
<head>
<script src="wwe-service-client-api.js"></script>
<script>

function test() {
    genesys.wwe.service.sendMessage({
        request: "agent.get"
    }, function(result) {
        console.debug("SUCCEEDED, result: " + JSON.stringify(result, null, '\t'));
    }, function(result) {
        console.debug("FAILED, result: " + JSON.stringify(result, null, '\t'));
    });
}

function eventHandler(message) {
    console.debug("Event: " + JSON.stringify(message, null, '\t'));
}

genesys.wwe.service.subscribe([ "agent", "interaction" ], eventHandler, this);

</script>
</head>
<body>
Hello world
</body>
</html>
Here's an example of how you could modify attached data:
genesys.wwe.service.interaction.setUserData(
    "1",
    {
        MyKEY1: "MyValue1",
        MyKEY2: "MyValue2"
    }
)
In the above example, the request is interaction.setUserData and the parameters are the interactionId of 1 and the keyValues of MyKEY1 and MyKEY2. All methods provided in the Service Client API are asynchronous, so to get the successful or failed result, just add the matching callback:
genesys.wwe.service.interaction.setUserData(
    "1",
    {
        MyKEY1: "MyValue1",
        MyKEY2: "MyValue2"
    }, 
    function(result){
        console.debug("SUCCEEDED, result: " + JSON.stringify(result, null, '\t'));
    }, 
    function(result){
        console.debug("FAILED, result: " + JSON.stringify(result, null, '\t'));
    }
)
The global template for a service call is:
genesys.wwe.service.<Service name>.<Service function>(<... function parameters ...>, [<optional done() callback>, [<optional fail() callback>]]);
The done() callback is called when a request is successfully sent without an error.

The fail() callback is called when a request generates an error or an exception.

The result of these functions is provided in a JSON object as a unique parameter.

Notifications

Warning
You must call genesys.wwe.service.subscribe only once.
You can use the following code to subscribe to agent and interaction notifications:
function eventHandler(message) {
    console.debug("Event: " + JSON.stringify(message, null, '\t'));
}

genesys.wwe.service.subscribe([ "agent", "interaction" ], eventHandler, context);
In the above example, eventHandler is the event handler function and context is an optional contextual object. Here's an example with an agent STATE_CHANGED to Ready:
{
    "event": "agent",
    "data": {
        "eventType": "STATE_CHANGED",
        "mediaState": "READY"
    }
}
Here's an example with an agent STATE_CHANGED to Not Ready with a reason:
{
    "event": "agent",
    "data": {
        "eventType": "STATE_CHANGED",
        "mediaState": "NOT_READY_ACTION_CODE",
        "reason": "Break",
        "reasonCode": "1511"
    }
}
Finally, here's an example with an ATTACHED_DATA_CHANGED event on a voice interaction:
{
	"event": "interaction",
	"data": {
		"eventType": "ATTACHED_DATA_CHANGED",
		"media": "voice",
		"interaction": {
			"interactionId": "1",
			"caseId": "4dda1ab6-aeab-4a33-f5d0-0153c9fdb43b",
			"userData": {
				"IWAttachedDataInformation": {
					"DispositionCode.Label": "DispositionCode",
					"Option.interaction.case-data.header-foreground-color": "#FFFFFF",
					"CaseDataBusinessAttribute": "CaseData",
					"DispositionCode.Key": "ChooseDisposition",
					"Option.interaction.case-data.frame-color": "#17849D"
				},
				"IW_CaseUid": "4dda1ab6-aeab-4a33-f5d0-0153c9fdb43b",
				"IW_BundleUid": "dfaca66c-4149-42a1-7244-337e949a12b5"
			},
			"parties": [
				{
					"name": "5001"
				}
			],
			"callUuid": "4L6JGNEE9H7DT671FRPTKE6CQ000000G",
			"state": "DIALING",
			"previousState": "UNKNOWN",
			"isConsultation": false,
			"direction": "OUT",
			"callType": "Internal",
			"dnis": "5001",
			"isMainCaseInteraction": true
		}
	}
}

Event Type references

The system eventType field can be one of the following:

eventType Description
CUSTOM_TOAST_BUTTON_CLICK Uses the following parameters:
  • customToastId: The identifier of the toast where the button has been clicked. The identifier is returned by the popupToast method.
  • buttonIndex: The index of the clicked button. The index starts by 0.
REALTIME_CONNECTION Uses the following parameters:
  • state: The attribute can take any of the following values:
    • DISCONNECTED - The real-time connection with the Genesys Web Services server is disconnected.
    • RECONNECTED - The real-time connection with the Genesys Web Services server is established after a disconnection.
    • DOWN - The real-time connection with the Genesys Web Services server is down for more than one minute due to server inactivity. In this situation, we can consider the session as Down.
The interaction eventType field can be one of the following:
eventType Description
Common events to all interaction types
UNKNOWN An unknown event occurs.
ADDED The interaction has been added in the list of interactions.
REMOVED The interaction has been removed from the list of interactions.
ATTACHED_DATA_CHANGED The attached data have changed in the interaction.
CASE_OR_BUNDLE_ID_CHANGED The case or the bundle identifier of this interaction has changed.
CASE_ID_CHANGED The case identifier of this interaction has changed.
NEW_MESSAGE This event represents a new message.
ERROR An error occurs in the interaction.
CONTACT_CHANGED A contact associated with the interaction is fully or partially modified.
Voice events
CALL_RECORDING_STATE_CHANGED The call recording state changed.
DIALING The outbound call starts ringing.
ESTABLISHED The call has been established.
HELD The call has been held.
PARTY_CHANGED The list of party has been changed in the interaction.
RELEASED The call has been released.
RINGING The inbound call starts ringing.
OpenMedia events
ACCEPTED The open media interaction is accepted.
COMPLETED The open media interaction has been completed (Mark as done).
COMPOSING The open media interaction is in composing mode.
CREATED The open media interaction has been created.
INSERT_STANDARD_RESPONSE A standard response has been inserted in the interaction.
INVITED The open media interaction is an invitation.
INVITED_CONFERENCE The open media interaction receive a conference invitation.
IN_QUEUE_FAILED The place in queue has failed.
IN_WORKBIN The interaction has been placed in the work-bin.
IN_WORKBIN_FAILED The place in work-bin has failed.
LEFT_CONFERENCE The open media interaction has left the conference.
PULLED The open media interaction has been pulled from a work-bin.
PULL_FAILED The pull from the queue has failed.
PULL_WORKBIN_FAILED The pull from the work-bin has failed.
REVOKED The open media interaction has been revoked.
TRANSFER_COMPLETED The open media interaction has been transferred and the transfer has been completed.
Chat events (inherit from OpenMedia events)
CANCELED The interaction is already accepted in another chat session.
ENDED The chat has been ended.
JOIN_FAILED The connection with the chat server failed.
JOIN_PENDING The interaction is trying to join the chat session.
Outbound email events (inherit from OpenMedia events)
CANCELLED The outbound email has been cancelled.
SENT The outbound email has been sent.

Outbound events

The Outbound preview events table lists the SCAPI event details for Pull Preview, Push Preview and Direct Push Preview records.

Outbound preview events
Mode UI Event Event Type State Call Type Capabilities
Pull Preview Preview record received ADDED PREVIEWING OUTBOUND_PREVIEW CALL, REJECT_RECORD, CANCEL_RECORD
PREVIEWING PREVIEWING OUTBOUND_PREVIEW CALL, REJECT_RECORD, CANCEL_RECORD
Make call from preview ADDED DIALING OUTBOUND HANGUP
DIALING DIALING OUTBOUND HANGUP
REMOVED IDLE OUTBOUND_PREVIEW -
Release and mark done RELEASED IDLE OUTBOUND MARK_DONE
MARKDONE_APPLY IDLE OUTBOUND MARK_DONE
REMOVED IDLE OUTBOUND -
Reject record STATE_CHANGE REJECTED OUTBOUND_PREVIEW MARK_DONE
Cancel record STATE_CHANGE CANCELED OUTBOUND_PREVIEW MARK_DONE
Regular Push Preview Record received ADDED INVITED OUTBOUND_PUSH_PREVIEW ACCEPT, REJECT
INVITED INVITED OUTBOUND_PUSH_PREVIEW ACCEPT, REJECT
Accepted PREVIEWING PREVIEWING OUTBOUND_PUSH_PREVIEW CALL, REJECT_RECORD, CANCEL_RECORD
Rejected REMOVED REJECTED OUTBOUND_PUSH_PREVIEW -
Make call ADDED DIALING OUTBOUND HANGUP
DIALING DIALING OUTBOUND HANGUP
ESTABLISHED TALKING OUTBOUND HANGUP, HOLD
Release and mark done RELEASED IDLE OUTBOUND MARK_DONE
MARKDONE_APPLY IDLE OUTBOUND MARK_DONE
REMOVED IDLE OUTBOUND_PUSH_PREVIEW MARK_DONE
REMOVED IDLE OUTBOUND -
Reject record STATE_CHANGE REJECTED OUTBOUND_PUSH_PREVIEW MARK_DONE
Cancel record STATE_CHANGE CANCELED OUTBOUND_PUSH_PREVIEW MARK_DONE
Direct Push Preview Record received ADDED INVITED OUTBOUND_PREVIEW ACCEPT, REJECT
INVITED INVITED OUTBOUND_PREVIEW ACCEPT, REJECT
Accepted PREVIEWING PREVIEWING OUTBOUND_PREVIEW CALL, REJECT_RECORD, CANCEL_RECORD
Rejected REMOVED REJECTED OUTBOUND_PREVIEW -
Make call ADDED DIALING OUTBOUND HANGUP
DIALING DIALING OUTBOUND HANGUP
ESTABLISHED TALKING OUTBOUND HANGUP
REMOVED IDLE OUTBOUND_PREVIEW -
Release and mark done RELEASED IDLE OUTBOUND MARK_DONE
MARKDONE_APPLY IDLE OUTBOUND MARK_DONE
REMOVED IDLE OUTBOUND -
Reject record STATE_CHANGE REJECTED OUTBOUND_PREVIEW MARK_DONE
Cancel record STATE_CHANGE CANCELED OUTBOUND_PREVIEW MARK_DONE

The Outbound campaign events table lists the possible events for outbound campaigns.

Outbound campaign events
EventType Trigger Example
CampaignLoaded When an outbound campaign is loaded. 
{
    "event": "outbound",
    "data": {
        "eventType": "CampaignLoaded",
        "campaign": "Offer of the Month"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}
CampaignUnloaded
 When an outbound campaign is unloaded. 
{
    "event": "outbound",
    "data": {
        "eventType": "CampaignUnloaded",
        "campaign": "Offer of the Month"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}
CampaignStarted When an outbound campaign starts. This event also has a "mode" property that describes the mode in which the campaign started.
{
    "event": "outbound",
    "data": {
        "eventType": "CampaignStarted",
        "campaign": "Offer of the Month",
        "mode": "Predictive GVP"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}
CampaignStopped When an outbound campaign stops. 
{
    "event": "outbound",
    "data": {
        "eventType": "CampaignStopped",
        "campaign": "Offer of the Month"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}

Chain of records events

The RECORDS_RETRIEVED event is triggered on an outbound interaction when all of the records in the interaction's chain of records have been retrieved.

Sample response 

{
    "event": "interaction",
    "data": {
        "eventType": "RECORDS_RETRIEVED",
        "interaction": {
            "interactionId": "1",
            "caseId": "a26f59d2-2979-43c5-5c1d-b0757f9ab077",
            "parentInteractionId": null,
            "chainedRecords": [
                {
                    Custom_Character: "c"
                    Custom_Datetime: "2021-03-17 14:42:39"
                    Custom_Float: "16.64"
                    Custom_Integer: 0
                    Custom_String_with_default: "Hi there!           "
                    Custom_VarChar: ""
                    GSW_AGENT_ID: "+33298025000"
                    GSW_APPLICATION_ID: 139
                    GSW_ATTEMPTS: 0
                    GSW_CALLING_LIST: "Calling List Custom"
                    GSW_CALLING_LIST_DBID: 101
                    GSW_CALL_ATTEMPT_GUID: "003DC7H6HG84DBRT1KMIF1TAES000031"
                    GSW_CALL_RESULT: 28
                    GSW_CAMPAIGN_GROUP_DBID: 101
                    GSW_CAMPAIGN_GROUP_DESCRIPTION: ""
                    GSW_CAMPAIGN_GROUP_NAME: "Outbound Campaign Custom@Agent Group Outbound"
                    GSW_CAMPAIGN_NAME: "Outbound Campaign Custom"
                    GSW_CHAIN_ID: 3
                    GSW_CONTACT_MEDIA_TYPE: "voice"
                    GSW_FROM: 0
                    GSW_PHONE: "+33647005"
                    GSW_PHONE_TYPE: 1
                    GSW_RECORD_HANDLE: 283
                    GSW_REFERENCE_ID: 3
                    GSW_SWITCH_DBID: 101
                    GSW_TZ_NAME: "ACT"
                    GSW_TZ_OFFSET: 34200
                    GSW_UNTIL: 86399
                    GSW_USER_EVENT: "PreviewRecord"
                    IW_BundleUid: "27458420-0348-4345-c693-45bd95b5c81f"
                    IW_CaseUid: "a26f59d2-2979-43c5-5c1d-b0757f9ab077"
                    InteractionSubtype: "OutboundNew"
                    InteractionType: "Outbound"
                    WWE_OUTBOUND_CAMP_TYPE: "PreviewRecord"            
                },
                {
                    Custom_Character: "c"
                    Custom_Datetime: "2021-03-17 14:42:32"
                    Custom_Float: "51.69"
                    Custom_Integer: 0
                    Custom_String_with_default: "Hello General Kenobi"
                    Custom_VarChar: ""
                    GSW_AGENT_ID: "+33298025000"
                    GSW_APPLICATION_ID: 139
                    GSW_ATTEMPTS: 0
                    GSW_CALLING_LIST: "Calling List Custom"
                    GSW_CALLING_LIST_DBID: 101
                    GSW_CALL_ATTEMPT_GUID: "003DC7H6HG84DBRT1KMIF1TAES000031"
                    GSW_CALL_RESULT: 28
                    GSW_CAMPAIGN_GROUP_DBID: 101
                    GSW_CAMPAIGN_GROUP_DESCRIPTION: ""
                    GSW_CAMPAIGN_GROUP_NAME: "Outbound Campaign Custom@Agent Group Outbound"
                    GSW_CAMPAIGN_NAME: "Outbound Campaign Custom"
                    GSW_CHAIN_ID: 3
                    GSW_CONTACT_MEDIA_TYPE: "voice"
                    GSW_FROM: 0
                    GSW_PHONE: "+33647004"
                    GSW_PHONE_TYPE: 1
                    GSW_RECORD_HANDLE: 284
                    GSW_REFERENCE_ID: 4
                    GSW_SWITCH_DBID: 101
                    GSW_TZ_NAME: "ACT"
                    GSW_TZ_OFFSET: 34200
                    GSW_UNTIL: 86399
                    GSW_USER_EVENT: "ChainedRecord"
                    InteractionSubtype: "OutboundNew"
                    InteractionType: "Outbound"
                }          
            ],
            "userData": {
                "GSW_PHONE": "+33647005",
                "GSW_PHONE_TYPE": "1",
                "Custom_Character": "c",
                "Custom_Datetime": "2021-03-17 14:42:39",
                "Custom_Float": "16.64",
                "Custom_Integer": "0",
                "Custom_String_with_default": "Hi there!           ",
                "Custom_VarChar": "",
                "GSW_FROM": "0",
                "GSW_UNTIL": "86399",
                "GSW_TZ_OFFSET": "34200",
                "GSW_CALLING_LIST": "Calling List Custom",
                "GSW_CAMPAIGN_NAME": "Outbound Campaign Custom",
                "InteractionType": "Outbound",
                "InteractionSubtype": "OutboundNew",
                "GSW_RECORD_HANDLE": "283",
                "GSW_APPLICATION_ID": "139",
                "GSW_CAMPAIGN_GROUP_DBID": "101",
                "GSW_CALLING_LIST_DBID": "101",
                "GSW_CAMPAIGN_GROUP_NAME": "Outbound Campaign Custom@Agent Group Outbound",
                "GSW_CAMPAIGN_GROUP_DESCRIPTION": "",
                "GSW_CHAIN_ID": "3",
                "GSW_ATTEMPTS": "0",
                "GSW_CALL_RESULT": "28",
                "GSW_TZ_NAME": "ACT",
                "GSW_CALL_ATTEMPT_GUID": "003DC7H6HG84DBRT1KMIF1TAES000031",
                "GSW_CONTACT_MEDIA_TYPE": "voice",
                "GSW_REFERENCE_ID": "3",
                "GSW_SWITCH_DBID": "101",
                "GSW_USER_EVENT": "PreviewRecord",
                "GSW_AGENT_ID": "+33298025000",
                "WWE_OUTBOUND_CAMP_TYPE": "PreviewRecord",
                "IW_BundleUid": "27458420-0348-4345-c693-45bd95b5c81f",
                "IW_CaseUid": "a26f59d2-2979-43c5-5c1d-b0757f9ab077"
            },
            "state": "PREVIEWING",
            "previousState": "UNKNOWN",
            "capabilities": [
                "CALL",
                "REJECT_RECORD",
                "CANCEL_RECORD"
            ],
            "parties": [
                {
                    "name": "+33647005"
                }
            ],
            "startDate": null,
            "endDate": null,
            "callType": "OUTBOUND_PREVIEW",
            "isMainCaseInteraction": true,
            "isCaseSelected": true,
            "isCaseExpanded": false
        }
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}

Common actions with Service Client API

The following sections show some common actions you can perform with Service Client API:

Controlling call recording from a third-party application

Review the following methods for details about call recording control:

The call recording state is stored in the recordingState attribute on the interaction.Interaction object.

Embedding multiple third-party applications in Agent Workspace

You can configure Agent Workspace to include more than one third-party web application, displayed as either a tab, a popup window, in the background at the interaction level, or hidden. Configure the following options:

Updating attached data from a third-party application

Review the following methods for details about updating attached data:

The user data is stored in the userData attribute on the interaction.Interaction object.

You should also set the options related to user data in the Service Client section of Agent Setup or configure the service-client-api.user-data.read-allowed and service-client-api.user-data.write-allowed options.

Enabling click-to-dial from a third-party application

If you configure Agent Workspace to display your web application in a new tab in the Agent Workspace user interface, then the service API only gives access to the dial operation.

Enabling Service Client API to invoke toast in Agent Workspace

Review the following methods for details about enabling and updating toast:

Controlling case selection from a third-party application

Review the following method for details about case selecting control:

The case selection state is stored in the isCaseSelected attribute and the isCaseExpanded attribute on the interaction.Interaction object.

Supporting multiple browser tabs

Service Client API supports multiple browser tabs in a session. The API uses the concept of a leader tab and following tab or tabs. When multiple tabs are open, certain actions (typically automatic) are performed only by the leader tab, such as auto-answer for chat, email, and voice interactions, and contact management in Universal Contact Server. The API also tracks which tab was the last active because some actions are performed only by this tab, such as sounds, toasts, and supervisor-forced log out.

The state of a given browser tab is determined by an internal election process, which can be triggered when an agent closes a leader tab. The state is exposed through the data.frameState property on system events. The frameState property has three possible values:

  • LEADING: The election happened and this tab is the leader.
  • FOLLOWING: The election happened and this tab is a follower.
  • NEGOTIATING: The election is in progress and no tab is a leader or follower until the election is finished.
You can subscribe to system events as follows:
function eventHandler(message) {
  switch (message.event) {
    case 'system':
      log('Received system event: ', JSON.stringify(message, null, '\t'));
      break;
    default:
      break;
  }
}

genesys.wwe.service.subscribe(['system'], eventHandler, this);
When an election is triggered, you should see these types of system events:
Received system event:
{
    "event": "system",
    "data": {
        "frameState": "LEADING"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}
 
Received system event:
{
    "event": "system",
    "data": {
        "frameState": "NEGOTIATING"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}
Service Client API provides some helper functions through the System namespace to determine the state of a tab:

Service Client API updates the attached data for an interaction in the leader tab with a new caseId on eventType CASE_ID_CHANGED. 

{
    "event": "interaction",
    "data": {
        "eventType": "CASE_ID_CHANGED",
        "caseId": "e6470563-af78-4942-657d-976a25dd9de3",
        "previousCaseId": "5f7e5f3a-fb6e-43f3-c404-eaee21d64ef1"
    },
    "userAgent": "WWE Server",
    "protocolVersion": 2
}
Retrieved from "https://all.docs.genesys.com/PEC-Developer/Current/SCAPI/ServiceClientAPI (2024-09-16 10:22:50)"
Comments or questions about this documentation? Contact us for support!