Skip to content

Agent AI Integration with Genesys Cloud CX using Kore Data Table

Integration of Agent AI in Genesys is a significant enhancement to our solution. Previously limited to a single bot and a department-specific approach, the solution has now been upgraded to support multiple bots and a queue-based functionality. This enhancement enables Genesys Cloud CX to offer a more flexible and scalable solution for businesses seeking to leverage AI to improve agent efficiency and customer satisfaction across multiple departments.

Note

This integration process also works for Genesys Desktop App.

Definitions

Section/Group Key Definition Reference
Generate Oauth ID to enable Kore Services to Connect with Genesys

+

Create an Interaction Widget in Genesys for Agent AI

Agent AI URL The domain of the Agent AI.
Client App To use any Kore.ai Bot SDKs, a client app must be created to get the authentication credentials to communicate between the Kore.ai bot and Agent AI.

Note: Only the default Client App is supported.

https://developer.kore.ai/docs/bots/channel-enablement/adding-the-webmobile-client-channel
Create an Interaction Widget in Genesys for Agent AI Custom Data / x_passthru_metadata Use this to pass information to Agent AI Bot.
Capture Bot Information in Kore Data Table Secure Custom Data / KvpConfig Use this to pass sensitive information to Agent AI Bot. https://developer.kore.ai/docs/bots/sdks/user-authorization-and-assertion/#JSON_Web_Encryption_JWE
Create an Interaction Widget in Genesys for Agent AI Interaction Widget The Interaction Widget is utilized for displaying the Agent AI iframe within the Genesys Agent Desktop. https://help.mypurecloud.com/articles/set-up-an-interaction-widget-integration
Create an Interaction Widget in Genesys for Agent AI Interaction Widget URL params
  • “multibot=true”, represents usage of new version of AgentAI integration that supports agent specific bot assistant
  • “x_metadata” - This param value equals the URL-encoded string of JSON object which consists of data required by Kore Middleware service to successfully generate Agent AI iframe URL.
  • “x_passthru_metadata” - This parameter value can be a JWE or JWT token, a base64 encoded string, or a URL-encoded JSON. It is stored as custom data in the bot context. (Optional Parameter)
 x_metadata’s JSON object structure is

{

"datatable":{

"name":<datatable name>,

"token":<jwt token created using App's ClientId and ClientSecret>,

"qDelimiter":Paste the special character used in the queue name to distinguish the QueueIdentifier from the remaining part of the queue name }

}

Capture Bot Information in Kore Data Table BotId A unique identifier assigned to a bot. Agent AI > Flows & Channels > Digital > Web/Mobile Client > JWT App Details
Capture Bot Information in Kore Data Table ClientId An identifier provided to a client application. Agent AI > Flows & Channels > Digital > Web/Mobile Client > JWT App Details
Capture Bot Information in Kore Data Table ClientSecret A secret key or password associated with the ClientId. Agent AI > Flows & Channels > Digital > Web/Mobile Client > JWT App Details
Capture Bot Information in Kore Data Table AgentAssistWidgetURL URL that points to the Agent AI widget.

For example, https://agentassist.kore.ai/koreagentassist-sdk-v3/UI/agentassist-iframe.html

Agent AI > Flows & Channels > Digital > Web/Mobile Client > JWT App Details
Capture Bot Information in Kore Data Table AudiohookEnabled A setting or flag indicating whether Kore audio processing is enabled for the bot. “true” if Kore audio processing should be enabled, otherwise “false”.
Capture Bot Information in Kore Data Table QueueIdentifier It’s a unique identifier in the Data Table to fetch bot details at run time.
Capture Bot Information in Kore Data Table KvpConfig The KVPs (Key value pairs) to be included in SecureCustomData. JSON object containing the necessary keys and xpath (paths to locate the value in Genesys Conversation API result JSON object). https://developer.genesys.cloud/devapps/api-explorer#get-api-v2-conversations--conversationId

Note: Optional Column. Required when you wish to send secure custom data to Agent AI.

Sample:

{

"queueName": "participants[0].queueName",

"callStatus": "participants[0].calls[0].state"

}

