Integration Description

In order to capture audio and provide call guidance to customer agents/representatives. Cogito integrates with the Genesys Cloud CX environment, to receive Call Events from the Genesys Cloud Notification service and utilizes either the SBC SIPREC integration to receive Call Audio (media), or the Genesys Cloud AudioHook API for real time audio feeds.

The Genesys Cloud Audio hook API provides Cogito with a Direct audio feed from the Genesys Cloud environment. AudioHook is supported with Genesys Cloud Voice and with BYOC Cloud. AudioHook is currently not supported with BYOC Premise (Genesys Cloud Premise Edges deployed locally). AudioHook is currently only supported in the Genesys CX3 license model. Support for the CX2 license model is planned for Q1 2023.

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

In-direct Call Termination

• Calls flow into and out of the Customer Data Centers via carrier SIP trunking to On Premise Oracle SBC’s. Calls are then delivered to the Genesys Cloud environment

Integration Points

Call Audio Options

Genesys AudioHook API

• Call Audio (media) is delivered to Cogito via the Genesys Cloud AudioHook API feature
• When a matching Agent Call Event is received, Cogito accepts the webhook session from AudioHook and begins processing the call audio

Oracle SBC’s

• Call Audio (media) will be delivered to Cogito via existing Oracle SBC SIPREC integrations
• The Cogito Cloud MSS places the SIPREC session inactive until a matching Agent Call Event is received
• When a matching Agent Call Event is received, Cogito sends a re-Invite to set the SIPREC session active and begin receiving audio from the Oracle SBC

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/

Call Matching

Inbound

AudioHook

• Genesys Conversation ID

SIPREC

• Oracle SBC generated UCID
• Passed to Genesys Cloud in User-to-User header
• Genesys Cloud trunk must be configured to accept the UCID value

Outbound

AudioHook

• Genesys Conversation ID

SIPREC

• Genesys Conversation ID
• Genesys Cloud trunk must be configured to send Conversation Headers (x-inin-cnv)
• Oracle SBC must be configured to send x-inin-cnv header in SIPRec metadata

Customer Configuration Items

Genesys Cloud Notification Service (CTI)

OAuth information for the customer’s Genesys Cloud environment

• Provide Genesys Cloud Region (ie: usw2)
• Provide OAuth Client ID and Secret (OAuth – Grant Type: Client Credentials;
  Roles – User and Supervisor)
• Ensure the Role assigned to OAuth contains permission for Analytics > Conversation Detail > View (usually the default User and Supervisor roles would have that permission by default)

• Enable UUI Passthrough on Incoming Trunk (for SIPREC Audio Integration only)

Audio Integration

Cogito can utilize two methods to obtain the audio stream data (media) of the agent interactions:

1. Thefirst method utilizes “Audiohook” feature provided by Genesys Cloud. In this scenario Cogito uses APIs to obtain media streams directly from Genesys Cloud trunk.
2. The second method of obtaining the audio data is via an SBC with SIPREC support. This solution can be utilized if the client still uses SBC as the edge device for call processing and usually applies to hybrid environments, when other ACD solutions (Avaya AES, Cisco, etc) are used in addition to Genesys Cloud.

Genesys Cloud Audiohook (if using Genesys audio integration)

Configure AudioHook Integration

• Install Audiohook streaming integration

• Configure WebSocket endpoint under the “Connection URI” property (to be provided by Cogito)

• 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 config

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

Oracle SBC (if using SIPREC audio integration)

Oracle SBC must be configured to send SIPREC to Cogito

Inbound

• Matching is based on SBC generated UCID
• UCID sent in SIPREC from SBC and CTI from Genesys Cloud Notification Service API
• UCID is populated in SIPREC metadata to Cogito
• UCID is sent to Genesys Cloud in User-to-User header
• The UCID is then made available in the CTI tag ASAIUUI via Genesys Cloud Notification Service API

Outbound

• Matching is based on the Conversation ID within Genesys Cloud
• The “ConversationID” is made available in CTI in the “Call ID” tag
• “x-inin-cnv” header configured to populate in SIPREC metadata to Cogito
• Genesys Cloud is configured so that the sip trunk adds a custom SIP Header “x-inin-cnv” which is then sent to Cogito by the Oracle SBC in SIPREC metadata. The agent channel is different for Outbound calls

Enable Conversation Headers (x-inin-cnv) for Outbound matching:

• Requires a VPN connection for secure data transfer
• This solution has been tested with Oracle SBC, however other SBC models may also be supported if the above requirements can be met technologically

📘

In case a different model SBC is used - additional time should be allocated to the project to allow for the integration and testing to be completed

Solution Architecture Diagram - AudioHook

Solution Architecture Diagram - SIPREC

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

Genesys AudioHook Integration

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