> ## 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. Watch first**

Turn on **Show every Genesys conversation** on the **Channels** tab to see your Genesys email and messaging as sessions while agents keep working in Genesys. The AI answers customers waiting in a queue when autopilot is on for their channel, so check autopilot for each channel first. Switch off queues you don't want in the **Queues** list on the **Directory** tab, and check your workflows and team assignment first. See [See every Genesys conversation](https://docs.open.cx/integrations/genesys/conversations.md#see-every-genesys-conversation).

**6. 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, or turn on [Sync queues as teams](#sync-queues-as-teams) for every queue. 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.

### Sync queues as teams

Turn on **Sync queues as teams** on the **Directory** tab to bring in every Genesys queue as a team, whatever its channel. Turning it on refreshes the directory at once, and every refresh after that:

* Creates a team for each new queue, named after it, with the linked agents who are members of the queue. A team you already have with the same name is linked instead of copied.
* Renames a linked team when its queue is renamed. While it's on, linked teams take their queue's name.
* Unlinks the team of a queue deleted in Genesys. The team, its members and its sessions stay.

When Genesys moves a conversation to a queue, the session moves to that queue's team. New teams use manual assignment, because Genesys routes their conversations. A team you already had keeps its own settings when it's linked, so turn on support for it if sessions should move into it.

To leave a queue out, such as sales or partner support, switch it off in the **Queues** list. Do this before you turn the sync on, so no team is made for it. A queue you leave out keeps any team already linked to it. To remove a queue's team, switch the queue off first, then delete the team. A deleted team comes back on the next refresh while its queue is on.

**Sync queues as teams** is off by default, so connecting creates no teams. Connecting to a different Genesys org turns it off again and clears the queues you left out, because they belong to the old org.

## 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, and messaging in **Past conversations** imports | `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, and flow messages shown as the flow's on handed-off messaging sessions | `integration:botconnector:send`, `conversation:message:view` |
| WhatsApp templates sent from the inbox | `responses:response:view` |
| Diagnostics | `architect:flowInstance:search`, `audits:audit:view`, `usage:events:view` |
| Typed custom fields on contacts and companies | `externalContacts:customFields:view` |
| Conversation custom attributes (Genesys Cloud CX 2 or higher) | `conversation:customAttributes:view`, `conversation:customAttributes:edit` |

Calls and callbacks in **Show every Genesys conversation**, and notes on external contacts in both directions, need nothing beyond the permissions above.

Add these to the role yourself if you want them. Signing in doesn't add them.

| Feature | Permissions |
| - | - |
| [Genesys summaries](https://docs.open.cx/integrations/genesys/conversations.md#genesys-summaries-and-analytics) | `conversation:summary:view` |
| [Sentiment and categories](https://docs.open.cx/integrations/genesys/conversations.md#genesys-summaries-and-analytics), filling gaps in call transcripts, and the transcript of [calls you see without streaming](https://docs.open.cx/integrations/genesys/conversations.md#calls-and-callbacks) | `speechAndTextAnalytics:data:view`, `recording:recording: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 |
| **Share OpenCX context with Genesys** | Writes the session's summary, intent, outcome and the customer's other sessions onto each Genesys conversation, and routes waiting emails by them. See [OpenCX context](https://docs.open.cx/integrations/genesys/conversations.md#opencx-context-for-agents-flows-and-reports). | On |
| **Handoff summary note** | Puts a note for the agent in the Genesys transcript at handoff: why, the summary, language, sentiment and a link to the session. The customer never sees it. See [Handoff note](https://docs.open.cx/integrations/genesys/conversations.md#handoff-note). | On |
| **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 |

**Show every Genesys conversation** (off by default; needs go-live), **Native email** and **Native messaging** are on the **Channels** tab. See [See every Genesys conversation](https://docs.open.cx/integrations/genesys/conversations.md#see-every-genesys-conversation) and [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.