Capture Bot Information in Kore Data Table JWEPublicKey Public key assigned to the Client App. Agent AI > Flows & Channels > Digital > Web/Mobile Client > JWT App Details
Capture Bot Information in Kore Data Table RSPrivatePem The Private Key that corresponds to the Public Key supplied during the creation of a Client App using the RS256 or RS512 algorithm. RSPrivatePemKey is an optional column and is required when the algorithm used is “RS256” or “RS512”.

(Not supported / Will be supported in future releases)

Capture Bot Information in Kore Data Table Algorithm Algorithm assigned to the Client App. Currently, “HS256” algorithm is the only supported value. So, the algorithm value will always be “HS256”.
Install Audiohook for Voice Streaming Kore Voice Gateway(KVG) For Saas in US region, value is savg-webserver.kore.ai

For on-prem, refer to corresponding host

Architecture Diagrams

Chat

architecture-diagram-chat

Voice

architecture-diagram-voice

Interaction Sequence

interaction-sequence

This document provides detailed, step-by-step instructions for setting up the integration of the Agent AI widget in the Genesys environment.

Activities on Kore Platform

Activities on Genesys Cloud

Chat Setup

Voice Setup

Prerequisites

  • Genesys Administrator having access to Genesys Cloud account with Admin rights.
  • Kore Administrator having access to Kore.ai Agent AI instance.

Capture Bot Information in Kore Data Table

Data Tables are used to store agent queue-specific bot credentials. Each record of the Kore Data Table represents a unique Genesys agent queue and its corresponding bot definitions.

If a single bot is used for several queues, create a record and insert the queue names, separated by commas, as the value for the QueueIdentifier, along with the bot details.

Kore.ai matches the third-party queue name with the "QueueIdentifier" credential name in its bot credentials to render the appropriate bot.

  • Bot credentials are fetched based on Genesys desktop queue names. If the Genesys queue name is of the “<QUEUEIDENTIFIER><QDELIMITER>XXXXX” format, for example “ALPHAINC_CUSTOMERSERVICE_16092024,” then:
  • QueueIdentifier = ALPHAINC and qDelimiter = “_”.
  • Update the QueueIdentifier in the Kore datatable.
  • Update the qDelimiter in the Create an Interaction Widget in Genesys for Agent AI section.

Note

Multiple records with different bot credentials shouldn't be entered into the Kore Data Table for a single QueueIdentifier.

How to create a New Data Table

  1. Sign in to Kore.ai XO Platform.
  2. Click Data > Data Tables.

  3. Click New Table.
    new-table

  4. Enter the following details in the New Table page:

    1. Name of the Data Table (any alphanumeric name).
    2. Description of the Data Table.

    3. Columns to be included in the Data Table. Click the “tick” mark to add multiple columns.
      multiple-columns

      Add the following case-sensitive columns with type “string”:

      Mandatory Columns:

      • QueueIdentifier (unique identifier for the table)
      • BotId
      • ClientId
      • ClientSecret
      • AgentAssistWidgetURL
      • AudiohookEnabled
      • JWEPublicKey

      Optional Columns:

      • KvpConfig
      • Algorithm (HS256)
      • RSPrivatePem (Ignore/Not Supported)

    4. Indexes for the table.

      • Index Name for reference.
      • Is Unique flag to define if the index is expected to contain unique values. (Enable “‘is Unique.”)
      • Column & Sort Order – List of columns to be included in the index; you can select multiple columns and specify the sort order (ascending or descending) for each of the selected columns. (Select QueueIdentifier with ascending order.)
        queue-finder

    5. Bot Assignments (not applicable).

    6. App Assignments to let apps access data in this table.

      1. Select any app from the displayed list, or click Create New App and enter your app name:
        create-new-app

      2. Select the Read, Write, and Delete permissions, as required.

      Note

      You can also create new apps by clicking Data > Apps > New App in the home page:

      apps-new-app

    7. Process Assignments (not applicable)

    8. Click Create to create the new data table.
      create-new-data-table

Insert data into Data Table

