> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Genesys Cloud

> Connect Genesys Cloud to OpenCX by signing in or with client credentials, choose where handoffs go, and link your agents and queues.

Connect first, then go live when you're ready. Connecting is silent: your customers, your AI and your queues carry on exactly as before until an admin clicks **Go live**.

Genesys Cloud flow: customer channels reach the OpenCX AI; on handoff OpenCX opens a Genesys message conversation that your Architect flow routes to a queue, and agent replies return to the customer's channel

## Before you start

* A Genesys Cloud admin who can create roles and OAuth clients, usually **Master Admin**.
* A Genesys Cloud licence that includes digital messaging, or setup stops. To import articles, also Genesys Knowledge.
* The **Manage integrations** permission in OpenCX (`settings-integrations:write`).

## Connect

> [tab] Sign in with Genesys (recommended)
>
> **1. Open the integration**
>
> Go to [**Settings → Ticketing**](https://platform.open.cx/settings/ticketing) and choose **Genesys Cloud**.
>
> **2. Pick your region**
>
> Under **Region**, choose the one in your Genesys address. See [Regions](#regions).
>
> **3. Sign in**
>
> Click **Connect Genesys**, sign in as a Genesys admin and approve.
>
> OpenCX creates an **OpenCX Integration** role, gives it to the admin signing in (Genesys only lets you grant a client a role you hold), creates an **OpenCX** OAuth client, then runs setup. If the admin is missing permissions, it lists them and creates nothing.
>
> If your org has more than one division, you choose **All divisions** (the default) or specific ones before anything is created. To change them later, sign in again with **Reconnect**.

> [tab] Client ID and secret
>
> Use this for US East 2 (FedRAMP), which doesn't support sign-in. On FedRAMP, agents can't sign in to the [Assist panel](https://docs.open.cx/integrations/genesys/conversations.md#assist-panel) either.
>
> **1. Create a role in Genesys**
>
> In **Admin → Roles / Permissions**, create a role with the [permissions](#permissions) below and grant it in the divisions OpenCX should work in. OpenCX shows what it can see under **Connection**, but only Genesys can change it.
>
> **2. Create an OAuth client**
>
> In **Admin → Integrations → OAuth**, add a client with grant type **Client Credentials** and assign the role. Copy the client ID and secret.
>
> **3. Connect in OpenCX**
>
> Go to [**Settings → Ticketing**](https://platform.open.cx/settings/ticketing) and choose **Genesys Cloud**. Pick the **Region**, paste both values and click **Test & Connect**.
>
> **4. Run setup**
>
> On the **Setup** tab, click **Run setup**.

## Finish setup

On the **Setup** tab:

**1. Routing**

Choose a queue. It becomes your **Default queue**. To use your own flow, choose **Use my own flow** instead, enter the **Flow ID** and click **Save**. See [Use your own flow](https://docs.open.cx/integrations/genesys/conversations.md#use-your-own-flow).

**2. Conversation threading**

Click **Turn off threading** so each handoff starts a new Genesys conversation. This changes a setting for your whole Genesys organization, and OpenCX names the other connections it affects. With **Keep**, a returning customer can join an older conversation.

**3. Connection check**

Under **Tools**, click **Run check**. It sends a message through the OpenCX flow and checks the reply. With your own flow, use **Test session** on the **Diagnostics** tab instead. Then hand off a real session, accept it in Genesys Cloud and reply. The reply should reach the customer's channel.

If a step fails, use the button beside it: **Retry**, **Reconnect** or **Open in Genesys**. Running setup again is safe.

## Roll out step by step

**1. Connect**

Your **Autopilot** settings, ticketing system, teammates and open sessions don't change. In Genesys, setup adds only OpenCX's own objects: a role, an OAuth client, a messaging connection and a message flow. It changes no existing queue, flow or route.

**2. Set up and test**

Finish setup and link your agents and queues. Use **Test session** on the **Diagnostics** tab to send a labelled session to a queue you choose and watch it end to end.

**3. Decide where the AI answers**

Check your Autopilot settings before you go live. Connecting and going live never change them, and the AI answers only on channels where autopilot is on. A channel with autopilot off hands each new session to your team.

**4. Go live**

On the **Setup** tab, click **Go live**. Handoffs from now on open Genesys conversations, and Genesys becomes your ticketing system, replacing any other. Sessions already with your team stay in OpenCX. To stop new handoffs later, turn off **Genesys connection on**.

**5. Turn on the rest, one at a time**

Each is off until you choose it: **Agent sync**, **Presence sync**, [native messaging](https://docs.open.cx/integrations/genesys/native-messaging.md), [native email](https://docs.open.cx/integrations/genesys/native-email.md) and [phone calls](https://docs.open.cx/integrations/genesys/voice.md). The native channels and phone calls need you to go live first.

OpenCX moves a conversation between queues only when you link a team to a queue and change the session's team, or turn on **Agent sync** and reassign it.

## Link agents and queues

On the **Directory** tab, link each Genesys item to its OpenCX counterpart. Click **Link to** a suggested match or pick one from the list. The directory refreshes about every half hour, or click **Refresh** beside **Refresh directory** on the **Setup** tab.

| Genesys Cloud | OpenCX | Notes |
| - | - | - |
| **Agents** | Teammates | Linked automatically when the email matches. |
| **Queues** | Teams | Handoffs from a team go to its queue. **Import as team** creates the team and adds linked queue members. Linked agents who later join the queue are added on each sync, and those who leave stay on the team. |
| **Skills** | Skills | Used for routing hints and workitems. |
| **Wrap-up codes** | Sub-statuses | A wrap-up sets the sub-status when the session closes, and the reverse applies when OpenCX closes it. |
| **Presence statuses** | Availability statuses | Optional. **Presence sync** is off by default. **From Genesys** reads it about once a minute. **Both ways** also sets Genesys presence from OpenCX. |

An unlinked presence maps to available for **Available** and **On Queue**, and to away otherwise.

## Permissions

The role OpenCX uses needs these. Signing in creates it for you and grants it in the divisions you choose. If you create it yourself, grant it in the divisions OpenCX should work in.

> [!NOTE]
>
> The role reads and writes only in the divisions it's granted in, so OpenCX can't see agents, queues or flows outside them. Its message flow goes in a chosen division: Home if you chose it, otherwise the first by name. Genesys doesn't divide messaging connections, the Assist panel or presence definitions, so those are org-wide, and contacts with no division stay visible.
>
> It can't change queues. Without `routing:queue:add` it can't create them either. Creating an email route or adding queue members always needs a Genesys login with routing write access.

| Area | Permissions |
| - | - |
| Messaging | `messaging:integration:add`, `messaging:integration:view`, `messaging:integration:edit`, `messaging:integration:delete`, `routing:message:manage`, `routing:conversation:edit`, `conversation:message:create`, `conversation:message:receive`, `conversation:communication:view`, `conversation:communication:disconnect`, `conversation:communication:blindTransfer`, `conversation:participant:wrapup`, `conversation:participant:attributesview`, `conversation:threadingTimeline:view`, `conversation:threadingTimeline:edit` |
| Directory | `directory:user:view`, `routing:queue:view`, `routing:skill:view`, `routing:wrapupCode:view`, `groups:team:view`, `presence:presenceDefinition:view`, `presence:userPresence:edit` |
| Analytics | `analytics:conversationDetail:view`, `analytics:queueObservation:view` |
| External contacts | `externalContacts:contact:add`, `externalContacts:contact:view`, `externalContacts:contact:edit`, `externalContacts:contact:enrich`, `externalContacts:identity:merge`, `externalContacts:externalSource:add`, `externalContacts:externalOrganization:add`, `externalContacts:externalOrganization:view`, `externalContacts:externalOrganization:edit`, `externalContacts:externalOrganization:enrich` |
| Flow and panel | `integrations:integration:add`, `integrations:integration:view`, `integrations:integration:edit`, `integrations:integration:delete`, `architect:flow:view`, `architect:flow:add`, `architect:flow:edit`, `architect:flow:delete`, `architect:flow:publish`, `architect:flow:unlock`, `architect:job:create`, `architect:job:view`, `architect:ui:view`, `oauth:client:view` |

These depend on your Genesys licence and never block connecting. Signing in adds the ones the admin holds. Without them, connecting works and only that feature stays off.

| Feature | Permissions |
| - | - |
| Workitems | `workitems:workitem:add`, `workitems:workitem:view`, `workitems:workitem:edit`, `workitems:worktype:view`, `workitems:status:view`, `workitems:workitemSchema:view` |
| Call recordings | `recording:recording:view` |
| Genesys transcription for live assist | `conversation:transcription:view` |
| Knowledge import | `knowledge:knowledgebase:view`, `knowledge:document:view` |
| Native email | `conversation:agentlessEmail:send`, `routing:queue:add` |
| Native messaging | `integration:botconnector:send`, `conversation:message:view` |
| Diagnostics | `architect:flowInstance:search`, `audits:audit:view`, `usage:events:view` |

To sign in, the admin also needs `authorization:role:view`, `authorization:role:add`, `authorization:role:edit`, `authorization:division:view`, `authorization:grant:add` and `oauth:client:add`. Changing divisions on a later sign-in also needs `oauth:client:edit`. If your org enforces OAuth scopes, the first sign-in also needs `oauth:client:authorize`, to approve OpenCX under **Authorized Applications**.

## Regions

| Region | Genesys Cloud address |
| - | - |
| US East (Virginia) | `mypurecloud.com` |
| US East 2 (FedRAMP) | `use2.us-gov-pure.cloud` |
| US West (Oregon) | `usw2.pure.cloud` |
| Canada | `cac1.pure.cloud` |
| South America (São Paulo) | `sae1.pure.cloud` |
| Europe (Ireland) | `mypurecloud.ie` |
| Europe (London) | `euw2.pure.cloud` |
| Europe (Frankfurt) | `mypurecloud.de` |
| Europe (Zurich) | `euc2.pure.cloud` |
| Middle East (UAE) | `mec1.pure.cloud` |
| Asia Pacific (Mumbai) | `aps1.pure.cloud` |
| Asia Pacific (Tokyo) | `mypurecloud.jp` |
| Asia Pacific (Seoul) | `apne2.pure.cloud` |
| Asia Pacific (Osaka) | `apne3.pure.cloud` |
| Asia Pacific (Sydney) | `mypurecloud.com.au` |

## Settings reference

All of these are on the **Handoff** tab.

| Setting | Purpose | Default |
| - | - | - |
| **Genesys connection on** | Off stops new handoffs, AI answers on native Genesys channels and updates from Genesys. The connection stays. | On |
| **Handoff routing** | **Let my Genesys flow decide**, **Always use the default queue** or **Prefer an agent**. | Let my Genesys flow decide |
| **Default queue** | Where handoffs go when nothing else picks a queue. | None |
| **Preferred agent** | The agent **Prefer an agent** adds to participant data. | None |
| **Agent sync** | Keeps the Genesys agent and the session assignee matched, both ways. | Off |
| **Smart routing** | Picks the queue with live agents who fit the session's skills and language. | Off |
| **When no agents are on the queue** | **Hand off anyway**, **Keep with the AI** or **Create a workitem**. See [no agents](https://docs.open.cx/integrations/genesys/conversations.md#when-no-agents-are-available). | Hand off anyway |
| **When a Genesys conversation ends** | **Close the session** or **Return to the AI**. | Close the session |
| **AI answers after wrap-up** | Hands the session back to the AI after a wrap-up that doesn't close it. | Off |
| **Wrap-up code suggestions** | **Off**, **Suggest** or **Pre-fill when sure**. See [suggestions](https://docs.open.cx/integrations/genesys/conversations.md#wrap-up-code-suggestions). | Off |
| **Default wrap-up code** | Applied to the agent when OpenCX ends a Genesys conversation. | None |
| **Worktype** / **Create a workitem for** | See [Workitems](https://docs.open.cx/integrations/genesys/conversations.md#workitems). | Never |
| **AI attributes** | See [AI attributes](https://docs.open.cx/integrations/genesys/conversations.md#ai-attributes). | None |

**Native email** and **Native messaging** are on the **Channels** tab. See [Channels](https://docs.open.cx/integrations/genesys/conversations.md#channels).

## Health and secrets

**Health** on the **Setup** tab lists only what needs attention. Click **Fix** beside a check, or **Repair** when something was changed in Genesys. **Undelivered messages** lists what still failed after a day of retries. **Retry** sends them now, so a customer may get an old reply.

If the connection stops working, the integration shows **Reconnect needed**. Click **Reconnect**, or with a client ID and secret, enter the new secret under **Rotate client secret** on the **Connection** tab. After **Rotate webhook secret**, the old secret keeps working for an hour.

## Disconnecting

On the **Connection** tab, click **Disconnect**, type your Genesys organization name and confirm.

OpenCX removes what it created in Genesys and lists anything it couldn't under **Remove these in Genesys**. The OAuth client and role usually need a Genesys admin. Sessions are kept, but replies to conversations still open in Genesys no longer reach customers.

Disconnecting also ends any open test session and removes the imported Genesys Knowledge articles. The live phone assist API key and client secret stop working, so create a new pair if you connect again. Moving to a different Genesys organization does the same. With a client ID and secret you can move directly. To move by signing in, disconnect first, because signing in to a different organization is refused while you're connected. A move also turns off [native messaging](https://docs.open.cx/integrations/genesys/native-messaging.md) and [native email](https://docs.open.cx/integrations/genesys/native-email.md) and clears their connection secret, queues and address, and removes the links between your teams, agents, skills, statuses and presences and the old organization, so set them up again for the new one. Contacts and companies link again at their next handoff. Reconnecting to the same organization keeps all of this.

Both also stop work still waiting on the old connection: calls still in progress are ended in OpenCX, recordings and transcripts not yet brought over stay in Genesys, and messages not yet processed are dropped. A session linked to the old conversation opens a new one with the customer's next message.

***

## Related Documentation

> [card] [Conversations & sync](https://docs.open.cx/integrations/genesys/conversations.md)
>
> Handoff, routing and what syncs each way.

> [card] [Phone calls & live assist](https://docs.open.cx/integrations/genesys/voice.md)
>
> Add transcripts and suggestions to Genesys calls.

> [card] [Genesys Cloud overview](https://docs.open.cx/integrations/genesys/overview.md)
>
> What the integration does.

> [card] [Troubleshooting](https://docs.open.cx/integrations/genesys/troubleshooting.md)
>
> Credential errors, empty queues, missing replies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.