> ## 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 handoff and routing troubleshooting

> Fix Genesys Cloud handoffs that never reach a queue, conversations that do not move or close, missing workitems, and hours, callback or routing warnings.

Use this page when a handoff doesn't reach a Genesys Cloud queue, a conversation doesn't follow a change in OpenCX, or **Health** shows a routing-related warning. Each entry gives the likely cause and the fix. For other problems, start at [Troubleshooting](https://docs.open.cx/integrations/genesys/troubleshooting.md).

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

### **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 because the role lacks the **Transfer** permission (`conversation:communication:transfer`). The session then has an internal note saying so, and **Health** shows **Transfers** for a day.

**Fix:** [link them](https://docs.open.cx/integrations/genesys/directory.md). A session also assigned to a linked agent goes to that agent, not the queue. If the internal note is there, reconnect with an admin who holds the **Transfer** permission, or add it to the role, and move this conversation in Genesys. After a reconnect, the next change goes to Genesys at once, and so do callbacks, Data Actions and the other requests Genesys had refused for the day.

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

Likely cause (Moving a conversation the connection isn't in needs the Transfer permission on the OpenCX role.): the role lacks the **Transfer** permission (`conversation:communication:transfer`). OpenCX keeps your change and adds an internal note.

**Fix:** reconnect with an admin who holds it, or add it to the role. Until then, transfer or reassign the conversation in Genesys. The session follows.

### **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/workitems.md) and compare the role with [Permissions](https://docs.open.cx/integrations/genesys/permissions.md).

### **Health shows a Business hours warning**

OpenCX can't use the schedule group you picked for [business hours](https://docs.open.cx/integrations/genesys/handoff.md#business-hours), so it uses your OpenCX office hours for now.

**Fix:** the warning says why.

* **Permission missing:** reconnect Genesys with an admin who holds `routing:scheduleGroup:view`, `routing:schedule:view` and `routing:emergencyGroup:view`, or add them to the role OpenCX uses.
* **Schedule group missing:** it was deleted in Genesys. Pick another one.
* **Schedule can't be read:** one of its schedules repeats in a way OpenCX doesn't read, such as every hour or by week number. Use daily, weekly, monthly or yearly repeats.
* **Genesys didn't answer:** nothing to do. OpenCX tries again a minute later.

The other warnings clear within an hour, when OpenCX tries again, or as soon as you pick a schedule group again.

### **Health shows a Callbacks warning**

Genesys refused a [callback](https://docs.open.cx/integrations/genesys/workflow-actions.md#callbacks) because the role OpenCX uses lacks `conversation:callback:create`. A session kept with the AI to offer it went to the queue instead.

**Fix:** reconnect Genesys with an admin who holds `conversation:callback:create`, or add it to the role OpenCX uses. The warning clears within a day.

### **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/permissions.md)). The warning clears within a day, and participant data keeps arriving meanwhile.

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

## Related

> [card] [Handoff settings](https://docs.open.cx/integrations/genesys/handoff.md)
>
> Routing, no-agents choices and business hours.

> [card] [Sessions and sync](https://docs.open.cx/integrations/genesys/conversations.md)
>
> What follows each change in OpenCX and Genesys.


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