Set up necessary permissions and app assignments and insert bot-specific data into the Data Table.

  1. Sign in to Kore.ai XO Platform.
  2. Click Data > Apps.

  3. Select the App with “write” access to the Data Table where you want to add information.
    app-write-access

  4. Copy Client ID and Client Secret of the App.

  5. Create a JWT Token using the Client ID and Client Secret by following this doc.

  6. Insert the following data into the Data Table by following this doc. Use the JWT Token created in the previous step.

    API Body Payload Structure: 

    {
    "data": {
        "QueueIdentifier": <Unique QueueIdentifier>,
        "BotId": <Kore BotId>,
        "ClientId": <Kore ClientId>,
        "ClientSecret": <Kore ClientSecret>,
        "AudiohookEnabled": "true" / "false",
        "AgentAssistWidgetURL": <Kore Agent AI Widget URL>,
        "KvpConfig": <KVPs of SecureCustomData>,
        "JWEPublicKey": <Public Key assigned to Client App>,
        "Algorithm": "HS256"
    }
}

Notes

  • For a single queue, the QueueIdentifier value contains one queue name (for example, “Kore”). For multiple queues, it includes all the queue names separated by commas (for example, “Kore, KoreSupport”).
  • JWEPublicKey and KvpConfig value should be a stringified JSON object.

Single Queue Example
single-queue-example

Multiple Queues Example
multiple-queues-example

Generate Oauth ID to enable Kore Services to Connect with Genesys

Steps to get Genesys OAuth ID:

  1. Sign in to Genesys Cloud.
  2. Go to Admin > Integrations > OAuth.
    single-queue-example
  3. Click Add Client.
  4. Enter the app name, description, and token duration in the App Name, Description, and Token Duration fields.
  5. Select Token Implicit Grant (Browser) in the Grant Types section.
    token-implicit-grant
  6. Add {Agent AI URL}/koreaiaa-genesys/ in the Authorized redirect URIs field.
  7. Add the following list of scopes in the Scope section:
    • conversations
    • conversations:readonly
    • integrations
    • integrations:readonly
    • messaging
    • messaging-platform
    • messaging-platform:readonly
    • messaging:readonly
    • notifications
    • user-basic-info
    • web-chat
    • web-chat:readonly

authorized-redirect-uris

After saving the configuration, you get the Client Id of the created OAuth client. Copy the ID and have it available for Step 3.

Create an Interaction Widget in Genesys for Agent AI

Create a new Interaction Widget. This widget is hosted in the Genesys agent desktop and provides the Agent AI solution features to agents.

Steps to create an Interaction Widget:

  1. Sign in to Genesys Cloud.

  2. Click Admin > Integrations.

  3. If you have not created an Interaction Widget for Agent AI, install a new Interaction Widget by clicking the Integrations tab on the right side of the page.
    genesys-cloud-integrations

    interaction-widget

  4. Name the Interaction Widget with a meaningful name, such as KoreaiAA Interaction Widget.

  5. Open the Interaction Widget by clicking the name.

  6. Go to the Configuration tab of the Interaction Widget.
    interaction-widget-configuration

  7. In the Application URL field, enter the following structure:
    {Agent AI URL}/koreaiaa-genesys/?conversationid={{gcConversationId}}&lang={{gcLangTag}}&environment={{gcHostOrigin}}&genesysid=<genesys-oauth-Id>&multibot=true&x_metadata=<?x=%7B%22datatable%22%xxxxx>&x_passthru_metadata=<Token>.

Note

x_passthru_metadata is an optional query parameter. This is required when you wish to pass custom data to Agent AI.

The “x_metadata” value equals the URL-encoded string of the JSON object.

  1. For the oauthId value, use the OAuth ID from Step 2.

  2. Build x_metadata:

    1. Sign in to Kore XO Platform.

    2. Click Data > Data Tables, and copy the Data Table name:
      copy-data-table-name

    3. Click Apps, and click one of the app names that has “read” access:
      click-apps-read-access

    4. Copy the Client ID and Client Secret values.
      client-id-client-secret-values

    5. Create a JWT Token using the Client ID and Client Secret by following this doc.

    6. Generate a JSON object with the specified structure, and then convert it into a URL-encoded string:

      {
            "datatable": {
                    "name": <paste datatable name>,
                    "token": <paste token created in previous step>,
                    "qDelimiter": <Paste the special character used in the queue name to distinguish the QueueIdentifier from the remaining part of the queue name>
                }
}
Website for url encoding - urlencoder
      Reference:
      java-script-demo

    7. Copy the URL-encoded string and paste it against the x_metadata value.

  3. Allow all permissions in iFrame Sandbox Options and iFrame Feature/Permission Policy:

