One of the first things you’ll need to decide is whether to use the APIs directly or use the client libraries. The libraries are designed to simplify how you interact with the API and they take care of a lot of the supporting code needed to make HTTP requests, handle HTTP responses, and enable CometD.

The libraries are available on GitHub in Java and Node.js, which means others can make bug fixes or enhancements that would then be reviewed and approved by Genesys before becoming generally available.

Genesys recommends using the client libraries if possible, but either way you should review the reference documentation for the Authentication API and any other Engage Cloud APIs you plan to use to develop your application.

All Engage Cloud APIs implement and adhere to the OAuth 2 standard for secure authentication. See the Authentication Overview for details.

Many requests in the Engage Cloud APIs are asynchronous. When you send an asynchronous request, the API returns an HTTP response with a status code, but this only means the request was processed and sent to a backend Genesys server. When the server finishes processing the request and notifies the API of any changes in state or errors, the API then sends the updated state or error details to the client application as an unsolicited notification.

The Engage Cloud APIs uses CometD to deliver these unsolicited notifications to clients. CometD is a library that allows the server to deliver messages to a web-based client with low-latency using a variety of transports. The transport used to deliver messages is negotiated between the client and server based on what the client supports running in a particular browser. For more information about CometD, or for details about where to obtain client-side CometD libraries for various platforms, see the official CometD site.

These APIs require CometD to deliver notifications:

• [[PEC-Developer/Current/WebAPIs/Provisioning_API|]]
• Statistics Overview
• [[PEC-Developer/Current/WebAPIs/Workspace_API|]]

Click the links above and review the “CometD” section on the API’s landing page for information about which channels you can subscribe to and the notification you’ll receive.

When an API requires CometD, you’ll see a “Notifications” category in its API reference information (see the Statistics API Notifications page for an example). You can use these endpoints to implement CometD if you aren’t using a client-side CometD library.

The Engage Cloud APIs use the following standard HTTP verbs to perform actions on resources:

Requests support typical parameter types like body, header, path, and query, but there is also a special body parameter called data. This is a JSON object containing any information needed to execute the action. For example, if you POST to /workspace/v3/voice/make-call, you must include a data object with the call destination:

{
    "data":{
       "destination":"5002"
    }
 }

All Engage Cloud APIs return a status JSON object with a required code field. You might also see the message and detail fields, which provide more information about the response. For example:

{
    "status":{
       "code":0
    }
 }

For successful responses, you can expect to see the following codes:

All other status codes indicate an error and include a message, and possibly a detail field, with more information about the problem. For example:

{
    "status":{
       "code":500,
       "message":"Resource not found",
       "detail":{
          "ConfCode":12345
       }
    }
 }

For asynchronous requests, you might also see errors delivered via CometD notifications. For example, the Workspace API returns an EventError message that includes the related DN, along with the error code and message, and the call connection ID and call UUID, if available.

Find the API requests, responses, and details here:

• Authentication API

The Authentication API implements authorization flows described in the OAuth 2.0 standard. OAuth is an authorization framework that enables an external application to obtain limited access to an HTTP service, with the consent of the user.

For this purpose, OAuth makes a clear difference between the external application (referred to as the Client), the user (referred to as the Resource Owner), and the browser (referred to as the User Agent).

For more information about the OAuth 2.0 spec, see: RFC 6749 - The OAuth 2.0 Authorization Framework.

The Authentication API supports the Authorization Code Grant flow defined in OAuth. This is a two-step process:

First, the user authenticates with the Authentication API, using a sign-in form at endpoint /oauth/authorize. After a successful authentication, the client application is returned a short-lived authorization code. The authorization code is conveyed to the client application through an HTTP redirect to a specific URI owned by the client application (redirect_uri) that needs to be pre-configured (see Requirements for details).

Second, the client application exchanges this code for an access token, by using the /oauth/token endpoint, and sending client application credentials. The access token can then be used for making authorized API calls.

The Authorization Code Grant flow is secure and convenient for interactive authentication using web applications that have a server component. That backend component can store client credentials secretly, and take charge of exchanging the authorization code for an access token.

For more information about the Authorization Code Grant flow, see: RFC 6749 - The OAuth 2.0 Authorization Framework - Authorization Code Grant.

You will need the following data for accessing the Authentication API:

• API Base URL — Where your client can find the API.
• API Key — You must send this as the value for x-api-key header of every request.
• Client credentials — Credentials for your client application, a Client ID and a Client Password.
• User credentials — Credentials of a user that wants to make use of API functions.

