Jump to: navigation, search
(Created Fix blank page For Version: HTCC:8.5.2)
 
(Update with the copy of version: 8.5.2DRAFT)
Line 1: Line 1:
<!-- Creation of the fix page -->
+
= Service Client API=
 +
__TOC__
 +
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 [[Documentation:HTCC:IWWDep:SettingUpAgents#Enabling_integration_of_web_applications_in_the_agent_interface|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:
 +
#You have a web application that you've integrated in Workspace Web Edition. See [[Documentation:HTCC:IWWDep:SettingUpAgents#Enabling_integration_of_web_applications_in_the_agent_interface|Enabling integration of web applications in the agent interface]] for details.
 +
#Download the sample application: {{Repository|service-client-api.zip|351abcaf-4621-4796-b5b7-4c1bfd81927f|service-client-api.zip}}.
 +
#Copy the '''wwe-service-client-api.js''' file in the sample application to a location your web application can access.
 +
#Set the options described below in [[ServiceClientAPI#Security_Configuration|Security Configuration]].
 +
#Review [[ServiceClientAPI#Working_with_the_API|Working with the API]] and [[ServiceClientAPI#Methods|Methods]] below for more information 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 [http://en.wikipedia.org/wiki/Same-origin_policy 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 [[Documentation:HTCC:IWWDep:ServiceClientAPI|Service Client API]] topic in the Workspace Web Edition Configuration Guide for a full list of the options available to configure the API.
 +
 
 +
First, set the {{#ppin:{{SectionTransclusion|IWWDep:ServiceClientAPI|service-client-api.accepted-web-content-origins}}|service-client-api.accepted-web-content-origins|||500|210}} 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 <tt><nowiki>http://my-web-server/path/page.html</nowiki></tt>, then you would set '''service-client-api.accepted-web-content-origins''' to <tt><nowiki>http://my-web-server</nowiki></tt>.
 +
 
 +
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: <tt><nowiki>http://my-web-server, http://my-second-web-server, http://my-third-web-server</nowiki></tt>.
 +
 
 +
Finally, if you want to allow ''any'' page to access the API, just set '''service-client-api.accepted-web-content-origins''' to <tt>*</tt>.
 +
 
 +
You can also limit the maximum number of requests per minute on any Service Client API request by setting the {{#ppin:{{SectionTransclusion|IWWDep:ServiceClientAPI|service-client-api.rate-limit}}|service-client-api.rate-limit|||500|210}} option. For example, setting the value to <tt>50</tt> would restrict the number of requests to 50 per minute. Set the value to <tt>0</tt> for unlimited requests.
 +
 
 +
Workspace calculates the API rate limit each minute. This means that after a minute ends, the request counter is reset to 0. For example, if one operation is complete at 19:02:54 and another at 19:03:03, only the second operation is counted because the first happened in the previous minute.
 +
 
 +
When the number of requests reaches the limit, Workspace Web Edition 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:
 +
 
 +
<source lang="javascript">
 +
{
 +
    "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"
 +
}
 +
</source>
 +
 
 +
 
 +
 
 +
To specify the global quarantine delay, set the {{#ppin:{{SectionTransclusion|IWWDep:ServiceClientAPI|service-client-api.rate-limit-quarantine-delay}}|service-client-api.rate-limit-quarantine-delay|||500|220}} option. For example, setting the option to <tt>60</tt> means that Workspace Web Edition ignores requests for 60 seconds after the limit is reached. A value of <tt>0</tt> means that Workspace Web Edition ignores further requests forever, so use this value carefully.
 +
 
 +
==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 <tt><nowiki><script></nowiki></tt> 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:
 +
<source lang="html4strict">
 +
<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>
 +
</source>
 +
 
 +
===Results Management===
 +
All methods provided in the Service Client API are asynchronous, so to get the succeeded or failed result, just add the matching callback:
 +
<source lang="javascript">
 +
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'));
 +
})
 +
</source>
 +
 
 +
The global template for a service call is:
 +
<source lang="javascript">
 +
genesys.wwe.service.<Service name>.<Service function>(<... function parameters ...>, [<optional done() callback>, [<optional fail() callback>]]);
 +
</source>
 +
 
 +
The <tt>done()</tt> callback is called when a request is successfully sent without an error.
 +
 +
The <tt>fail()</tt> 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.
 +
 
 +
Here's an example of the message you receive for a successful operation:
 +
<source lang="javascript">
 +
{
 +
"request": "voice.dial",
 +
"data": {
 +
"statusCode": 0
 +
}
 +
}
 +
</source>
 +
 
 +
Here's an example of the message you receive when the web application isn't authorized to use the API:
 +
<source lang="javascript">
 +
{
 +
"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'"
 +
}
 +
</source>
 +
 
 +
==Methods==
 +
===getAllowedServices===
 +
'''Namespace:''' System <br/>
 +
'''Signature:''' <tt><nowiki><static> getAllowedServices() → {Array.<string>}</nowiki></tt> <br/>
 +
'''Description:''' This method retrieves the list of allowed services, as determined by the security configuration. If the domain of the web application that calls this method isn't listed in the {{#ppin:{{SectionTransclusion|IWWDep:ServiceClientAPI|service-client-api.accepted-web-content-origins}}|service-client-api.accepted-web-content-origins|||500|210}} option, then this method fails. <br/>
 +
'''Returns:''' An array of allowed services array. <br/>
 +
'''Type:''' <nowiki>Array.<string></nowiki>
 +
 
 +
===dial===
 +
'''Namespace:''' Voice <br/>
 +
'''Signature:''' <tt><nowiki><static> dial(destination, userData)</nowiki></tt> <br/>
 +
'''Description:''' Calls the destination in the same way Workspace Web Edition calls the destination from Team Communicator. This methods supports caller ID and the [[Documentation:HTCC:IWWDep:Intercommunication|routing-based intercommunication features]]. <br/>
 +
'''Parameters:'''
 +
{|
 +
! '''Name'''
 +
! '''Type'''
 +
! '''Argument'''
 +
! '''Description'''
 +
|-
 +
| destination
 +
| string
 +
|
 +
| The call destination number.
 +
|-
 +
| userData
 +
| object
 +
| <optional>  
 +
| The attached user data key/value object which is updated with each interaction event.
 +
|}
 +
 
 +
 
 +
[[Category:V:HTCC:8.5.2]]

Revision as of 22:34, June 12, 2015

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. You have a web application that you've integrated in Workspace Web Edition. See Enabling integration of web applications in the agent interface for details.
  2. Download the sample application: service-client-api.zip.
  3. Copy the wwe-service-client-api.js file in the sample application to a location your web application can access.
  4. Set the options described below in Security Configuration.
  5. Review Working with the API and Methods below for more information 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 Service Client API topic in the Workspace Web Edition Configuration Guide for a full list of the options available to configure the API.

First, 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 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.

Workspace calculates the API rate limit each minute. This means that after a minute ends, the request counter is reset to 0. For example, if one operation is complete at 19:02:54 and another at 19:03:03, only the second operation is counted because the first happened in the previous minute.

When the number of requests reaches the limit, Workspace Web Edition 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.

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 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 methods provided in the Service Client API are asynchronous, so to get the succeeded or 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'));
})

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.

Here's an example of the message you receive for a successful operation:

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

Here's an example of the message you receive 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'"
}

Methods

getAllowedServices

Namespace: System
Signature: <static> getAllowedServices() → {Array.<string>}
Description: This method retrieves the list of allowed services, as determined by the security configuration. If the domain of the web application that calls this method isn't listed in the service-client-api.accepted-web-content-origins option, then this method fails.
Returns: An array of allowed services array.
Type: Array.<string>

dial

Namespace: Voice
Signature: <static> dial(destination, userData)
Description: Calls the destination in the same way Workspace Web Edition calls the destination from Team Communicator. This methods supports caller ID and the routing-based intercommunication features.
Parameters:

Name Type Argument Description
destination string The call destination number.
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!