iFrame Sandbox Options: allow-forms,allow-modals,allow-popups,allow-presentation,allow-same-origin,allow-scripts,allow-downloads.

iFrame Feature/Permission Policy: camera,microphone,geolocation,clipboard-write,display-capture,fullscreen.

Communication Type Filtering: chat and call.

Provide Interaction Widget access to agents

To view the Interaction Widget, agents must have the following accesses:

Group Membership

An Interaction Widget uses Group Membership to determine who can view it on the agent desktop.

  1. Use an existing Group, if your agents are already part of it. Otherwise, create a new Group for Agent AI permission.
  2. Name the Group as KoreAA-Agents or similar to distinguish it.
  3. Add any agent to allow them to use the Agent AI functionality. You can utilize more than one Group, if required.
  4. Go back to the Integrations section and open the Interaction Widget created in Step 2.
  5. On the Configuration tab, add access using the Group you identified or created for Agent AI in the Group Filtering option.

You may also utilize Queue Filtering (optional).
group-filtering

Custom Role/Permission

In addition to the basic agent role, add a new role as given below:

  1. Sign in to Genesys Cloud.
  2. Go to Admin > People & Permissions > Roles / Permissions.
  3. Click Add Role to create a new role.
  4. Give a distinctive name to the role; for example, KoreaiAA Agent.

  5. On the Permission tab, search for Conversation > Transcription > View, and add (select the box):

    Note

    The Conversation permission is available only in the CX3 license.

    1. Once finished, the Assigned Permissions view should look like this:
      assigned-permissions

  6. Once the role is created, click the three dots at the right end of the Permission role, and select Change Membership. Add the appropriate agents to the role.

Create a Queue in Genesys

  1. Sign in to Genesys Pure Cloud.
  2. Go to Admin > Contact Center > Queues, or enter “queues” in the search bar under the Admin section and press the Enter key.

  3. Click Create Queue. An empty page to create a new queue appears on the right side of the page.
    create-queue

  4. Enter/select the following details in the Create Queue page:

    • Name: Enter a unique name for the new queue.
    • Division: Select a division in which you want to place this queue.
    • Copy settings and members from (Optional): Select an existing queue name, if you want to copy the settings and members from it.
    • Peer Id (optional) : Enter a unique ID that can be used to identify the queue from an external platform.
      peer-id

  5. Click Save.

Enabling the Audio Monitoring toggle

To stream audio to third-party services, follow the below steps:

  1. Sign in to Genesys Pure Cloud.
  2. Go to Admin > Contact Center > Queues, or enter “queues” in the search bar under the Admin section and press the Enter key.
  3. Click the intended queue name.
  4. Click the Voice tab.

  5. Enable the Audio Monitoring toggle.
    audio-monitoring-toggle

    Audio Monitoring: Voice settings on a Queue now have an additional Audio Monitoring option, separate from Voice Transcription. This allows granularity in what you turn on. The Audio Monitoring will be enabled in the queue, if Audiohook Monitor is enabled by the organization.

Chat Setup

Create/Update Architect Inbound Message Flow in Genesys for the Agent Queue

This step is essential for managing incoming messages to the Genesys platform. When a chat is initiated from the web chat messenger, it first gets directed to this inbound message flow.

Steps to create a chat architect flow

  1. Sign in to Genesys Cloud.
  2. Go to Admin > Architect > Architect.

  3. Click the three dots next to Flows: Inbound Call, and select Inbound Message.
    inbound-message

  4. Click the +Add button to create an Inbound Message Flow.
    create-inbound-message-flow

  5. Click Create Flow. The final architect flow looks like the following screenshot:
    create-flow

  6. Click Publish.

Create Messenger Configuration