You can request API Key and Client Credentials for your cloud tenant from Genesys Customer Care. From your side, you need to provide the following data:

• Allowed OAuth Redirect URIs — During an Authorization Code Grant, the client’s browser is redirected to this URI after entering valid credentials. The client application must implement an endpoint at this URI that receives the authorization code and completes the flow. The Redirect URI must adhere to RFC 6749 Section 3.1.2. In particular, it must be an absolute URI that does not include a fragment component.
• Allowed CORS Origins (See Cross-Origin Resource Sharing) — If you are calling APIs from a web application, you may need to allow API access to your application, for the browser to permit cross-domain requests.

The user navigates to the /oauth/authorize endpoint, which displays a sign-in form. It is up to the client to decide how the user navigates to the sign-in page. It can happen by direct navigation, or through an HTTP redirect, or inside an embedded frame or popup window.

The /oauth/authorize URL must contain query parameters defined by OAuth. For example:

GET /auth/v3/oauth/authorize?response_type=code&client_id=&state=70db3ab252ead1dd&redirect_uri=https://yourapp.com/oauthcallback

After a successful sign-in, the Authentication Server conveys the authorization code to your client application. To do this, it redirects the browser to the provided Redirect URI, and adds a query parameter that contains the authorization code. For example, the HTTP redirect response may look like this:

HTTP/1.1 302 Found
 Location: https://yourapp.com/oauthcallback&code=ABCXYZ&state=70db3ab252ead1dd

After checking the state value, your application can exchange the authorization code for an access token, by using the /oauth/token endpoint. You must provide client credentials through HTTP basic access authentication. For example:

POST /auth/v3/oauth/token
 Authorization: Basic 
 Content-Type: application/x-www-form-urlencoded
 
 grant_type=authorization_code&code=ABCXYZ
 &redirect_uri=https://yourapp.com/oauthcallback

Again, the redirect_uri must be URL-encoded.

Finally, the Authentication API returns an access token to your client application, inside a JSON response. For example:

HTTP/1.1 200 OK
 Content-Type': application/json;charset=utf-8
 Cache-Control': no-store
 Pragma: no-cache
 
 {'access_token': '1234abcd-5569-4fa9-bfad-12345678abcd',
  'expires_in': 43199,
  'refresh_token': '456789ef-3dce-4c82-bc1f-987654324e87',
  'scope': '*',
  'token_type': 'bearer'}

Once your client application has the access token, it can access the APIs by including the token inside the Authorization header of HTTP requests to API endpoints.

Authorization: Bearer 1234abcd-5569-4fa9-bfad-12345678abcd

An access token is valid for a certain time. Once the access token expires, if your application obtained a refresh token, your application may use it to obtain a new access token, as described in OAuth 2.0 - Refreshing an Access Token.

If an application token is expired or invalid, the API returns the HTTP status code 401. This lets the application know it must get a new access token.

Review the error messages below to see solutions for common troubleshooting scenarios.

HTTP/1.1 403 Forbidden
 {'message': 'Forbidden'}

If you get this response from any API endpoint, you are probably using an invalid API Key in your x-api-key request header.

HTTP/1.1 401 Unauthorized
 {'error': 'Unauthorized', 'error_description': 'Bad credentials'}

If you get this response from the /oauth/token endpoint, you are probably using invalid client credentials. Check you Client ID and Client Password.

HTTP/1.1 400 Bad Request
 {'error': 'invalid_grant', 'error_description': 'Bad credentials'}

If you get this response from the /oauth/token endpoint, you are probably using invalid user credentials. Check you user name and password.

Genesys also offers client libraries for the Authentication API in both Node.js and Java. These libraries may help you start up quicker, as they take care of a lot of the supporting code needed to make the proper HTTP requests and handle HTTP responses.

HTTP Basic access authentication has been intentionally disabled. While basic authentication is the simplest way to authenticate a user, it does not provide the security benefits of OAuth. There are a few key security concerns with basic auth:

• A hash of the user’s username and password are sent with every request; this increases the exposure of sensitive data.
• The basic auth hash value never expires, so anyone intercepting that value will gain access to the account until the user’s password is changed.
• When using basic authentication, the user must provide their account credentials directly to the application, which means that something other than the user themselves and the Authentication API have direct access to their account credentials.

Some of the CDDS features you can add to your applications include:

• create a manual data export job
• download exported data file
• clone a manual export job
• view a list of jobs/files
• cancel a job
• delete a job/file

