Skip to main content
Connect first, then go live when you’re ready. Connecting is silent: your customers, your AI and your queues carry on exactly as before until an admin clicks Go live.

Before you start

  • A Genesys Cloud admin who can create roles and OAuth clients, usually Master Admin.
  • A Genesys Cloud licence that includes digital messaging, or setup stops. To import articles, also Genesys Knowledge.
  • The Manage integrations permission in OpenCX (settings-integrations:write).

Connect

Finish setup

On the Setup tab:
1

Routing

Choose a queue. It becomes your Default queue. To use your own flow, choose Use my own flow instead, enter the Flow ID and click Save. See Use your own flow.
2

Conversation threading

Click Turn off threading so each handoff starts a new Genesys conversation. This changes a setting for your whole Genesys organization, and OpenCX names the other connections it affects. With Keep, a returning customer can join an older conversation.
3

Connection check

Under Tools, click Run check. It sends a message through the OpenCX flow and checks the reply. With your own flow, use Test session on the Diagnostics tab instead. Then hand off a real session, accept it in Genesys Cloud and reply. The reply should reach the customer’s channel.
If a step fails, use the button beside it: Retry, Reconnect or Open in Genesys. Running setup again is safe.

Roll out step by step

1

Connect

Your Autopilot settings, ticketing system, teammates and open sessions don’t change. In Genesys, setup adds only OpenCX’s own objects: a role, an OAuth client, a messaging connection and a message flow. It changes no existing queue, flow or route.
2

Set up and test

Finish setup and link your agents and queues. Use Test session on the Diagnostics tab to send a labelled session to a queue you choose and watch it end to end.
3

Decide where the AI answers

Check your Autopilot settings before you go live. Connecting and going live never change them, and the AI answers only on channels where autopilot is on. A channel with autopilot off hands each new session to your team.
4

Go live

On the Setup tab, click Go live. Handoffs from now on open Genesys conversations, and Genesys becomes your ticketing system, replacing any other. Sessions already with your team stay in OpenCX. To stop new handoffs later, turn off Genesys connection on.
5

Watch first

Turn on Show every Genesys conversation on the Channels tab to see your Genesys email and messaging as sessions while agents keep working in Genesys. The AI answers customers waiting in a queue when autopilot is on for their channel, so check autopilot for each channel first. Switch off queues you don’t want in the Queues list on the Directory tab, and check your workflows and team assignment first. See See every Genesys conversation.
6

Turn on the rest, one at a time

Each is off until you choose it: Agent sync, Presence sync, native messaging, native email and phone calls. The native channels and phone calls need you to go live first.
OpenCX moves a conversation between queues only when you link a team to a queue and change the session’s team, or turn on Agent sync and reassign it. On the Directory tab, link each Genesys item to its OpenCX counterpart. Click Link to a suggested match or pick one from the list. The directory refreshes about every half hour, or click Refresh beside Refresh directory on the Setup tab. An unlinked presence maps to available for Available and On Queue, and to away otherwise.

Sync queues as teams

Turn on Sync queues as teams on the Directory tab to bring in every Genesys queue as a team, whatever its channel. Turning it on refreshes the directory at once, and every refresh after that:
  • Creates a team for each new queue, named after it, with the linked agents who are members of the queue. A team you already have with the same name is linked instead of copied.
  • Renames a linked team when its queue is renamed. While it’s on, linked teams take their queue’s name.
  • Unlinks the team of a queue deleted in Genesys. The team, its members and its sessions stay.
When Genesys moves a conversation to a queue, the session moves to that queue’s team. New teams use manual assignment, because Genesys routes their conversations. A team you already had keeps its own settings when it’s linked, so turn on support for it if sessions should move into it. To leave a queue out, such as sales or partner support, switch it off in the Queues list. Do this before you turn the sync on, so no team is made for it. A queue you leave out keeps any team already linked to it. To remove a queue’s team, switch the queue off first, then delete the team. A deleted team comes back on the next refresh while its queue is on. Sync queues as teams is off by default, so connecting creates no teams. Connecting to a different Genesys org turns it off again and clears the queues you left out, because they belong to the old org.

Permissions

The role OpenCX uses needs these. Signing in creates it for you and grants it in the divisions you choose. If you create it yourself, grant it in the divisions OpenCX should work in.
The role reads and writes only in the divisions it’s granted in, so OpenCX can’t see agents, queues or flows outside them. Its message flow goes in a chosen division: Home if you chose it, otherwise the first by name. Genesys doesn’t divide messaging connections, the Assist panel or presence definitions, so those are org-wide, and contacts with no division stay visible.It can’t change queues. Without routing:queue:add it can’t create them either. Creating an email route or adding queue members always needs a Genesys login with routing write access.
These depend on your Genesys licence and never block connecting. Signing in adds the ones the admin holds. Without them, connecting works and only that feature stays off. Calls and callbacks in Show every Genesys conversation, and notes on external contacts in both directions, need nothing beyond the permissions above. Add these to the role yourself if you want them. Signing in doesn’t add them. To sign in, the admin also needs authorization:role:view, authorization:role:add, authorization:role:edit, authorization:division:view, authorization:grant:add and oauth:client:add. Changing divisions on a later sign-in also needs oauth:client:edit. If your org enforces OAuth scopes, the first sign-in also needs oauth:client:authorize, to approve OpenCX under Authorized Applications.

Regions

Settings reference

All of these are on the Handoff tab. Show every Genesys conversation (off by default; needs go-live), Native email and Native messaging are on the Channels tab. See See every Genesys conversation and Channels.

Health and secrets

Health on the Setup tab lists only what needs attention. Click Fix beside a check, or Repair when something was changed in Genesys. Undelivered messages lists what still failed after a day of retries. Retry sends them now, so a customer may get an old reply. If the connection stops working, the integration shows Reconnect needed. Click Reconnect, or with a client ID and secret, enter the new secret under Rotate client secret on the Connection tab. After Rotate webhook secret, the old secret keeps working for an hour.

Disconnecting

On the Connection tab, click Disconnect, type your Genesys organization name and confirm. OpenCX removes what it created in Genesys and lists anything it couldn’t under Remove these in Genesys. The OAuth client and role usually need a Genesys admin. Sessions are kept, but replies to conversations still open in Genesys no longer reach customers. Disconnecting also ends any open test session and removes the imported Genesys Knowledge articles. The live phone assist API key and client secret stop working, so create a new pair if you connect again. Moving to a different Genesys organization does the same. With a client ID and secret you can move directly. To move by signing in, disconnect first, because signing in to a different organization is refused while you’re connected. A move also turns off native messaging and native email and clears their connection secret, queues and address, and removes the links between your teams, agents, skills, statuses and presences and the old organization, so set them up again for the new one. Contacts and companies link again at their next handoff. Reconnecting to the same organization keeps all of this. Both also stop work still waiting on the old connection: calls still in progress are ended in OpenCX, recordings and transcripts not yet brought over stay in Genesys, and messages not yet processed are dropped. A session linked to the old conversation opens a new one with the customer’s next message.

Conversations & sync

Handoff, routing and what syncs each way.

Phone calls & live assist

Add transcripts and suggestions to Genesys calls.

Genesys Cloud overview

What the integration does.

Troubleshooting

Credential errors, empty queues, missing replies.