Before using web messaging, you must configure it in Genesys Cloud. To configure Web or Mobile Messaging in your organization, follow these steps:

  1. Sign in to Genesys Cloud.
  2. Go to Admin > Message > Messenger Configurations.

  3. Click New Configuration.
    messanger-new-configuration

  4. Enter a name and description.
    messenger-configuration-name-description

  5. Click the Appearance tab and complete the following information:

  6. Under Select your Supported Languages, click the Select language(s) list and choose the languages that you want to support in the Messenger interface.

    Note

    The same language should be configured in the Kore Agent AI bot.

    select-supported-languages

  7. Under Select Default Language, click the Select language list and choose the default language.
    default-language

  8. Adjust the other settings according to your preferences.

  9. Click the Apps tab and complete the following steps:

  10. Under Clear Conversation, turn on the toggle button. This is required for the Agent AI Conversation Summary feature to work.
    clear-conversation-toggle

  11. Adjust the other settings according to your preferences.

  12. Click Save New Version to create a new version.

Create Messenger Deployment

To deploy the Messenger snippet to your website, follow these steps:

  1. Sign in to Genesys Cloud.
  2. Go to Admin > Message > Messenger Deployments.

  3. Click New Deployment.
    new-messenger-deployment

  4. Enter a name and description.
    messenger-deployment-details

  5. Under Select your Configuration, click **Select Configuration **to select a version of a Messenger configuration created in the previous step to assign to this deployment.

  6. In the Assignment pane, navigate to the Messenger configuration you want to assign to the configuration, and click the name of the Messenger configuration.
  7. Select the version that you want to assign.
  8. Click Save.
  9. Under Restrict domain access, determine whether to allow all domains or restrict the domains on which you want to deploy the snippet.
  10. To allow all domains, select the Allow all domains option. Use this option for testing and development purposes.
  11. To restrict domains, enter a domain and click Add Domain. You can add multiple domains to the list. Restrict domains to prevent unauthorized usage of your snippet from unknown domains. If you restrict a domain, Messenger does not run on that website and rejects API requests from that domain.
  12. Under Select your Architect Flow, select the inbound message flow created in the previous steps.
  13. Click Save. The Messenger Deployments page now displays the snippet and the deployment key.

  14. Copy the Messenger snippet and deploy the Messenger snippet to your website.

    • If you are building a custom Messenger, copy the deployment key.

    Note

    Once the above mentioned website page loads, the messenger window appears.

    messenger-window

(Optional) Install Audiohook for Voice Streaming

The final step is to install Audiohook for voice streaming, if using Kore-managed Transcriptions.

  1. Sign in to Genesys Cloud.
  2. Go to Admin> Integrations > Integrations.

  3. Enter “audiohook” in the search bar.
    audiohook

    Audiohook integration requires specific configuration values to support Agent AI configuration. 4. Install a new audiohook app by clicking the Integrations button on the top-right corner.
    audiohook-monitor

  4. Open the Audiohook, and go to the Configuration tab.
    audiohook-configuration

    1. Channel value should be both.
    2. The Connection URI format should be similar to \ wss://{Kore Voice Gateway(KVG)}/audiosocket/genesys/?sipuri=xxx&token=xxx&botId=xxx&accountId=xxx&agentassist=true, but add “multiBot=true” parameter to it.

    Notes

    • Configure SIP of any of the bots inserted in the Data Table.
    • Kore Voice Gateway(KVG) host name to be referred from corresponding environment being used at Saas or on-prem

  5. Get sipuri=sip:<sip-string> from Agent AI > Flows & Channels > Voice Gateway > SIP Numbers > Configure SIP Trunk > Product Selection > Agent AI.
    configure-sip-trunk

  6. Use the following reference from Agent AI > Flows & Channels > Digital > Web/Mobile Client > JWT App Details page to fetch Bot ID, Account ID, Client ID, and Client Secret (for token generation).
    web-mobile-client

Follow the steps of Using XO Platform APIs – Kore.ai Documentation to generate the token (token= <token>.)

  1. Add credentials in the Credentials tab.

  2. Use the ClientID and ClientSecret of the bot you have used while configuring the Audiohook. These credentials are used to validate the audiostream signature by Kore.
    audiohook-credentials

  3. Click Save.

Create/Update Architect Inbound Call Flow in Genesys for the Agent Queue

When a call comes to a Genesys number, it passes through an architect flow. If you do not have an ACD architect flow for the queue, create one by following this section.

Steps to create a call architect flow

  1. Sign in to Genesys Cloud.

  2. Go to Admin > Architect > Architect.
    genesys-architect

  3. Click the +Add button to create an Inbound Call Flow.
    create-inbound-call-flow

  4. Click Create Flow. The final architect flow looks like the following screenshot:
    final-architect-flow

