RingCentral Engage: Handover Integration

This page describes the process to configure the RingCentral Engage Handover Integration.

For Endpoints that support Handover, RingCentral Engage can be chosen as the selected Handover Provider. When this is selected, all handover requests will be routed to RingCentral Engage and be processed by an agent.

Requires a RingCentral Engage Subscription

This guide assumes that you already have an active RingCentral Engage subscription.

Requires "Admin" role in RingCentral Engage

The steps described in this guide are only executable by users with an "Admin" role.

Configuring RingCentral Engage Handover Settings

In order to configure the RingCentral Engage Handover settings, RingCentral Engage first has to be chosen as the selected Handover Provider in the Endpoint in the Handover Settings tab. This will make the settings that have to be configured appear. 

RingCentral Engage Handover Settings

There is also a toggle called Forward Only Handover Conversations which is turned off per default. This means that all conversations users have with your Endpoint will also be forwarded to RingCentral Engage. They will be marked as Bot conversations until the Handover node is triggered, where they will then get the Agent category assigned.

If this setting is turned on, only conversations that actually trigger a handover is sent to RingCentral Engage.

The next chapter describes how setup RingCentral Engage and how to find the settings needed in the Handover Settings.

Integrate the RingCentral Engage Endpoint with your RingCentral Engage Platform

:link: Location: RingCentral Engage Platform

✔ Your role on RingCentral Engage must be Admin
✔ A community has to exist in RingCentral Engage

In this chapter, all required components are configured within RingCentral Engage and the necessary settings are extracted for the Handover Settings in the Endpoint. These settings can be found in the green boxes throughout this chapter.

Creating the API Access Token

In the "ADMIN" section in the top bar of the RingCentral Engage platform, navigate to "API access tokens" from the sidebar on the left.
Click the "+" button in the top-right section to create a new API Access Token.
Select an Agent that should be used to chat with the users.


"API Access Token"

The text next to your API Access Tokens name on the "API access tokens" page is the one required for the "API Access Token" field in the Handover Settings within the Endpoint in Cognigy.AI.

Creating the Categories

Navigate to "Categories" in the sidebar of the "ADMIN" page.
In the "ADMIN" section in the top bar of your RingCentral Engage platform, navigate to "Categories" from the sidebar on the left.
Click the "+" button in the top-right section to create a new Category.
Fill out the "Name" field (e.g. Cognigy), leave all other fields to their default and confirm by clicking "Save".


Repeat that step twice to create the "Bot" and "Agent" category and select the previously created "Cognigy" category as a parent.


You should end up with a "Cognigy" category with "Agent" and "Bot" subcategories.


Categories can be assigned to conversation threads within the RingCentral Engage platform.
If a message arrives in a thread that has the "Bot" category assigned, that message will be processed by the Cognigy bot.

"Bot Category Id" + "Agent Category Id"

By double-clicking the "Bot" or "Agent" category, its configuration page will open. In the URL at the top of your browser, the category id will show in the URL:

xxxxx.engagement.dimelo.com/admin/categories/ CATEGORY_ID /edit

These Ids are needed for the "Bot Category Id" and "Agent Category Id" fields in the Handover S ettings in the Endpoint in Cognigy.AI.

Creating the Source

The Handover integration needs to connect to a `Source` in RingCentral Engage. This source needs to be of type `Engage Digital source SDK`. This can be created by navigating to "Sources" in the sidebar in the "ADMIN" section in RingCentral Engage.

