Getting Started with Our APIs

Genesys Cloud CX

Updated June 27, 2024

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. It receives Call Events from the Genesys Cloud Notification Service API and real time audio feeds from the Genesys AudioHook Monitor.

AudioHook Monitor availability

  • AudioHook Monitor is available for GC1, GC2 and GC3 license types as of June 10, 2024
  • Genesys Cloud AudioHook Monitor 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) or for premises-based Edge (LDM)
  • Please refer to the latest Genesys documentation on AudioHook at https://help.mypurecloud.com/articles/about-the-AudioHook-integration/ for additional information and pricing

Integration Points

Genesys Cloud AudioHook Monitor

  • 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

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’s “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 endpoints 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 in the Cogito system with Genesys endpoint information. The endpoint for agent identification in Genesys Cloud is the Genesys “username”. Cogito receives this value as “agentId” in the Notification Service API events, in the format of “[email protected]”. The domain portion “@customer.com” is ignored. The username portion is provisioned as the “Telephony Agent ID” endpoint in the User Management. Cogito uses this information to map the CTI events and audio streams to a particular agent.

When clients migrate from one integration to another - Cogito can support different integrations for different agents by utilizing User Management. In order to move a particular user from Avaya, Cisco or Genesys Engage integration to Genesys Cloud - the “agentID” and “adaptor” information can simply be updated in the User Management file, and Cogito will begin matching and recording the agent’s interactions in Genesys Cloud.

There are several methods of user management in Cogito when using Genesys Cloud integration:

Customer Configuration Items

CTI - Genesys Cloud Notification Service

  1. OAuth integration would need to be provisioned for Cogito in the customer’s Genesys Cloud environment. The following information would need to be provided to Cogito:

    • Genesys Cloud Region (ie: usw2)
    • OAuth Client ID and Secret
      • OAuth – Grant Type: Client Credentials

  2. 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 - Genesys Cloud AudioHook

Cogito utilizes the “AudioHook Monitor” feature provided by Genesys Cloud. Genesys Cloud streams media directly from Genesys Cloud trunk to the Cogito provided websocket endpoint.

Configure AudioHook Integration

  1. Click + Integrations

  2. Search for AudioHook and click “Install”

  3. Install AudioHook streaming integration:

  4. Configure WebSocket endpoint under the “Connection URI” property (endpoint will be provided by Cogito after the Cogito environment has been deployed):

  5. Configure API credentials (to be provided by client to Cogito to configure the backend service).

    • Client generates new values for “API Key” and “Client Secret”.

    • There are no minimum character or other password requirements.

    • The only requirement 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 the websocket endpoint configuration.

Enable AudioHook Integration

The AudioHook Monitor can be invoked by enabling Audio Monitoring in queue settings or with Architect’s “Audio Monitoring” action. These can be configured together or separately; either one will allow for audio to be streamed to Cogito. Using the "Audio Monitoring" block in Architect doesn’t require any queue settings, so audio will be forked regardless of what queue the call ultimately ends up in; when the Architect flow hits the "Audio Monitoring" block - it will start to fork the audio at that point. Similarly, using “Audio Monitoring” in queue settings doesn’t require any Architect flow configuration. Typically queue settings are easier to implement and maintain. However, the choice ultimately depends on what works best for the client’s technical team from configuration and maintenance perspectives.

Enabling “Audio Monitoring” in queue settings allows all the calls processed by that queue to be forked to Cogito. Enabling “Audio Monitoring'' using Architect block allows for the same functionality. The only difference is that it also allows streaming audio while the caller is in the IVR and not connected to a queue yet. If a client wanted Cogito to have access to the audio while the caller is in the IVR then they would have to use the Audio Monitor block. When the Architect hits that block then it will start to fork the audio at that point. If the Audio Monitoring is only set up at the queue level and not using the Architect block, then the audio will only begin to be forked when it hits the queue. This means that Cogito would not receive any audio from the IVR portion of the call. However, since Cogito only records interactions between the callers and the live agents - streaming the IVR portion of the call is not required. Therefore, either the queue settings or the architect flow can be used, whichever is most convenient for the client's technical team.

Enable Audio Monitoring in “Queue” settings

  1. Click on the “Contact Center” and locate the queue which requires AudioHook Monitor. In this example, the “Billing” queue is used.

  2. Select the “Voice” tab and locate the “Audio Monitoring” toggle next to “Voice Transcription” toggle in the bottom right corner

  3. Turn “Audio Monitoring” toggle to “On”

Enable “Audio Monitoring” action in Architect Flow

  1. Browse to “Architect” module in Genesys Cloud and select the desired queue

  2. Create a new “Task” and select “Audio Monitoring” action under the “Audio” section of the Toolbox. Place the action in the appropriate location within the architect call flow.

Enable “Line Recording”

  1. Make sure that call recording is enabled under the trunk settings. That option is located under Telephony / Trunks / External Trunks. Click on the trunk you are using for the calls requiring AudioHook and locate the “Media” section
  2. Expand the “Media” section to reveal the recording options.
    • Check “Record Calls on this trunk
    • Check “Dual Channel”
    • Check “Consults”, “Holds” and “External bridged transfers” as required

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 2 months ago