> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Initial configuration

Before the Genesys handoff can be enabled, Genesys Cloud must be configured on your side and a set of credentials must be gathered for Ada. Complete the requirements below in your Genesys Cloud organization, then share the credentials your Ada team needs to finish the backend integration. This guide assumes an active Genesys Cloud organization with at least one Inbound Message flow enabled.

## Licensing prerequisites

The integration is built on Genesys [Open Messaging](https://help.mypurecloud.com/articles/about-open-messaging/) and [Process Automation](https://developer.genesys.cloud/platform/process-automation/), which require one of the following Genesys Cloud licenses:

* Genesys Cloud CX 1 Digital Add-on II
* Genesys Cloud CX 2 Digital
* Genesys Cloud CX 3 Digital

## Identify the Genesys Cloud region

Note which AWS region your Genesys Cloud organization is hosted in. The connector uses an AWS-style region key and maps it to the corresponding Genesys Cloud domain at runtime.

| AWS region key   | Genesys Cloud domain     |
| ---------------- | ------------------------ |
| `us-east-1`      | `mypurecloud.com`        |
| `us-east-2`      | `use2.us-gov-pure.cloud` |
| `us-west-2`      | `usw2.pure.cloud`        |
| `ca-central-1`   | `cac1.pure.cloud`        |
| `eu-central-1`   | `mypurecloud.de`         |
| `eu-central-2`   | `euc2.pure.cloud`        |
| `eu-west-1`      | `mypurecloud.ie`         |
| `eu-west-2`      | `euw2.pure.cloud`        |
| `ap-south-1`     | `aps1.pure.cloud`        |
| `ap-northeast-1` | `mypurecloud.jp`         |
| `ap-northeast-2` | `apne2.pure.cloud`       |
| `ap-northeast-3` | `apne3.pure.cloud`       |
| `ap-southeast-2` | `mypurecloud.com.au`     |
| `sa-east-1`      | `sae1.pure.cloud`        |
| `me-central-1`   | `mec1.pure.cloud`        |

## Create an Inbound Message flow

The Inbound Message flow determines how Genesys routes new Open Messaging conversations to queues. If one does not already exist, create it — see [Inbound Message Flows](https://help.mypurecloud.com/articles/inbound-message-flows/) for the full Genesys documentation.

> **Info**
>
> Any custom attributes passed from Ada must first be retrieved and assigned to a variable in this flow using the **Get Participant Data** action. The end user's email and name, sent in the handoff, are also available as the built-in variables `Message.Message.senderAddressInfo.email` and `Message.Message.senderAddressInfo.name`.

## Set the Open Messaging Threading Timeline

It is recommended to set the Threading Timeline value to **0 minutes** for Open Messaging under **Admin → Message → Threading Timeline**. This prevents Genesys from merging a new Ada handoff into a previous Open Messaging conversation from the same end user.

## Create a role for the integration

Create a new role in Genesys under **Admin → People & Permissions → Roles / Permissions** with at least the following permissions:

* `routing:message:manage`
* `messaging:integration:add`
* `messaging:integration:view`
* `messaging:integration:delete`
* `integrations:integration:add`
* `integrations:integration:delete`
* `integrations:integration:edit`
* `integrations:action:add`
* `integrations:action:delete`
* `architect:flow:add`
* `architect:flow:edit`
* `architect:flow:publish`
* `architect:flow:delete`
* `processautomation:trigger:add`
* `processautomation:trigger:delete`
* `conversation:participant:wrapup`
* `conversation:message:receive`
* `oauth:client:view`
* `authorization:role:view`

> **Info**
>
> Ada's installation process validates the full set of permissions up front. If anything is missing, your Ada team will reach out with every missing permission, so they can all be granted in one pass.

## Create an OAuth client for Ada

Under **Admin → Integrations → OAuth**, create a new OAuth client that Ada uses to provision and operate the integration.

**To create the OAuth client:**

1. Set the **Grant Type** to **Client Credentials**.
2. Set the **Authorized Roles** to the role created in the previous step.
3. Set the **Assigned Divisions** to the division or divisions the integration should operate in. If the client is restricted to a single division, note the **Division ID** to provide to your Ada team.
4. Save the **Client ID** and **Client Secret**.
   These are required by your Ada team to install the integration.

## Credentials to provide

Once the prerequisites are complete, share the following with your Ada team so they can install the integration:

1. **Genesys Cloud region** — the AWS region key from the table above (for example, `us-east-1`)
2. **OAuth Client ID**
3. **OAuth Client Secret** — share securely with your Ada team, not in a shared channel
4. **Genesys Division ID** *(optional)* — only required if the OAuth client is restricted to a specific division

Share these credentials securely with your Ada representative. Once your Ada team has them, they complete the backend setup and confirm when the integration is ready to configure.

## Associate the Open Messaging integration with the Inbound Message flow

After your Ada team confirms the integration is installed, complete the routing association in Genesys. Without it, no messages can be routed from Ada to Genesys.

Ada's installation creates an Open Messaging integration named `Ada - <bot-handle>`.

**To associate the Open Messaging integration:**

1. Go to **Admin → Orchestration → Routing → Message Routing**, find the `Ada - <bot-handle>` address, and associate it with the Inbound Message flow you want Ada handoffs to route through.
2. *(Optional)* Go to **Admin → Message → Platforms** and update the supported content profile on the `Ada - <bot-handle>` Open Messaging integration if you want to support a different set of file types than the default — see [Supported Content Profiles](https://help.mypurecloud.com/articles/supported-content-profiles/). The supported file types are limited by what Genesys and Ada both support.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).