Currently, CDDS only supports the export and download of contacts and interaction-based data sourced from Universal Contact Server (UCS).

Find the API requests, responses, and details here:

• Cloud Data Download Service API

Make sure to check out the Introduction to Engage Cloud APIs page for more information about core concepts in the Engage Cloud APIs, such as requests, responses, and CometD notifications.

The webhook is delivered as a POST request. Digital Channels expects the third-party system to respond with 200 OK. If the third-party system doesn’t respond with 200 OK or is not available, Digital Channels will try to redeliver the webhook according to the configuration for retry timeout and retry attempts. Contact your Genesys representative for details about this configuration.

The webhook POST request contains an X-Hub-Signature header with the SHA1 signature of the post payload. The signature is calculated using the keyed-hash message authentication code (HMAC), where the key is the app secret. The signature is then prefixed with sha1=. The third-party system should verify this signature to validate the integrity and origin of the payload.

Find the API requests, responses, and details here:

• Interactions Webhook

Make sure to check out the Introduction to Engage Cloud APIs page for more information about core concepts in the Engage Cloud APIs, such as requests and responses.

Find the API requests, responses, and details here:

• Secure Email API

Make sure to check out the Introduction to Engage Cloud APIs page for more information about core concepts in the Engage Cloud APIs, such as requests and responses.

You can work with the API in two modes:

1. Create a subscription and receive notifications. This is the preferred approach if you need up-to-date information over a period of time. When you create a subscription, you can start receiving calculated statistics. These statistics are either pre-configured for your account/contact center and or come from the definitions you provided in the request.
2. Get the current values of statistics without a subscription. This is useful if your client can’t maintain a CometD connection or if your application requires this information only once. This API works with statistics that are pre-configured for your contact center.

The Statistics API is divided into the following categories:

• Requests (/statistics) — Subscribe to statistics, unsubscribe from statistics, and get the current value of statistics without a subscription.
• Notifications (/notifications) — Implements CometD channels for statistics notifications.

Find the API requests, responses, and details here:

• Statistics API
• Statistics Notifications API

Genesys also offers client libraries for the Statistics API in both Node.js and Java. These libraries simplify how you interact with the API and they take care of a lot of the supporting code needed to make HTTP requests and enable CometD. Genesys recommends using the client libraries if possible. For help deciding if you should use them, check out the Getting Started page.

There are also some Statistics tutorials that demonstrate how to use the client libraries. See Tutorials for details.

In order to initialize and use the Statistics API, you first need to authenticate with the Authentication Client Library or the Authentication API.

You can get the current value of predefined statistics from Stat Server without a subscription by making a POST request to /statistics/v3/operations/get-statistic-ex.

This operation has just one mandatory body parameter called statistics.

Sample request

POST to /statistics/v3/operations/get-statistic-ex

Here’s the JSON body included with the above request:

{
    "data":{
       "statistics":[
          {
             "name":"CurrentAgentState",
             "objectType":"Agent",
             "objectId":"agent2"
          },
          {
             "name":"TimeInCurrentState",
             "objectType":"Agent",
             "objectId":"agent2"
          }
       ]
    }
 }

Sample JSON response body

{
    "status":{
       "code":0
    },
    "data":{
       "statistics":[
          {
             "name":"CurrentAgentState",
             "objectType":"Agent",
             "objectId":"agent2",
             "value":{
                ...
             },
             "timestamp":1490830620000
          },
          {
             "name":"TimeInCurrentState",
             "objectType":"Agent",
             "objectId":"agent2",
             "value":{
                ...
             },
             "timestamp":1490830620000
          }
       ]
    }
 }

You can also use an API call to get the current value of one valid statistic from Stat Server by making a GET request to /statistics/v3/statistic-values/{statisticName}.

This request accepts two mandatory query parameters, objectType and objectId.

Sample request

GET /statistics/v3/statistic-values/{statisticName}?objectType=XXX&objectId=YYY

Sample JSON response body

 {
    "status":{
       "code":0
    },
    "data":{
       "statistic":{
          "value":{
             ...
          },
          "timestamp":1490830620000
       }
    }
 }

To create a subscription, POST to the following path: /statistics/v3/subscriptions

This POST allows an optional query parameter verbose= and the body is JSON with the operationId and data parameters.

Sample request

POST to /statistics/v3/subscriptions

Here’s the JSON body included with the above request:

{
    "operationId":"UUID1",
    "data":{
       "statistics":[
          {
             "statisticId":"UUID2",
             "objectId":"agent",
             "objectType":"Agent",
             "name":"AverageHandlingTime"
          },
          {
             "statisticId":"UUID3",
             "objectId":"agent",
             "objectType":"Agent",
             "definition":{
                "notificationMode":"Periodical",
                "notificationFrequency":10,
                "insensitivity":1,
                "category":"TotalAdjustedTime",
                "subject":"DNStatus",
                "intervalType":"GrowingWindow",
                "mainMask":"WaitForNextCall",
                "dynamicTimeProfile":"00:00",
                "dynamicFilter":"Media=voice",
                "maskType":"DN"
             }
          }
       ]
    }
 }

In the above sample, AverageHandlingTime references the corresponding statistic (pre-configured) for the given contact center.

Sample JSON response body

 {
    "status":{
       "code":0
    },
    "data":{
       "subscriptionId":"UUID1",
       "operationId":"UUID1",
       "statistics":[
          {
             "statisticId":"UUID2",
             "objectId":"agent",
             "objectType":"Agent",
             "name":"AverageHandlingTime",
             "value":{
                ...
             },
             "timestamp":1490830620000
          },
          {
             "statisticId":"UUID3",
             "objectId":"agent",
             "objectType":"Agent",
             "value":{
                ...
             },
             "timestamp":1490830620000
          }
       ]
    }
 }

In the above sample:

• The status code is 0 because this is synchronous operation.
• The subscriptionId is filled from the operationId.

To retrieve the values of a set of statistics that was opened within a subscription, you need to make a GET request to the following path: /subscriptions/{id}/statistic-values

The GET allows two optional query parameters,verbose= and statisticIds=.

Sample request

GET /statistics/v3/subscriptions/UUID1/statistic-values

Sample JSON response body

{
    "status":{
       "code":0
    },
    "data":{
       "subscriptionId":"UUID1",
       "statistics":[
          {
             "statisticId":"UUID2",
             "objectId":"agent",
             "objectType":"Agent",
             "name":"AverageHandlingTime",
             "value":{
                ...
             },
             "timestamp":1490830620000
          },
          {
             "statisticId":"UUID3",
             "objectId":"agent",
             "objectType":"Agent",
             "value":{
                ...
             },
             "timestamp":1490830620000
          }
       ]
    }
 }

In the above sample:

• The status code is 0 because this is synchronous operation.

You can delete a subscription by sending a DELETE request to the following path: /statistics/v3/subscriptions/{id}. This closes all statistics associated with the specified subscription. It’s a fire-and-forget operation that always returns a success response.

You can subscribe to CometD notifications about service state and statistic value updates for statistics in your subscription.

Statistic value updates

Notification topic: /statistics/v3/updates

Notification sample:

{
    "name":"StatisticUpdate",
    "topic":"/statistics/v3/updates",
    "data":{
       "statistics":[
          {
             "subscriptionId":"UUID1",
             "statisticId":"UUID2",
             "value":{
                ...
             },
             "timestamp":1490830620000
          }
       ]
    }
 }

Where:

• subscriptionId - The ID of the subscription the statistic is associated with.
• statisticId - The ID of the statistic.
• value - The value of the statistic.
• timestamp - The time the statistic was generated (provided by Stat Server).

Service state

If the Statistics service is unable to connect to internal server(s) it needs to communicate with, it notifies subscribers with a ServiceStateChange message where the serviceState is UNAVAILABLE. When this happens, the Statistics service drops all subscriptions, so you’ll need to re-create your subscriptions when the service is available again.

Notification topic: /statistics/v3/service

Notification sample:

Service is unavailable

{
    "data":{
       "serviceState":"UNAVAILABLE"
    },
    "name":"ServiceStateChange",
    "topic":"/statistics/v3/service"
}

Service is available again

{
    "data":{
       "serviceState":"AVAILABLE"
    },
    "name":"ServiceStateChange",
    "topic":"statistics/v3/service"
}

Once workitems are submitted to Genesys through the API, you can use other Genesys applications to route them to agents, get interactions that were processed by agents, and view reports about those interactions. See the overview documentation on the PureEngage Docs site for details about Task Routing and how you should use this API as part of the larger solution.

Find the API requests, responses, and details here:

• Openmedia API

Make sure to check out the Introduction to Engage Cloud APIs page for more information about core concepts in the Engage Cloud APIs, such as requests and responses.