- Your Genesys Cloud region and client ID.
- An OpenCX session ID from the Inbox and its Genesys conversation ID.
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.
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.”
: 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”
: another workspace uses this organization. Fix: disconnect it there first, then connect here.Signing in with Genesys returns an error
: 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
: your org enforces OAuth scopes and this admin can’t approve new applications. Fix: sign in as an admin withoauth:client:authorize, or connect with a client ID and secret.
A setup step shows failed or action required
: 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
: 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
: 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
: 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
: no flow is bound, oropencx_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.The Knowledge import asks for permissions
: the role can’t read Genesys Knowledge. Fix: addknowledge:knowledgebase:view and knowledge:document:view to the role OpenCX uses, then click Import again.
The past conversations import asks for permissions
: 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: addanalytics:conversationDetail:view and recording:recording:view to the role OpenCX uses, then click Resume beside Past conversations.
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 addconversation: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
: the channel refused the reply, or the messaging connection changed. Fix: read the reason inopencx_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
: 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
: 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 holdsresponses: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
: 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. 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.Health shows Email routing with a warning
: the role OpenCX uses lacksrouting:conversation:edit.
Fix: add it to the role (see Permissions). The warning clears within a day, and participant data keeps arriving meanwhile.
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.The Assist panel says “This conversation is not available to Assist.”
: 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
: 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
: Genesys hasn’t finished them yet, the queue isn’t recorded or transcribed in Genesys, or the role lacksrecording: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
: 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
: 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
: 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 with the OpenCX session ID, the Genesys conversation ID and a timestamp.Related Documentation
Connect Genesys Cloud
Region, credentials and permissions.
Conversations & sync
Handoff, routing and what syncs each way.
Genesys Cloud overview
What the integration does.
Human handoff
When the AI hands a session to a person.