> ## 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.

# Genesys Cloud troubleshooting

> Fix Genesys Cloud connection errors, missing users or queues, handoffs that never reach a queue, agent replies that do not arrive, and sync delays.

Before debugging, have this ready:

* Your Genesys Cloud **region** and client ID.
* An OpenCX session ID from the [Inbox](https://platform.open.cx/inbox) and its Genesys conversation ID.

> [!NOTE]
>
> **Fastest path to root cause:** check **Health** on the **Setup** tab, then open the session in the Inbox. A failed handoff shows on the timeline with the reason.

## Diagnostics

Open **Settings → Ticketing → Genesys Cloud → Diagnostics**.

| Tool | What it does |
| - | - |
| **Test session** | Opens a labelled test conversation in the queue you pick. Shows each step live, links to it in Genesys, and can be ended from OpenCX. Never billed or reported. Runs no workflows. Five per 10 minutes, one at a time. |
| **Request log** | Every Genesys call and webhook for 7 days, failures first: status, duration, retries, error code and correlation ID. Quote the correlation ID to Genesys support. Holds no tokens, message text or customer data. |
| **Logs from Genesys** | What Genesys holds for a session or conversation ID: segments, flow history, audits, operational events, integration status and limits. |
| **Export** | One redacted JSON file of connection state, setup steps, health, recent failures and event counts, safe to send to support. |

In the Inbox, **Diagnostics** in a session's **Genesys Cloud** details shows that session's timeline.

Flow history needs `architect:flowInstance:search`, audits need `audits:audit:view`, and operational events need `usage:events:view`. These are optional: without one, that section says which permission it needs, and everything else works.

## Common scenarios

### **"Genesys rejected these credentials. Check the client ID, secret and region."**

Likely cause (The client ID or secret was mistyped or regenerated, or the client belongs to another region.): wrong client ID, secret or region.

**Fix:** copy both values again from **Admin → Integrations → OAuth**, confirm the grant type is **Client Credentials**, and check the [region](https://docs.open.cx/integrations/genesys/connect.md#regions).

### **"This Genesys organization is already connected to another OpenCX workspace"**

Likely cause (A Genesys organization can be linked to one OpenCX workspace at a time.): another workspace uses this organization.

**Fix:** disconnect it there first, then connect here.

### **Signing in with Genesys returns an error**

Likely cause (The sign-in was cancelled or expired, or the admin or region doesn't match.): the admin lacks permissions, or the region is wrong.

**Fix:** follow the message shown. **The Genesys admin is missing permissions** names what's missing, so sign in as an admin who has it. **That Genesys organization is in another region** means you should pick the [region](https://docs.open.cx/integrations/genesys/connect.md#regions) from your Genesys address.

### **Genesys shows its own error page after Connect Genesys**

Likely cause (Genesys stops the sign-in before it returns to OpenCX.): your org enforces OAuth scopes and this admin can't approve new applications.

**Fix:** sign in as an admin with `oauth:client:authorize`, or [connect with a client ID and secret](https://docs.open.cx/integrations/genesys/connect.md).

### **A setup step shows failed or action required**

Likely cause (Genesys returned an error, or the step needs a choice from you.): the step is waiting for you, or Genesys returned an error.

**Fix:** use the button beside the step. See [Finish setup](https://docs.open.cx/integrations/genesys/connect.md#finish-setup).

### **OpenCX can't see your users or queues**

Likely cause (Genesys hides everything outside the divisions the role is granted in.): they're in a division the role isn't granted in.

**Fix:** if you connected by signing in, click **Reconnect** and choose that division too. With a client ID and secret, grant the role there in Genesys and compare it with [Permissions](https://docs.open.cx/integrations/genesys/connect.md#permissions).

### **Routing asks you to choose a queue again**

Likely cause (OpenCX can't hand sessions to a queue it can't see.): the default queue is outside the divisions the connection can see.

**Fix:** choose a queue beside **Routing**, or add its division.

### **Reconnect says `oauth:client:edit` is missing**

Likely cause (Updating an existing OAuth client's divisions needs this permission. Connecting doesn't.): the admin changed the divisions but can't edit OAuth clients. The connection keeps the divisions it had.

**Fix:** sign in as an admin with `oauth:client:edit`, or keep the current divisions.

### **A handoff runs but nothing appears in the queue**

Likely cause (Genesys accepted the conversation, but no flow is bound to the OpenCX connection, or the flow can't find the queue.): no flow is bound, or `opencx_queue_id` doesn't match a queue.

**Fix:** click **Run check** under **Tools**. Bind a flow to the **OpenCX** connection under **Admin → Routing → Message Routing**, and make sure it has a [fallback queue](https://docs.open.cx/integrations/genesys/conversations.md#use-your-own-flow).

### **The session shows a failed handoff**

Likely cause (Genesys refused or didn't answer. Common reasons are a missing messaging connection, the integration being off, or a licence without digital messaging.): the integration is off or the messaging connection is gone.

**Fix:** read the reason on the timeline. Check **Genesys connection on** on the **Handoff** tab, then click **Repair** under **Health** if the connection was removed.

### **The Knowledge import asks for permissions**

Likely cause (Signing in adds Knowledge access only when the admin holds it, so connecting never depends on it.): the role can't read Genesys Knowledge.

**Fix:** add `knowledge:knowledgebase:view` and `knowledge:document:view` to the role OpenCX uses, then click **Import** again.

### **Agent replies don't reach the customer**

Likely cause (WhatsApp's 24-hour window is the usual reason. The messaging connection may also have been changed in Genesys.): the channel refused the reply, or the messaging connection changed.

**Fix:** read the reason in `opencx_notes` or the session's internal note. For WhatsApp, send a template from OpenCX. Otherwise check **Health** and click **Repair**.

### **A returning customer lands in an old conversation**

Likely cause (Genesys adds new messages to the customer's previous conversation for as long as the threading timeline allows.): threading is still on.

**Fix:** click **Turn off threading** under **Conversation threading** on the **Setup** tab.

### **Reassigning or changing team doesn't move the conversation**

Likely cause (OpenCX can only transfer to a linked agent or queue, and agent transfers need Agent sync.): the teammate or team isn't linked, **Agent sync** is off, or Genesys refused the transfer. Genesys refuses transfers asked for by a connection that isn't in the conversation, and the session then has an internal note saying so.

**Fix:** [link them](https://docs.open.cx/integrations/genesys/connect.md#link-agents-and-queues). A session also assigned to a linked agent goes to that agent, not the queue. If the internal note is there, move the conversation in Genesys.

### **The session stays open after the conversation ends**

Likely cause (Updates usually arrive within about a minute, and pause while the connection needs reconnecting.): the update hasn't arrived, the setting returns it to the AI, or **Reconnect needed** is showing.

**Fix:** wait a minute. Then check **When a Genesys conversation ends** and the connection status.

### **Sessions don't get a workitem**

Likely cause (Workitems need a worktype and a mode that covers the session.): **Create a workitem for** doesn't cover the session.

**Fix:** check [Workitems](https://docs.open.cx/integrations/genesys/conversations.md#workitems) and compare the role with [Permissions](https://docs.open.cx/integrations/genesys/connect.md#permissions).

### **The Assist panel says "This conversation is not available to Assist."**

Likely cause (The panel shows only sessions from your connected OpenCX organization, to agents on the conversation.): the conversation didn't come from OpenCX, or the agent isn't on it.

**Fix:** open the panel from a handed-off conversation, as an agent on it.

### **None of the above**

Contact [support@open.cx](mailto:support@open.cx) with the OpenCX session ID, the Genesys conversation ID and a timestamp.

***

## Related Documentation

> [card] [Connect Genesys Cloud](https://docs.open.cx/integrations/genesys/connect.md)
>
> Region, credentials and permissions.

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

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

> [card] [Human handoff](https://docs.open.cx/handoff/introduction.md)
>
> When the AI hands a session to a person.


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