How handoff works
OpenCX opens one Genesys message conversation per session, starting with the customer’s latest message. Your inbound message flow routes it to a queue. New customer messages and agent replies then pass through OpenCX, with files where the channel carries them. Your flow can read this participant data, always as text:
The full summary,
opencx_transcript, opencx_sentiment and opencx_handoff_reason (why the AI handed off) follow on the customer participant once the conversation opens. All of it is plain text.
Handoff note
With Handoff summary note on (the default, on the Handoff tab), the agent also finds a note in the conversation’s transcript: who handed off and why, the summary, the session’s language and sentiment, and a link to the session in OpenCX. It’s for the agent only: the customer never gets it. If Genesys refuses it, the handoff still goes through, and the session gets an internal note saying so (at most one a day). Native email and native messaging hand off inside Genesys, so they have no note, only the participant data.Teammate replies
When a teammate replies from the OpenCX inbox after the handoff, the customer gets it on their own channel at once, as usual. A copy also goes into the Genesys conversation’s transcript under the teammate’s name, such asMaya Haddad (OpenCX): …, so the Genesys agent sees what the customer was told, even while they hold the conversation. The customer gets the reply once, never again from Genesys. Long replies go in parts, split between paragraphs, and lists and links stay readable. If Genesys refuses the copy, the reply still reached the customer, and the session gets an internal note saying so (at most one a day). The Genesys agent’s own replies are never copied back.
Use your own flow
OpenCX imports and publishes an OpenCX Inbound Messages flow for you. To route with your own flow, choose Use my own flow beside Routing on the Setup tab, any time. A minimal flow:
Connection check expects the OpenCX flow. With your own flow, use Test session on the Diagnostics tab for the round trip.
When no agents are available
When no agents are on the queue decides what happens if nobody is on the target queue at handoff. If OpenCX can’t tell, or there’s no target queue, it hands off.What Genesys sends to OpenCX
These updates usually arrive within about a minute.Genesys summaries and analytics
Genesys takes a few minutes after a conversation ends to write its summary and analyse it. OpenCX checks for them for about an hour after the session closes, then stops, and keeps what it finds on the session for good, so it stays after Genesys deletes its copy. This covers every session linked to a Genesys conversation, calls and sessions from Show every Genesys conversation included, but not Past conversations imports or conversations that had already ended when they came in.
Use them like any other session attribute, in workflows and reports. Customers never see the note. With PII redaction on, the summary is redacted before it’s saved, and a session whose history was erased gets no summary.
Summaries need
conversation:summary:view. Sentiment and categories need speechAndTextAnalytics:data:view and recording:recording:view. Each also needs that feature on your Genesys plan. Surveys need nothing more. If Genesys refuses, Health on the Setup tab shows Genesys insights with what to add, and OpenCX asks again a day later.
What OpenCX sends to Genesys
Everything below goes to participant data unless noted. None of it reaches the customer as a message. If Genesys refuses a change, it still applies in OpenCX.
Genesys refuses transfers asked for by a connection that isn’t in the conversation. When it does, an internal note on the session says so, naming the queue or agent when OpenCX knows it, so move the conversation there in Genesys.
When the AI or the customer closes a session with an agent connected, the conversation stays open. On a conversation that started in Genesys, a close by a teammate or a workflow leaves it open too, and the session gets an internal note. Agent sync is on the Handoff tab, and it stays off until you turn it on.
Priority
With session priority on, a priority change updatesopencx_priority (none 0, low 10, medium 20, high 30, urgent 40). While the conversation waits in a queue, its routing priority changes too. Custom priority levels stay in OpenCX.
OpenCX context for agents, flows and reports
With Share OpenCX context with Genesys on (the default, on the Handoff tab), OpenCX writes what it knows about the session onto the customer participant of the Genesys conversation. Agents see it in the interaction’s participant data, Architect flows read it with Get Participant Data, and it travels with the conversation into Genesys conversation details. Every key starts withopencx_, each event is one update, and keys your flows or agents set are never changed. Turning it off stops everything in this section. The participant data in How handoff works, opencx_transcript included, is part of every handoff and is written either way.
A conversation that ends in Genesys first doesn’t get
opencx_outcome, because Genesys takes no participant data once a conversation has ended.
Email routing
For an email shown under every Genesys conversation that waits in a queue with no agent yet, OpenCX also asks Genesys to route it by what the session holds, set by your workflows, a teammate or the AI:- Priority: the session’s priority (none 0, low 10, medium 20, high 30, urgent 40), only when it’s higher than the email’s own.
- Language: the Genesys routing language matching the session’s language, when your Genesys has one. Otherwise the language is only in participant data.
- Skills: session skills linked to Genesys skills, added to the skills the email already asks for.
routing:conversation:edit, which the OpenCX role has. If Genesys refuses, Health shows Email routing with a warning, OpenCX stops asking for a day, and the participant data still lands.
Wrap-up code suggestions
With Suggest, the AI writes up to three codes from the conversation’s queue toopencx_wrapup_suggestions. Pre-fill when sure also pre-selects the top code when the AI is at least 80% sure and the queue makes wrap-up mandatory. A code the agent chose is never replaced, and the agent always has the final say.
Contacts and companies
At handoff, OpenCX links the contact to a Genesys external contact by phone number, then email, or creates one. A contact with neither isn’t linked. Its company links to an external organization the same way. When an agent wraps up, a name edited in Genesys comes back, and an edited email or phone fills only an empty field. When Genesys has matched a call, an email, or an SMS or WhatsApp conversation to an external contact, the session joins the OpenCX contact already linked to that external contact, so one person keeps one contact across channels. Otherwise the contact found by phone number or email is linked to it, and the external contact’s name, email and phone fill in, with its address and custom fields as contact attributes of the same names (address, and each field’s own name). A contact that already has the older genesys_contact_<field> name keeps it. Web messaging never joins a contact this way, because a page can claim anyone’s identity, and neither does a session signed in with a contact token.
Custom fields keep their type: numbers stay numbers, checkboxes become true or false, dates and text stay text, and a list of tags becomes one comma-separated value. A field of a type OpenCX can’t hold is left out. Without externalContacts:customFields:view on the role, text, numbers and true/false come over as they are and lists stay out. Custom fields update when the contact links and when an agent wraps up.
Editing one of those attributes in OpenCX updates that custom field on the external contact, so Genesys and OpenCX keep the same value. If Genesys refuses the edit, for example because the contact is in a division the role can’t edit, the edit stays in OpenCX and isn’t retried. Whichever side changed a field last wins: a later change in Genesys replaces the value in OpenCX, and an OpenCX edit stays until Genesys changes that field.
Notes travel both ways. Notes your Genesys agents keep on an external contact appear in OpenCX as internal notes on that contact’s newest Genesys session, under the agent’s name and dated, when the contact links and each time an agent wraps up. OpenCX contacts have no notes of their own, so the session is where they go. The 50 newest come over, each once, and they’re never shown to the customer or the AI. They’re redacted under your PII redaction settings, and a session whose history was erased gets none. In the other direction, an internal note a teammate writes on a session linked to Genesys is also added to the external contact’s notes, ending with a link back to the session, while Share OpenCX context with Genesys is on. Genesys signs every note with an agent, so the teammate must be linked to a Genesys user; otherwise the note stays in OpenCX only. Notes OpenCX writes, including CSAT scores, never come back as Genesys notes.
The external contact’s organization becomes the contact’s company in OpenCX, and the contact is added to it. A company already linked to that organization is used, such as one OpenCX created at handoff, and keeps its name. Otherwise a company is created with the organization’s name. The organization’s custom fields become company attributes of the same names, with the same types. A company that already has the older genesys_organization_<field> name keeps it.
Only the attributes your AI Context Rules allow reach the AI.
AI attributes
Under AI attributes on the Handoff tab, list what the AI should look for in a session, and where it goes: participant data, a custom field on the external contact, or a suggested wrap-up code (opencx_suggested_wrapup). The AI fills them at handoff and when OpenCX ends the conversation, and never replaces an agent’s entry. A custom field is written only on an external contact whose schema has that field. External contacts OpenCX creates have no schema, so nothing is written to them for those fields.
Participant data on contacts
Under Participant data on the Handoff tab, OpenCX lists the participant data keys it has seen on your sessions. Turn a key on to keep it on the contact too, under the same name, so the customer’s next session starts with it. The contact gets it the first time Genesys sends it for that customer, then updates when the value changes in Genesys, so an edit your team makes on the contact stays until Genesys sends a new value. Every key stays on the session either way.Conversation custom attributes
With Genesys Cloud CX 2 or higher, flows and agents can set custom attributes on a conversation. Each becomes the session attribute of the same name, with numbers and true/false kept and lists comma-separated. A teammate’s change to it in the inbox, or a change to agenesys_custom_<name> attribute from anywhere, goes back to the custom attribute of that name, as its type. OpenCX only updates attributes the conversation already has, because a new set of custom attributes needs a schema that you choose in Genesys.
If Genesys refuses them because of the licence or the role’s permissions, Health shows a Custom attributes warning for a day, and the rest of the sync carries on. OpenCX tries again after that day.
Workitems
To also give sessions a Genesys workitem, set Worktype and Create a workitem for on the Handoff tab.
A session gets at most one workitem, with its title, summary, queue, skills, language and priority. To fill custom attributes, set session attributes named
genesys_workitem_<attribute> before handoff. Values the worktype rejects are left out. The ID is stored on the session as genesys_workitem_id.
Workflow actions
Assist panel
In assist mode, agents see the AI’s draft in an OpenCX Assist panel beside the interaction, with Insert, Copy and Dismiss. Drafts reach the customer only when an agent sends them, and only agents on the conversation can see them. Agents sign in with Genesys when they open it in a new browser session. To install the panel, click Install beside Assist panel on the Setup tab. Nobody sees it until you choose who gets it: in Genesys Cloud, open Admin → Integrations → OpenCX Assist → Configuration and pick the agents’ groups under Group Filtering. To show it only on some queues, pick them under Queue Filtering.Channels
Choose where customers chat on the Channels tab. These can run together, and each session stays on the one it started on.
Agent replies on sessions that start in OpenCX:
A message your flow sends on these sessions, such as a queue update or a survey question, reaches the customer the same way. It appears as a workflow message under the flow’s name, not as an agent’s reply: it doesn’t reopen a closed session, doesn’t count as a first reply in SLAs or reports, doesn’t run your agent reply or agent inactivity workflows, and doesn’t send the
conversation.agent_response webhook. On API sessions, read it from the session history.
See every Genesys conversation
Turn on Show every Genesys conversation on the Channels tab, after you go live. Every email, messaging conversation (WhatsApp, web messaging, SMS, Instagram, Messenger and other messengers), call and callback in your Genesys queues then appears as a session, usually within seconds. These sessions work like sessions on your other channels, and your agents keep working in Genesys:- Customer, agent, flow and bot messages and files appear on the session as they’re written, in the order they were written in Genesys. Messages the AI sent never appear twice. After you redact a session, messages written before the erasure don’t come back to it; new ones still appear.
- The queue sets the team, the agent who accepts it becomes the assignee (when the agent is linked), the wrap-up code sets the sub-status, and the session closes when the conversation ends in Genesys, with its last messages (or a note saying to open the conversation in Genesys if Genesys didn’t share them).
- The AI answers while the customer waits in a queue, when autopilot is on for the channel: on email, web messaging and Open Messaging, in the customer’s own conversation. Email needs the sender address set under Native email, or replies sent from your support address. WhatsApp, SMS and other messengers can’t take a reply in an ongoing conversation, so those sessions start with your agents. With autopilot off, a session starts with your agents, as on any channel. With assist mode on, the AI writes drafts for the agent.
- An agent who accepts the conversation in Genesys owns it. The AI stops, and a reply it was still writing isn’t sent.
- When the AI hands off, the conversation stays in its queue for your agents: nothing is transferred and no workitem is created.
- When the AI resolves the session, OpenCX ends the conversation in Genesys, so no agent picks it up. If the customer writes again, a new conversation and a new session start.
- The AI’s resolutions are billed, and its handoffs and resolutions count in your reports, as on any channel.
- Assign to AI works while no agent holds the conversation in Genesys. It’s refused once one does.
- Your teammates can work these sessions from OpenCX. While no agent holds the conversation in Genesys, a reply from the inbox goes into the customer’s own conversation the way the AI’s does, on email, web messaging and Open Messaging. Files go as links. It counts as the teammate’s reply, as on any channel: the session becomes theirs, the AI stops answering, and it counts in reply times and reports. It’s never added to the session a second time.
- Once an agent accepts the conversation in Genesys, the composer says to reply in Genesys, and a reply from the inbox is refused. A reply sent just as the agent accepted it isn’t sent, and the session gets an internal note.
- WhatsApp takes only approved templates in an ongoing conversation, so the composer offers Send template instead of Send. Pick one of your WhatsApp templates in Genesys, fill in its values and check the preview, as with your own WhatsApp templates. Genesys sends it into the customer’s conversation, the session shows it like any template, and the session becomes yours. It’s refused while an agent holds the conversation in Genesys. Header and button values can’t be filled in from OpenCX, so send templates that need them from Genesys.
- SMS and other messengers can’t take a reply in an ongoing conversation, so the composer says to reply in Genesys.
- Workflow messages go out like the AI’s while no agent holds the conversation, and are held back with a note once one does.
- Closing the session in OpenCX ends the conversation in Genesys when no agent holds it. With an agent on it, the conversation stays open for them, and the session gets an internal note saying so. If Genesys is unavailable at that moment, OpenCX ends the conversation once Genesys is back.
- Assigning one of these sessions to a teammate means they work it from OpenCX, so nothing changes in Genesys. Changing the team doesn’t move the conversation in Genesys: Genesys refuses agent actions asked for by the connection, and the session gets an internal note instead.
- Conversations waiting for the AI (native email or messaging) keep working as before.
Calls and callbacks
Calls and callbacks in the same queues appear as phone sessions, whether or not live assist is on and whether or not Genesys transcribes the queue:- A call appears when an agent answers it, with the caller’s number on the contact, the queue’s team, the agent as assignee (when linked) and its timeline. A call or callback the minute check finds first appears at once, even while it waits.
- When the call ends, the session closes, and Genesys’s recording, its transcript (with a speech analytics licence) and the agent’s wrap-up code and notes come in over the next minutes to hours, as for calls with live assist. A call that ended before OpenCX saw it, including one the caller abandoned in the queue, comes in closed at its own times, and its recording, transcript and wrap-up follow the same way. Like past conversations, it isn’t counted in AI handoff and resolution reports.
- Closing a call’s session in OpenCX never hangs up the call. It stays live in Genesys until the caller or the agent ends it.
- These are your agents’ sessions. The AI never answers or joins them, they’re never billed as AI resolutions, and they count in your reports like any call your team takes.
- With live assist on a transcribed queue, the transcript also appears live and agents get suggestions, as before.
Import past conversations
To bring past messaging and email into the inbox, open the Knowledge section of the Connection tab and press Import beside Past conversations. It covers the last 90 days and creates closed sessions on their real channels. Messages a flow, bot or auto-reply sent come in as workflow messages, never as an agent’s reply. Nothing is sent to customers, no AI or workflow runs, and nothing is billed. Sessions keep the times their messages were written, so they don’t jump to the top of the inbox or change your reply-time reports, and they never count as AI handoffs. Participant data on emails, calls and messaging still open comes in as session attributes of the same names, and an email, SMS or WhatsApp conversation joins the contact linked to its external contact. Importing again skips what’s already there. A large history imports in parts and carries on by itself about once a minute, waiting whenever Genesys is busy so live conversations come first. A conversation that fails for a passing reason is tried again at the end. Resume only matters after an import stopped on an error, such as a missing permission. Each imported session also shows its timeline of queues, agents and wrap-up. Ended messaging conversations come from the transcripts Genesys keeps with its recordings, so the import needsrecording:recording:view on the role OpenCX uses. Without it, emails still import, messaging is skipped, and the import ends asking for the permission: add it, then press Resume to bring the messaging in. Conversations with nothing to bring over, such as an email with no sender address or a conversation Genesys kept no transcript of, are skipped, not failed.
To import one conversation in a workflow, set Genesys Conversation ID on the Create Ticket action. A live messaging conversation stays open and keeps syncing. An email or a call still open is refused until it ends. An ended call comes in as a closed phone session, and its recording, transcript and wrap-up follow.
Sessions your team starts
On a Genesys workspace, the New Session dialog and sub-sessions work on email. OpenCX sends the message and no Genesys conversation exists until the session is handed off.Merged sessions
Genesys has no conversation merge. After a merge, each source conversation getsopencx_merged_into and is ended, unless the primary shares it. The primary’s conversation gets opencx_merged_from. Turn off threading so a returning customer can’t rejoin an ended source conversation.
Related Documentation
Connect Genesys Cloud
Setup, settings and directory links.
Phone calls & live assist
Transcripts and suggestions on Genesys calls.
Human handoff
Assist mode and when the AI hands off.
Troubleshooting
Empty queues, missing replies, conversations that don’t move.