Genesys Cloud Open Messaging - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

The Genesys Cloud Open Messaging handover provider bridges Cognigy.AI and Genesys, enabling end users to connect with human agents working in a contact center that uses Genesys Cloud CX. The Genesys Cloud Open Messaging handover provider is based on Open Messaging APIs. Open messaging facilitates integrations between Genesys Cloud and a third-party messaging service through a webhook.

Prerequisites

Restrictions

Configuration on the Handover Provider Side

Before starting the integration with Cognigy, build the Genesys Cloud Open Messaging configuration on the Genesys Cloud CX side.

  1. Create a Platform

    • In the Genesys Cloud interface, click Menu in the upper-left corner and go to Digital and Telephony > Message > Platform Configurations.
    • In the upper-right corner, click + Create Profile.
    • In the Create a configuration profile window, enter a unique name for the platform configuration and click Create.
    • In the left-side menu, select Platform Integrations.
    • On the Messaging Platforms page, click + Create New Integration and select Open Messaging.
    • On the Open Messaging page, fill in the following fields:
      • Name — enter a name without spaces for your integration. Copy and save this name. You need to specify this name in the Deployment name field on the Cognigy side.
      • Outbound Notification Webhook URL — enter https://endpoint-<your-environment>/handover/genesysCloudOM. For example, https://endpoint-app.cognigy.ai/handover/genesysCloudOM, where environment is app.cognigy.ai.
      • Outbound Notification Webhook Signature Secret Token — enter the secret into the X-Hub-Signature-256 header generation for webhook requests sent to the outbound notification webhook URL. For the secret, you can choose any arbitrary but sufficiently random string that you want. The external service should use the secret and signature to validate the message originating from Genesys Cloud. This validation is optional but recommended. For more information about validation, see Validate webhook notifications in the Genesys Cloud Developer Center. Copy and save this token for future use in Cognigy.AI. Note that if you don’t copy and save this token, you will need to recreate it after saving the platform configuration.
    • Click Save.
    • From the Platform Config list, select the config that you created in Platform Configurations.
    • From the Supported Content Profile list, select default. Save changes.

  2. Create a Queue

    • In the left-side menu, select User Management > Queues.
    • On the Queues page, click + Create Queue. The Create Queue panel opens on the right side.
    • In the Create Queue panel, fill in the following fields:
      • Name — enter a unique name of the queue. Save and copy this name for later use.
      • Division — select Home.
    • Click Save. Your queue will appear in the queue list.
    • Open the queue settings by selecting the queue from the list.
    • In your browser’s address bar, find and copy the queue ID from the URL. The ID is located between /queues/ and /general. For example, in the URL, https://apps.mypurecloud.de/directory/#/admin/organization/queues/d59d0280-6664-4896-ad42-1a2715b7178e/general, copy the ID d59d0280-6664-4896-ad42-1a2715b7178e.
    • Save the queue ID for later use in Cognigy.AI.

  3. Create an Inbound Message Flow

    • In the left-side menu, select Orchestration > Architect.
    • Hover over the icon on the Flows tab and select Inbound Message.
    • Click + Add in the upper-left corner. The Create ‘Inbound Message Flow’ dialog box opens.
    • In the Name field, enter a unique name for the inbound message flow.
    • From the Divisions list, select the division to assign the flow to.
    • Click Create Flow. The flow’s configuration page opens.
    • In the Search Toolbox field, enter Send Response and drag the action below the Start action in the messaging flow editor.
    • In the Message Body field of the Send Response action, enter Connected and select Literal from the list next to the field.
    • (Optional) Below the Send Response action, add the Get Participant Data action.
    • (Optional) In the Get Participant Data editor, click + and add the following attributes:

| Attribute | Name | Value | | --- | --- | --- | | 1 | Queue ID | queueId | | 2 | Language | myLanguage | | 3 | Skills | mySkills | | 4 | User ID | userId |

  1. Set up Message Routing

    • Go to the Genesys Cloud interface, click Menu in the upper-left corner and select Orchestration > Routing > Message Routing.
    • In the upper-right corner, click + Attach New Addresses to a Flow. The Attach New Addresses page opens.
    • From the Select Flow list, select the Inbound Message Flow you created.
    • From the Select Addresses section, choose the Open Messaging platform you created and click Attach Address. Save changes.

  2. Configure Credentials

    • In the left-side menu, select IT and Integrations > OAuth, then click + Add Client.
    • On the Add New Client page, configure the following:
      • App Name — enter a unique name for the client.
      • Grant Types — select Client Credentials. Click Next.
    • In the Roles list, activate the corresponding role for the client. The role must include at least the following permissions:
      • messaging-platform:readonly (View messaging platform integrations)
      • conversations (Create, edit, and delete conversation data)
      • analytics:readonly (Query aggregate conversation data and view conversation details)
    • Click Next.
    • In the Token Duration in seconds field, enter the token expiration time. Click Next.
    • Click Generate New Client Secret, then Confirm.
    • Copy the Client ID and Client Secret, save them for future use, and click Finish. Confirm that you copied the Client ID and Client Secret in the dialog box.
    • In the left-side menu, select Authorized Applications.
    • In the upper-right corner, click + Authorize a Client.
    • In the Authorize Client window, enter the Client ID that you copied previously and click Authorize Client.
    • (Optional) In the Users that can use this application section, select the roles of the users who can use this application.
    • In the Scope section, select the minimum scope of the application, as listed in step 3. Click Authorize.

