Genesys Cloud Open Messaging¶
Cognigy includes Genesys Cloud as an additional handover provider, allowing Cognigy users to connect with human agents from Genesys Cloud.
Open messaging facilitates integrations between Genesys Cloud and a third-party messaging service through a webhook.
The Genesys Cloud Open Messaging handover is based on Open Messaging APIs. Open messaging facilitates integrations between Genesys Cloud and a third-party messaging service through a webhook.
Setup¶
Prerequisites¶
- You need to have an account in Genesys Cloud.
- Activate Genesys Cloud Open Messaging on the Cognigy side:
- If you have a shared or dedicated SaaS installation, contact Cognigy technical support.
- If you have an on-premise installation, specify the following feature flags:
FEATURE_ENABLE_GENESYS_CLOUD_OM="true"
,FEATURE_ENABLE_GENESYS_CLOUD_OM_WHITELIST="organisation1,organisation2"
,FEATURE_USE_GENESYS_BOT_CONNECTOR_ENDPOINT_WHITELIST="organisation1,organisation2"
. To enable the Genesys Cloud Open Messaging handover provider for all organizations in your installation, use*
instead of a list of organizations.
Configure Genesys Cloud Open Messaging¶
Before starting the integration with Cognigy, create Genesys Cloud Open Messaging on the Genesys side.
Create a Platform¶
To create a platform config for Genesys Cloud Open Messaging, follow these steps:
- Open the Genesys Cloud interface.
- Go to Admin > Message > Platform Configs.
- In the upper-right corner, click + Create Profile.
- In the Create a configuration profile window, specify a unique platform config name and click Create.
- In the left-side menu, select Platforms.
- On the Platforms page, click + Create new Integration > 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 isapp.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 usage on the Cognigy side. Note that if you did not copy and save this token at once, after saving the platform configuration, you will need to recreate this token.
- Click Save.
- From the Platform Config list, select the config that you created on the Platform Configs page.
- From the Supported Content Profile list, select
default
. - Click Save.
Your Open Messaging platform will appear in the platform list.
Create a Queue¶
To create a Queue, follow these steps:
- Open the Genesys Cloud interface.
- Go to Admin > Contact Center > Queues.
- On the Queues page, click Create Queue.
- In the left-side Create Queue window, 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 this queue from the list.
- Copy the Queue ID from the page URL. To do this, navigate to the page URL and find the ID between
/queues/
and/general
. For example, in the URL,https://apps.mypurecloud.de/directory/#/admin/organization/queues/d59d0280-6664-4896-ad42-1a2715b7178e/general
, the IDd59d0280-6664-4896-ad42-1a2715b7178e
should be copied. - Save the Queue ID for later use in Cognigy.
Create an Inbound Message Flow¶
To create an Inbound Message flow, follow these steps:
- Open the Genesys Cloud interface.
- Go to Admin > Architect.
- Click or hover over the Flows menu and select Inbound Message.
- Click Add. The Create Flow dialog box opens.
- In the Name field, specify a unique name for the inbound message flow.
- Click the Divisions list and select the division in which to place the flow.
- Click Create Flow. The flow's configuration page opens.
- To configure a flow, click Edit.
- Go to Toolbox.
- Drag the Send Response action and drop it onto the messaging flow editor.
- In the Message Body of the Send Response action, specify
Connected
. - The steps 12–14 are optional.
Follow them if you want to add a new embedded version of AI Copilot within your handover.
(Optional) Below the Send Response action, add Get Participant Data action. - (Optional) In the Get Participant Data editor, add the following variables:
queueId
myLanguage
mySkills
userId
- (Optional) for debugging purposes, you can send this data to the human agent within a conversation. To do that, below the Get Participant Data action, add the second Send Response action. In the message body, specify variables in a message sequence with the String Builder.
- Below the Send Response action, place the Transfer to ACD action to transfer an interaction to a queueing system.
- In the Queue field of the Transfer to ACD action, select the queue to which you want to transfer the interaction.
- In the upper-left corner, click Save, then Publish.
After creating your inbound message flow, you will see this flow in the architect list.
To learn more about designing the flow, see Configure Inbound Message Flow settings.
Set up Message Routing¶
To set up Message Routing, follow these steps:
- Open the Genesys Cloud interface.
- Go to Admin > Routing > Message Routing.
- In the upper-right corner, click + Attach New Addresses to a Flow.
- On the Attach New Addresses page, navigate to the Select Flow list.
- From the Select Flow list, choose the Inbound Message Flow you created.
- From the Select Addresses section, choose the Open Messaging platform you created and click Attach Address.
- Click Save.
Your Message Routing configuration will appear in the message routing list.
Configure Credentials¶
To configure credentials, follow these steps:
- Open the Genesys Cloud interface.
- Go to Admin > Integrations > OAuth.
- Click + Add Client.
- On the Client Details tab, provide a unique name in the App Name field.
- On the Roles tab, activate the corresponding role for the client. The role must contain at least a minimum scope of the following permissions:
messaging:integration:view
(Messaging > Integration > View)conversations:message:receive
(Conversation > Message > Receive)conversations:message:create
(Conversation > Message > Create)conversation:webmessaging:view
(Conversation > Webmessaging > View)conversation:message:view
(Conversation > Message > View)analytics:conversationDetail:view
(Analytics > Conversation Detail > View)
- Return to the Client Details tab and select Client Credentials in the Grand Types list.
- Click Save.
- Copy the Client ID and Client Secret and save them for future use.
- From 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 and saved previously.
- Click Authorize Client.
Once your client is authorized, you can start configuring Genesys Handover Provider on the Cognigy side.
Create an Endpoint¶
To start using Genesys Cloud as a handover provider with Cognigy.AI, follow these steps:
- Open the Cognigy.AI interface.
- Go to Deploy > Endpoints.
- Open the Endpoint where you want to enable Handover to Genesys Cloud.
- In the Configuration Information section, copy the Config URL and save it for future use.
- Scroll down to Handover Settings and select Genesys Cloud Open Messaging from the list.
- Fill in the following fields:
- Host — enter the login URL for Genesys Cloud customers, which varies by region, such as
mypurecloud.de
for Germany. You can use the base domain likemypurecloud.com
orcac1.pure.cloud
, omittingapps.
orlogin.
part. For more on Genesys Cloud regions, refer to AWS regions for deployment. - Deployment Name — specify the Open Messaging platform name that you created on the Genesys side.
- Queue — enter the Queue ID that you copied when you created a queue on the Genesys side.
- Webhook Secret — specify the Outbound Notification Webhook Signature Secret Token that you created on the Genesys side.
- Client ID — enter the Client ID that you generated on the Genesys side.
- Client Secret — enter the Client Secret that you generated on the Genesys side.
- Host — enter the login URL for Genesys Cloud customers, which varies by region, such as
- Activate the Send Profile information setting if you want to send user information, such as the first and last name, to the human agent.
- Click Save.
Configure Handover Settings¶
In Handover to 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. - Custom Attributes — add custom attributes in the
Key: Value
format, which allows you to include additional information. For example:{ "section": "section A", "region": "Europe" }
To test connection, click Open Demo Web Chat.
(Optional) Send Genesys Bot Messages to End Users¶
Note
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 humans but end users receive these messages. Forwarding messages to the end user can be helpful in the following use cases:
- when the conversation status or wait time information is relevant to the end user.
- to provide the end user with updates and transparency throughout the interaction.
- to allow the end user to make informed decisions while waiting for a human agent, such as requesting a callback.
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 roting logic. Follow the instructions to configure this logic:
- In your chosen Handover Flow, set a Lookup Node below the Handover to Agent Node. Set Lookup Node as your Entrypoint.
- For the Type field within the Lookup Node, select Handover Status.
- For the child Case Node, specify
genericHandoverUpdate
in the Value field. - 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. - In the Handover Settings of the Say Node, select User Only from the Handover Output Destination list.
- To display all incoming Genesys Status or Bot messages, add a Go To Node below the Say Node.
- 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:
AI Copilot Workspace¶
Within Genesys integration, you can use AI Copilot Workspace as an assistant for your human agents.
By default, two versions of the application are provided:
Standalone¶
AI Copilot will be available as a standalone application via the following link:
https://${AICopilotBaseUrl}/?userId=${userId}&sessionId=${sessionId}&URLToken=${URLToken}
Where:
AICopilotBaseUrl
— the base URL of AI Copilot. It represents the main web address where the AI Copilot service is hosted.sessionId
— the Cognigy Session ID. A session is a period of interaction or communication between the human agent and the AI Copilot Workspace.userId
— the Cognigy User ID. It helps AI Copilot associate the interaction with a specific user, allowing for tracking user-specific information.URLToken
— the Endpoint token on the Cognigy side. To find this token, navigate to the Endpoint linked with AI Copilot. In the Config URL field, copy the token found afterhttps://endpoint-trial.cognigy.ai
. For example, in the URLhttps://endpoint-trial.cognigy.ai/f38791ae20d4961acf0e97d9f377c4fe3df92894e1eff1c7a774a8ed089a4590
, the token would bef38791ae20d4961acf0e97d9f377c4fe3df92894e1eff1c7a774a8ed089a4590
. Note that only authorized users can access or interact with the AI Copilot system through this URL.
For example:
https://ai-copilot-trial.cognigy.ai/?sessionId=session-17738489-e767-4d47-b669-cb0dd2e899e0&userId=52476cc5-710c-40db-8108-e99109f45d91&URLToken=a4d5c86c98f27730311591f28d194510e05ffed30ca148e3344970defd418e7d
Embedded¶
By default, you can use the embedded version of the AI Copilot workspace, but it will overlap part of the screen with the conversation. To place the workspace to the right of the chat with the conversation, follow these steps:
Create a Script¶
To create a script, follow these steps:
- Go to Endpoint Settings > Copilot.
- Copy the Copilot Embedding URL by clicking on it.
- Go to Genesys Cloud.
- Open the Admin tab.
- Under Contact Center, click Scripts.
- Click Create.
- Type a name for the script.
- Select the Blank Script template and click + Create.
- On the script page, go to the Add Components tab.
- Under the Components section, select Web Page. In the Web Page Source field, enter the Copilot Embedding URL that you copied before.
- In the Layout section, change the size of Width and Height by clicking the Stretch button.
- In the upper-right corner, go to the Variables tab.
- On the Variables tab, go to the Basic Types section and click String.
- Create a new variable:
14.1 In the Name field, enteruserId
.
14.2 In the Description field, enterCognigy variable
.
14.3 Enable the Input toggle.
14.4 Click Apply. - In the upper-left corner of the script page, click Script > Properties.
- In the Script Properties section, activate the Inbound and Message features.
- In the upper-left corner of the script page, click Script > Save, then Publish.
Add the Script to the Inbound Message Flow¶
To add the Script to the Inbound Message Flow, follow these steps:
- Open the Genesys Cloud interface.
- Go to Admin > Architect.
- Click or hover over the Flows menu and select Inbound Message.
- From the flow list, select a flow that you created before.
- To configure a flow, click Edit.
- In the flow editor, ensure that both the Get Participant Data action is added. If you haven't done so already, refer to steps 12-14 in the Create an Inbound Message Flow section.
- Below the Get Participant Data action, place Set Screen Pop action. The Set Screen Pop action must be positioned above the Transfer to ACD action.
- From the Message Script list of the Set Screen Pop action, select the script created before.
- In the Inputs action, add
userId
in the userId field. - In the upper-left corner, click Save, then Publish.