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

### **The past conversations import asks for permissions**

Likely cause (Signing in adds recording access only when the admin holds it, so connecting never depends on it.): the role can't read conversation analytics, or the transcripts Genesys keeps for ended messaging conversations. Without the second, emails import and messaging is skipped.

**Fix:** add `analytics:conversationDetail:view` and `recording:recording:view` to the role OpenCX uses, then click **Resume** beside **Past conversations**.

### **Health shows a Custom attributes warning**

Likely cause (Conversation custom attributes need Genesys Cloud CX 2 or higher. Signing in adds their permissions only when the admin holds them.): the Genesys licence or the role doesn't allow conversation custom attributes. Participant data, contacts and the rest of the sync keep working.

**Fix:** if you don't use conversation custom attributes, nothing is needed. Otherwise add `conversation:customAttributes:view` and `conversation:customAttributes:edit` to the role OpenCX uses. The warning clears within a day, when OpenCX tries 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 reply from the inbox is refused or not sent**

Likely cause (OpenCX replies in a Genesys conversation the way the AI does, and only while nobody holds it in Genesys.): an agent accepted the conversation in Genesys, the session is on SMS or another messenger that can't take a reply in an ongoing conversation (or Genesys never said which messenger it is), or the session was imported from past conversations. WhatsApp takes only templates: use **Send template**.

**Fix:** reply in Genesys. If the agent hands the conversation back to the queue, replies from the inbox work again within about a minute. An internal note on the session says why a reply wasn't sent. A long reply Genesys refused part-way through gets a note with the part the customer didn't get.

### **A WhatsApp template from the inbox is refused, or none are listed**

Likely cause (Templates come from Genesys's own WhatsApp templates and go out through the conversation's WhatsApp number in Genesys.): an agent holds the conversation in Genesys, the role OpenCX uses can't read templates, the conversation's number isn't a WhatsApp number in Genesys, or Genesys refused the template (for example, it needs header or button values).

**Fix:** the error says which. Reply in Genesys while an agent holds the conversation. For an empty list or a read error, reconnect Genesys with an admin who holds `responses:response:view`, or add it to the role. New templates show up within five minutes. Send templates that need header or button values from Genesys.

### **A note says Genesys could not deliver a message**

Genesys reported that a message didn't reach the customer, and the note gives its reason. On WhatsApp this is usually a reply sent outside the 24-hour window, which needs a template. Send it again from Genesys once the reason is fixed.

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

### **Health shows Email routing with a warning**

Likely cause (Genesys refused a routing change for a waiting email. OpenCX stops asking for a day, so nothing retries in a loop.): the role OpenCX uses lacks `routing:conversation:edit`.

**Fix:** add it to the role (see [Permissions](https://docs.open.cx/integrations/genesys/connect.md#permissions)). The warning clears within a day, and participant data keeps arriving meanwhile.

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

### **A Genesys conversation doesn't appear in the inbox**

Likely cause (Conversations appear within seconds while live updates arrive, and within about a minute when they don't.): **Show every Genesys conversation** is off, the queue is left out on the **Directory** tab, or the conversation is waiting for the AI and appears once the AI takes it.

**Fix:** check both settings. If **Health** shows **Live updates** or **Every conversation** with a warning, OpenCX is catching up by itself:

* **Live updates from Genesys are not arriving**: sessions still appear, about a minute later. If it stays for more than half an hour, check the connection status and reconnect if asked.
* **Some queues are checked every minute instead of live**: you have more queues than one live connection carries, or Genesys refused live updates for some of them. Their sessions appear about a minute later.
* **Some sessions are waiting for their latest messages from Genesys**: Genesys is busy, and those sessions catch up when it allows.
* **Many conversations were found by the minute check instead of live updates**: live updates are missing some conversations. Nothing is lost; contact support if it stays.
* **Genesys conversations are not being checked for what live updates missed** (an error): contact support.

### **A call has no transcript or recording**

Likely cause (Genesys produces both after the call ends: OpenCX keeps looking for the recording for 24 hours and the transcript for 6.): Genesys hasn't finished them yet, the queue isn't recorded or transcribed in Genesys, or the role lacks `recording:recording:view` (recordings) or `speechAndTextAnalytics:data:view` with a speech analytics licence (transcripts).

**Fix:** wait a few hours after the call. If **Health** shows **Call recordings** with a warning, add `recording:recording:view` to the role. For transcripts, add `speechAndTextAnalytics:data:view` and check the speech analytics licence. A call still open has no transcript until it ends, unless live assist transcribes it.

### **The Genesys agent doesn't see a teammate's reply or the handoff note**

Likely cause (The copy goes in only after a handoff, on sessions OpenCX handed off to Genesys.): Genesys refused the copy, or **Handoff summary note** is off. A refused copy leaves an internal note on the session, and the customer still got the reply.

**Fix:** check the setting on the **Handoff** tab. If the internal note keeps appearing, check **Health** and the request log on the **Setup** tab for the refusal.

### **A teammate's note doesn't reach the Genesys contact**

Likely cause (Genesys signs every external contact note with an agent.): the teammate isn't linked to a Genesys user, the session's contact isn't linked to an external contact, or **Share OpenCX context with Genesys** is off.

**Fix:** link the teammate on the **Directory** tab and check the setting. Notes written before the fix aren't sent again.

### **Moving a session to another team doesn't move the Genesys conversation**

Likely cause (Genesys refuses agent actions asked for by the connection on conversations it routes.): the session shows a conversation your agents work in Genesys. OpenCX keeps your change and adds an internal note.

**Fix:** transfer or reassign the conversation in Genesys. The session follows.

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