Once your client is authorized, you can start configuring the Genesys Cloud Open Messaging handover provider on the Cognigy.AI side.

Configuration on the Cognigy.AI Side

  1. Create a Handover Provider

    • Go to Deploy > Handover Providers.
    • Click + New Handover Provider and select Genesys Open Messaging from the list.
    • Scroll down to Handover Settings and select Genesys Cloud Open Messaging from the list.
    • Fill in the following fields:
    • (Optional) Activate the Send Profile information setting if you want to display human agent information, such as the first and last name, to the user. Save changes.

  2. Configure Handover Settings

    • In the Handover to Human Agent Node, configure the following settings:
      • Language — specify a language for the conversation. For example, english, spanish, german.
      • Skills — define skills for the conversation. For example, escalation.
      • Priority — set the priority for the conversation. For example, 1. If a priority is set, it triggers a flow in Genesys to prioritize or de-prioritize the conversation within the queue. Note that this functionality requires the appropriate flow to be set up in Genesys.
      • Enable User Connects Message — notify human agents when an end user reconnects to the chat. The parameter is enabled by default. When the parameter is enabled, the message User joined the conversation appears in the chat as soon as the end user returns to the chat tab by clicking the ← (back arrow) at the top bar in the browser, after having opened a new URL on the same tab as the chat.
      • Enable User Disconnects Message — notify human agents when an end user disconnects from the chat. The parameter is enabled by default. When the parameter is enabled, the message User left the conversation is sent as soon as the end user closes the tab with the chat or switches to a new URL address within the current tab.
      • Display Agent Details — display the human agent’s name and avatar from Genesys in the chat for the end user. The parameter is disabled by default.
      • Custom Attributes — add custom attributes, which allows you to include additional information. When sending custom attributes from Cognigy.AI to Genesys Cloud, you can enter them in two ways:
        "{\"customerType\":\"premium\",\"tags\":[\"urgent\",\"vip\"]}"
        ```
        - JSON Object

    {
      "customerType": "premium",
      "tags": ["urgent","vip"],
      "preferences": { "language": "en", "notifications": true }
    }
    ```

Before sending to Genesys, Cognigy.AI flattens nested objects, joins or indexes arrays, converts booleans to 1/0, and skips unsupported types. To test the connection, click Open Demo Web Chat in your Endpoint.

Additional Configuration

Send Genesys Bot Messages to End Users Before using this feature, add the GENESYS_CLOUD_OM_HANDLE_BOT_MESSAGE: "true" feature flag.

By default, the Genesys Inbound Message flow routes messages to human agents only. You can configure your settings so that not only human agents but also end users receive these messages. Forwarding messages to the end user can be helpful in the following use cases:

The Genesys Inbound flow is responsible for message configuration. However, if you want to use additional logic, such as allowing end users to see their queue position, set up the In-Queue Message flow in Genesys in addition to the Genesys Inbound flow. Cognigy.AI is responsible for message routing logic. Follow the instructions to configure this logic:

  1. In your chosen Handover Flow, set a Lookup Node below the Handover to Human Agent Node. Set the Lookup Node as your Entrypoint.
  2. For the Type field within the Lookup Node, select Handover Status.
  3. For the child Case Node, specify genericHandoverUpdate in the Value field.
  4. Add your Say Node under the Case Node to display the messages to the end user. Select Text from the Output Type list, and in the Text field enter the following CognigyScript: {{ input.data.request.text }}. The script will then query Genesys for the relevant data, such as a queue position.
  5. In the Handover Settings of the Say Node, select User Only from the Handover Output Destination list.
  6. To display all incoming Genesys Status or Bot messages, add a Go To Node below the Say Node.
  7. Open the Go To Node. From the Select Node list, choose Lookup. Scroll down to the Advanced section. From the Execution Mode list, select Go to Node and wait for Input.

The main Flow on Cognigy.AI should look like this:

Filter Transcript Messages By default, Cognigy.AI sends the full conversation transcript as a single message once the handover to Genesys occurs. Additionally, you can filter out empty or unsupported messages to keep the transcript relevant and concise: