Skip to main content
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.

A handoff runs but nothing appears in 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.

The session shows a failed handoff

: 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

: 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

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

: 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

: 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

: Create a workitem for doesn’t cover the session. Fix: check Workitems and compare the role with Permissions.

Health shows a Business hours warning

OpenCX can’t use the schedule group you picked for 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 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

: the role OpenCX uses lacks routing:conversation:edit. Fix: add it to the role (see Permissions). The warning clears within a day, and participant data keeps arriving meanwhile.

Health shows a Custom attributes warning

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

Handoff settings

Routing, no-agents choices and business hours.

Sessions and sync

What follows each change in OpenCX and Genesys.