After creating the Source, Base URI field has to be filled with the URL: <endpoint-url>/handover/rce where the is the Endpoint doman for the Cognigy.AI environment in question (e.g. https://endpoint-dev.Cognigy.AI).

The default categories field in the Message Settings section in the Source should be set to the Bot Category that was created earlier.

Realtime Access Token

The value of the API access token field in the Source has to be copied into the field Realtime Access Token in the Handover Settings within the Endpoint in Cognigy.AI.

Realtime Endpoint URL

The Realtime endpoint URL that is found within the Implementation Details section in the source in RingCentral Engage. This URL has to be copied into the Realtime Endpoint URL field in the Handover Settings within the Endpoint in Cognigy.AI.

Configuring the Source in RingCentral Engage

After the source has been configured, every agent who needs to work with the source has to have read and reply permissions for the source. This is configured by going to the Agents overview and clicking on the key icon for the agent in question.

Apple Business Chat

The reply permission is required for owners of the API token on all sources that are not the custom source SDK.

Creating the Webhook

Navigate to "Webhooks" in the sidebar on the "ADMIN" page.
Click the "+" button on the top right to crate a new Webhook.


SETTINGS section

In "Api access token", select the previously created Api Access token.

Set "Active" to "on" with a checkmark.

For "URL", insert the the following URL: <endpoint-url>/handover/rce, where you replace the with the Endpoint URL for your Cognigy.AI environment (e.g. https://endpoint-demo.Cognigy.AI).

Fill "Secret" with a randomly generated value.


The "Secret" text value is the one required for the "Webhook Secret" field in the Handover Settings within Cognigy.AI.

FILTERS section

Set "Sources filtering strategy" to "No sources except".
In "Sources", select the source that was created earlier.


In "Registered Events", add "intervention.closed" via the dropdown.

Verification Token

The verification token has to be changed to match the verification token configured for your Cognigy.AI environment. The token is by default set to cognigy123 but it depends on the installation of your Cognigy.AI platform (for further informations please contact the technical support).

By now, the webhook has been fully configured, and you can therefore click on "Save".

Getting the Base API URL

The Base API URL setting which needs to be configured in the Endpoint in Cognigy.AI is the URL pointing to the API of the RingCentral Engage environment. The API URL can be constructed by inserting api after the environment name in the URL. Example:

URL: cognigy.engagement.dimelo.com
API URL: cognigy.api.engagement.dielo.com

Initial Handover Test

After filling in the Handover Settings of the Endpoint, a first test of the Handover configuration has to be made before the configuration in RingCentral Engage can be completed. The reason for this is that certain identities have to be created in RingCentral Engage, which happens when the first user talks to the Endpoint.

To make this initial test, a Flow containing just a Handover Node has to be created and the Endpoint with the Handover Settings has to point to this Flow. Send a message to the Endpoint and the first conversation should be created in RingCentral Engage.

Creating Bot Identities in RingCentral Engage

When the first conversation has been created in RingCentral Engage, a few things have to be configured. Per default, the messages from the Bot will not appear on the right side of the messaging window, but will appear on the left side together with the user messages. It is also not possible to reply to the user before an Agent identity has been assigned to the agent.

In order to make the Bot messages appear on the right side of the screen as a normal conversation view, the Bot user has to a controlled identity first. This is done by going to the Identities page in RingCentral Engage and selecting the Bot identity. The checkbox Controlled identity then has to be checked. This will ensure that on all new conversations, the Bot messages appear correctly on the right side in the message window.

Seeing all identities in RingCentral Engage

Changing the Bot Identity

In order to reply to the user, the agent in question first have to have a controlled identity assigned. An Agent identity has therefore also been created, which can be edited and made controlled in the same way as the Bot identity.

Changing the Agent Identity

After the Agent identity has been made controllable, it has to be assigned to agents who should be able to reply to the users. This is done by navigating to the Agents view and clicking on the contact book icon for the agent in question. Here the correct community has to be selected and thereafter the Agent user. Note that the + icon has to be clicked before clicking "Save".

Assigning Identities to Agents

Chatting with Users in RingCentral Engage

In order to chat with users, go to the "Desks > Folders" view. Here all messages from the users come in. When the user has started a handover, the chat will get the category Agent. Is therefore useful to setup a folder that has all chats with the category Agent, so that the agents can easily see which users they need to respond to.




Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful