Getting Started with Our APIs

Genesys Cloud

Suggest Edits

Integration Description

In order to capture audio and provide call guidance to customer agents/representatives Cogito integrates with the Genesys Cloud CX environment via APIs. It receives Call Events from the Genesys Cloud Notification Service API and utilizes Genesys AudioHook API for real time audio feeds.

The Genesys Cloud AudioHook API provides Cogito with a direct audio feed from the Genesys Cloud environment.

  • AudioHook is supported with Genesys Cloud Voice and with BYOC Cloud deployment models.

AudioHook is currently not supported with BYOC Premise (Genesys Cloud Premise Edges deployed locally).

  • AudioHook requires Genesys Cloud Voice Transcription to be enabled.

Voice Transcription is currently only supported in the Genesys CX3 license model. Support for the CX2 license model is also available with WEM AddOn.

  • Genesys Cloud should be consulted to confirm the AudioHook Monitor availability.

Please refer to existing Genesys documentation on AudioHook at https://help.mypurecloud.com/articles/about-the-audiohook-integration/ for more information.

Call Flow

Direct Call Termination

  • Calls flow directly into the Genesys Cloud environment.
  • AudioHook required.

Integration Points

Call Audio Options

Genesys AudioHook API

  • Call Audio (media) is delivered to Cogito via the Genesys Cloud AudioHook API feature.
  • Connectivity is established from Genesys Cloud to Cogito Websocket endpoint hosted by AWS ALB.
  • The Open message from the client contains a parameter "conversationId" which is used to match to the CTI Events CallID field.
  • When a matching Agent Call Event is received, Cogito accepts the webhook session from AudioHook and begins processing the call audio.
  • Endpoint address is provided by Cogito.

Call Events: Genesys Cloud Notification service

  • Call Events such as call start, hold, and resume will be sent via the Genesys Cloud Notification Service API to the Cogito CTI-Tracker client.
  • Connectivity is established via OAuth with “Client ID” and “Client Secret” provided by the Customer.
  • Cogito requests will be serviced by the region-specific API in Genesys cloud. For example, if Genesys environment is located in AWS us_west_2 region - the API endpoint would be https://api.usw2.pure.cloud/.
  • The complete list of Genesys Cloud API servers is available via this link: https://developer.genesys.cloud/platform/api/.

Call Matching

Both AudioHook and Notification Service CTI feeds will contain a “conversationId” parameter that is used to perform call matching for both Inbound and Outbound call flows.

User Management

Cogito User Management requires a standardized set of data associated with each user. Cogito uses this information primarily to enable telephony integrations and to enable appropriate reporting pipelines.

Users will be provisioned on the Cogito system with updated Genesys endpoint information. The endpoint for agent identification for Genesys Cloud is the Genesys username. Cogito receives this value as “agentId” in the Notification Service API event, in the format of “[email protected]_”. The [email protected]_ is ignored. The username portion is provisioned as the Telephony Agent ID endpoint.

There are several methods of user management in Cogito:

  • Automated User Import from Genesys Cloud environment.
  • CSV File.
    Client provides a standardized set of data associated with each user, compiled into a “User Input File”, to input users into Cogito's systems. The User Input File should be provided as a single un-tabbed .CSV file.
  • Cogito's Admin Service APIs.
    Cogito's Admin Service APIs is a collection of REST APIs that can be used by authenticated and authorized clients to onboard and manage their users in their own namespace which is referred to as a “domain” in this document.

Customer Configuration Items

Genesys Cloud Notification Service (CTI)

OAuth information for the customer’s Genesys Cloud environment

  1. OAuth integration has to be provisioned for Cogito in the customer’s Genesys Cloud environment. The following information has to be provided to Cogito:
  • Genesys Cloud Region (ie: usw2).
  • OAuth Client ID and Secret.
    • OAuth – Grant Type: Client Credentials.

  1. Ensure the Role assigned to OAuth contains permission for Analytics > Conversation Detail > View (User and Supervisor roles would have that permission by default).
  • Roles – User and Supervisor.

Audio Integration

Cogito utilizes the “AudioHook” feature provided by Genesys Cloud. In this scenario Cogito uses APIs to obtain media streams directly from Genesys Cloud trunk.

Genesys Cloud Audiohook

Configure AudioHook Integration

  • Install Audiohook streaming integration.
  • Configure WebSocket endpoint under the “Connection URI” property (endpoint will be provided by Cogito after the Cogito environment has been deployed).
  • Configure API credentials (to be provided by client to Cogito to configure the backend service).
  • Please generate new values for “API Key” and “Client Secret”. There are no minimum character or other password requirements.
  • The only requirement here is for the “client secret” to be a base-64 encoded sequence of bytes. You can use https://www.base64encode.org or other similar tools to encode a string into base-64 format. Cogito will use these values in websocket endpoint configuration.

Enable Voice Transcription

  • AudioHook requires enabling voice transcription globally in Speech and Text Analytics settings.
  • AudioHook also requires enabling voice transcription for the queue in the Voice settings of the queue configuration.

Enable “Line Recording”

  • Make sure that line recording is enabled for your trunk. That setting should be under Telephony / Trunks / External Trunks. Clicking on the trunk you are using for your AudioHook calls, you can find the line recording toggle in the Media section.

  • The recording options are towards the bottom of that section.

Solution Architecture Diagram - AudioHook

References

Genesys Notification Service Integration

https://developer.mypurecloud.com/api/rest/v2/notifications/notification_service.html
https://developer.mypurecloud.com/api/rest/v2/notifications/available_topics.html
https://developer.genesys.cloud/api/rest/v2/users/#get-api-v2-users
https://developer.mypurecloud.com/api/rest/client-libraries/java/
https://developer.mypurecloud.com/api/rest/client-libraries/java/UsersApi.html
https://developer.mypurecloud.com/api/rest/client-libraries/java/NotificationsApi.html

Genesys AudioHook Integration

https://help.mypurecloud.com/articles/audiohook-integration-overview/
https://help.mypurecloud.com/articles/about-the-audiohook-integration/

Updated 6 months ago