Revision as of 16:35, May 27, 2015 by Jumunn (talk | contribs)
Jump to: navigation, search

Service Client API

You can use the Service Client API to enable click-to-dial functionality from your web application in Workspace Web Edition. You would typically want to do this if you have integrated a web application in Workspace Web Edition and you want agents to be able to click a phone number in that application and have Workspace Web Edition dial the number. Genesys provides the Client Service API to enable this functionality by allowing your application to access the Workspace Web Edition object model and bypass the cross-domain security limitations.

Here's an overview of the steps you should to follow to use the API:

  1. Your web application is integrated in Workspace Web Edition. See Enabling integration of web applications in the agent interface for details.
  2. You downloaded the sample application: service-client-api.zip
  3. You copied the wwe-service-client-api.js file to a location your web application can access.

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). This raises the issue of

To work around this issue, you need to set a few configuration 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 Service Client API topic in the Workspace Web Edition Configuration Guide for a full list of the options available to configure API.

Origin

Because of the web browser security restriction, for this third party web page to access this API, the option service-client-api.accepted-web-content-origins must be configured in the section "interaction-workspace" of the Workspace Web Edition application. For instance, if you want to give the access to this web page located at the address: http://my-web-server/path/page.html

then, you can set: 

service-client-api.accepted-web-content-origins=http://my-web-server

If several custom web pages must access the API, you can grant the access like the following: 

service-client-api.accepted-web-content-origins=http://my-web-server, http://my-second-web-server, http://my-third-web-server

To allows any web pages to access the API, just set: 

service-client-api.accepted-web-content-origins=*

Rate Limit

The option service-client-api.rate-limit specifies the limit for the maximum number of requests per minute on any service API call. I.e.: In the configuration: 

service-client-api.rate-limit=50

means that globally, every requests are limited to 50 requests / minutes.

0 means unlimited.

When a limit is reached, further requests of the same type will be ignored for a certain period of time (the quarantine delay), and the first request receives a result with an explicit error message: 

{
    "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"
}

You can specify a global quarantine delay, using service-client-api.rate-limit-quarantine-delay, which is 30 seconds by default: 

service-client-api.rate-limit-quarantine-delay=60

means that you need 60 seconds before being able to send a new request!

0 means that anymore requests will be ignored forever!


API Reference

After you've completed the steps above, 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 succeeded(result) { console.debug("SUCCEEDED, result: " + JSON.stringify(result, null, "\t")); }
 
            function failed(result) { console.debug("FAILED, result: " + JSON.stringify(result, null, "\t")); }
 
            function callMe() {
                genesys.wwe.service.voice.dial('+33298000000', succeeded, failed)	
            }
        </script>
    </head>
    <body>
        <a href="javascript:callMe()">Call me</a>
    </body>
</html>

Results Management

All the methods are asynchronous, so to get the succeeded or the failed result, just add the matching callback: 

genesys.wwe.service.voice.dial('+33298000000', function(result){
    console.debug("SUCCEEDED, result: " + JSON.stringify(result, null, '\t'));
}, function(result){
    console.debug("FAILED, result: " + JSON.stringify(result, null, '\t'));
})

Sample of message received when an operation is succeeded: 

{
	"request": "voice.dial",
	"data": {
		"statusCode": 0
	}
}

Sample of message received when the web application isn't authorized to use the API: 

{
	"request": "voice.dial",
	"errorMessage": "The service API denied the access for the origin: http://localhost:8090\nPlease check the option 'service-client-api.accepted-web-content-origins'"
}

System Namespace

Methods

getAllowedServices

<static> getAllowedServices() → {Array.<string>}

Following the security configuration, this service retrieves the list of allowed services.

Returns: An array of allowed services array.

Type: Array.<string>

Voice Namespace

Methods

dial

<static> dial(destination, userData)

Call the destination like it is done from Team Communicator. It supports the Caller ID feature and the 'routing-based' mechanism from the intercommunication features.

Parameters:

Name Type Argument Description
destination string The call destination number.T
userData object <optional> The attached user data key/value object which is updated with each interaction event.
Comments or questions about this documentation? Contact us for support!