Genesys Cloud troubleshooting

Before debugging, have this ready:

• Your Genesys Cloud region and client ID.
• An OpenCX session ID from the Inbox and its Genesys conversation ID.

​

Diagnostics

Open Settings → Ticketing → Genesys Cloud → Diagnostics. 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: 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.

​

”This Genesys organization is already connected to another OpenCX workspace”

Likely cause: another workspace uses this organization. Fix: disconnect it there first, then connect here.

​

Signing in with Genesys returns an error

Likely cause: 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 from your Genesys address.

​

Genesys shows its own error page after Connect Genesys

Likely cause: 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.

​

A setup step shows failed or action required

Likely cause: the step is waiting for you, or Genesys returned an error. Fix: use the button beside the step. See Finish setup.

​

OpenCX can’t see your users or queues

Likely cause: 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.

​

Routing asks you to choose a queue again

Likely cause: 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: 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: 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.

​

The session shows a failed handoff

Likely cause: 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: 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: 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: 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: 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. 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: 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: Create a workitem for doesn’t cover the session. Fix: check Workitems and compare the role with Permissions.

​

The Assist panel says “This conversation is not available to Assist.”

Likely cause: 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 [email protected] with the OpenCX session ID, the Genesys conversation ID and a timestamp.

---

​

Related Documentation