Notes

  • Inside the Transfer to ACD node, select the queue name where you want to transfer the call.
  • The Transcription node is optional, if you have already enabled Voice Transcription and Audio Monitoring in the queue level voice configuration.
  • Architect flow is required as a mandatory step, as it directs the incoming call to the Genesys agent desktop.

Access Custom Data and Secure Custom Data in Agent AI Bot

Custom Data and Secure Custom Data can be accessed in Welcome Events in Agent AI configuration page and in Dialog Tasks in Agent AI automation page.

Custom Data can be accessed as {{context.session.UserContext.customData.internalMetaData.<key>}}.

Follow this doc for the detailed steps on how to access Custom Data.

Secure Custom Data can be accessed as {{context.session.UserContext.secureCustomData.<key>}}.

Follow the same steps of this doc for the detailed information on how to access Secure Custom Data, with the exception of the path being {{context.session.UserContext.secureCustomData.<key>}}.

Note

If a URL-encoded JSON is provided in the “x_passthru_metadata”, you must use the JavaScript option in the Message node. Then, parse the value of context.session.UserContext.customData.internalMetaData before accessing its content.

Example:

var cd = JSON.parse(context.sessiinternalMetaDataon.UserContext.customData.internalMetaData);

print(cd.<key>);

Post Installation Setup

Steps to start a Chat Request Simulation

  1. Sign in to Genesys Developer Applications.

    Note

    To start chat simulation, you must have access to the Genesys Developer portal (an account with Genesys).

    chat-simulation

  2. Click Web Messenger, select the Deployments, and then click Start Chat to initiate the chat request.
    chat-simulation-web-messenger

  3. Enter a message on the Message Us window, and then click the Send icon.
    chat-simulation-message-use

  4. Turn on the On Queue toggle on the top-right corner of the page.

  5. A new chat notification appears on the Genesys Agent Desktop. Accept the conversation by clicking the Answer button on the left panel.
  6. Select the Interaction Widget icon to view the Agent AI widget.
    interaction-widget-icon-chat

Steps to start a Voice Request Simulation

  1. In Call Routing, assign the Architect flow created in Step-4 to a Genesys Phone Number.
    call-routing

    create-call-route

  2. Initiate a call using this Genesys Phone Number.

  3. A new call notification appears on the Genesys Agent Desktop. Accept the conversation by clicking the Answer button on the left panel.
  4. Select the Interaction Widget icon to view the Agent AI widget.
    call-interaction-details

Set default contextual panel to Kore Agent AI Interaction Widget

To streamline call handling and improve efficiency, the Agent AI widget can now be embedded as the primary contextual panel interaction widget.

To enable this:

  1. Sign in to Genesys Cloud.
  2. Click Admin.
  3. Click Panel Manager under the Contact Center section. This opens the Default Contextual Panel.
  4. Select the interaction widget name in both Voice and Web Messaging field dropdown lists (refer to step-4 of Create an Interaction Widget in Genesys for Agent AI).
  5. Click Save.
    free text

Also, for backward compatibility of the feature, add an additional query param(defaultwidget=true) to the Kore Interaction Widget URL.

Example: https://platform.kore.ai/koreaiaa-genesys/?conversationid={{gcConversationId}}&lang={{gcLangTag}}&environment={{gcHostOrigin}}&genesysid=<genesys-oauth-Id>&defaultwidget=true

Note

Reload the Genesys Agent Desktop before testing this latest change.

Support for Agent Transfer

The Agent AI widget supports both Cold and Warm Transfers:

  • Cold Transfer: A cold transfer occurs when one agent hands over a conversation to another, applicable across Voice, Chat, and Email channels. A new conversation summary is generated for the receiving agent and added to Agent-1’s Assist tab, along with feedback options. Agent-2 can modify the summary feedback for Voice and Email channels.
  • Warm Transfer: A warm transfer is like a conference call between two agents, applicable to Voice and Chat channels. During the transfer, Agent-2 can modify the Summary Feedback. However, the Run, Override, Send, Copy, Terminate, Restart, and List View buttons remain disabled until Agent-1 disconnects from the call.