Overview
Voiceflow integrates with Genesys Cloud to connect an AI Chat conversation to a contact-center agent through Open Messaging. Customers keep the same Chat interface while staff receive their details and conversation context, reply and finish the hand-off in Genesys.
Configure the Genesys message flow and callbacks, then add a Handoff step to your Voiceflow agent. This connection handles Chat; use your verified telephony routing for phone calls rather than these Open Messaging settings.
Examples of when to use Genesys
- Human agent hand-off — send a customer who needs a person to the right staffed queue.
- Share customer context — give the receiving agent the AI exchange or a prepared escalation summary.
- Exchange messages and images — keep customer and agent replies in the same conversation.
- Show waiting information — display a queue estimate and warn an inactive customer.
- Return to AI — continue the configured Voiceflow path after human support ends.
What you need
- A Genesys Cloud administrator with Open Messaging available, an Open Messaging Integration ID, a staffed queue and its Queue ID.
- A Client Credentials OAuth client with permission to receive Open Messages, read queue wait estimates and disconnect a conversation participant. Its roles must cover the receiving queue’s division.
- An editable Voiceflow Chat project with Genesys available in Integrations, a test Environment, and the Voiceflow Chat widget or a custom client implementing Chat hand-off events.
- Trusted customer email, name and account ID. These fields are required by this connector; do not substitute another customer’s identity or use one fixed identity for every visitor.
Studio
Use Agent studio for the connection and Handoff step. A Genesys administrator prepares the Open Messaging integration, message routing and lifecycle callbacks described below.
Code
Set PROJECT_ID, ENVIRONMENT_ALIAS and VF_TOKEN in your shell. Use a server-side Voiceflow API credential with project access. Examples use cURL, jq and a current Voiceflow CLI. Keep OAuth credentials, callback secrets and VF_TOKEN out of customer browsers and source control. Genesys-side administration is required for both methods.
Connecting Genesys
Connect your regional Genesys account and enable messages and lifecycle callbacks.
Prepare Open Messaging
Create the OAuth client
In Genesys Cloud, open Menu → IT and Integrations → OAuth → Add client and choose Client Credentials. Assign roles with these runtime permissions:
conversation:message:receiveto send customer messages into Open Messaging.routing:queue:viewto retrieve the queue’s estimated wait time.conversation:communication:disconnectto disconnect the customer when the hand-off closes.
Associate the roles with the divisions containing the target queue. Save Client ID and the Client Secret; the latter becomes Voiceflow’s OAuth secret key. Follow Genesys OAuth setup for the administrator’s access and client settings. Client Credentials uses assigned roles, rather than a user-consent scope list.
Create the Open Messaging integration
In Genesys, open Menu → Digital and Telephony → Message → Platform Integrations, create an Open Messaging integration and set Outbound Notification Webhook URL to:
Choose a strong Outbound Notification Webhook Signature Secret Token. Store the same value in Voiceflow’s Webhook secret. This is separate from the OAuth Client Secret. Save the integration and retain its Integration ID.
Use the Open Messaging setup to select a supported content profile if you will exchange images. Saving credentials in Voiceflow does not create this integration or register its webhook.
Route incoming messages to the queue
Create and publish an Architect Inbound Message Flow with a Transfer to ACD action targeting the staffed queue. In Menu → Orchestration → Routing → Message Routing, attach the Open Messaging integration’s address to that flow and save.
For a single queue, select the queue in the flow. If your flow routes dynamically, read the queue_name participant attribute and map it to an approved queue. Voiceflow’s Queue name supplies that attribute; Queue ID retrieves wait estimates and does not perform the ACD transfer.
Follow Transfer to ACD and inbound message routing for the provider controls. Record the selected queue’s name and ID together.
Deliver agent and closure events
Open Messaging sends message notifications to the webhook. Agent arrival and conversation completion use separate lifecycle requests. Configure these before testing the full journey; storing the connection alone does not enable them.
Have your Genesys administrator create published Architect Workflows and a Web Services Data Action that POSTs to the same callback URL. Use a User Defined credential named webhookSecret, containing the same callback secret stored above. Set Content-Type to application/json and X-Hub-Signature-256 to ${credentials.webhookSecret}. Keep that secret in the integration credentials, not in a public request template.
The action’s input contract requires one string named conversationId. Map the triggering event’s conversationId into that action input. Use this request template:
This template uses the display name Agent. To send a real agentName, first resolve the event’s userId to that name in your Workflow; the user-start event does not supply it. Create a second action for final completion, with required conversationId input:
Use Genesys event triggers to invoke the published Workflows. With JSON input, create the Workflow input jsonData, select Json as the trigger data format and map its conversationId property to the Data Action input. Save and test each trigger, then activate it. Restrict triggers to this Open Messaging route and queue. Pass the actual Genesys conversation ID into the action; the callback field is conversationID, whereas Open Messaging notifications use conversationId.
- On
v2.detail.events.conversation.{id}.user.start, check that a human agent has connected before sendingStart; exclude unrelated media and queue activity. - Reconcile
user.endandcustomer.endwith the conversation’s current participants before sendingEnd. An agent leaving during a transfer does not mean customer support has finished. SendEndonly when the intended support conversation is over. - If you enforce an inactivity-disconnect policy, invoke a separate action with
type: "Inactivity Timeout"andconversationIDwhen that policy actually dismisses the customer. Voiceflow’s warning timer does not create this provider policy.
See Data Action contracts, request configuration and User Defined credentials for the action editor. Test with an active Voiceflow hand-off: HTTP 200 alone can also mean the conversation ID was unknown or the payload was ignored.
Save the connection
Studio
Find Genesys in your project
Open the Chat project in Agent studio. In the left sidebar, open More → Integrations, find Genesys and select Connect.
Enter the regional account and credentials
Enter Domain, Client ID, Webhook secret and OAuth secret key. Domain is the regional base suffix, such as mypurecloud.com, without https://, api. or login.: Voiceflow constructs the login and API hosts from it. Use the region of your actual Genesys organization.
Select Connect. This stores credentials; it does not validate OAuth, routing or callback delivery.
Check the connection scope
Connect Published first. Where offered, configure a separate Draft override for testing. Draft falls back to Published credentials without an override; changing the Environment alone does not isolate the Genesys account.
Code
Save genesys-connection.json outside your repository. Replace each placeholder; use your organization’s regional domain suffix without a scheme or host prefix.
oauthSecretKey authenticates the OAuth client; secretKey validates callbacks. This stable operation writes the project’s shared Published connection. It has no Environment or Draft-slot selector; use a separate test project to isolate this write.
The response reports Integration genesys connected. This confirms storage, not successful Genesys authentication or routing. Continue with the Handoff step.
Rotate or disconnect Genesys credentials
Keep callback secrets and active conversation credentials in step.
Studio
Return to More → Integrations → Genesys to replace or remove the intended connection. Removing Published also removes its Draft override.
Code
Repeat the connect operation to replace Published credentials. To remove both Published and Draft, use DELETE /v1/stable/integration/genesys?projectID=… on the realtime API host, or vf integration disconnect --integration genesys --project-id "$PROJECT_ID".
Active hand-offs retain their starting credentials and access token. Drain them before rotating OAuth or callback secrets. A new project connection does not update an active hand-off or refresh its stored token. Set the OAuth token lifetime to cover your intended support sessions and test the expiry boundary before launch.
Human agent hand-off
Move the customer into the Genesys message flow and its staffed queue.
Map the integration, customer and queue
- Integration ID: the Genesys Open Messaging integration, not an OAuth Client ID.
- User email: the customer’s email, used as their Open Messaging channel identity.
- Customer name: the displayed customer name and
customerNameparticipant attribute. - Customer account ID: the
customerAccountIdparticipant attribute. It does not look up or verify a CRM account. - Queue name: the
queue_nameparticipant attribute, for a message flow that reads and maps it. - Queue ID: the queue whose estimated wait time Voiceflow requests. Keep it aligned with the queue selected by Architect.
All six fields must be nonempty. Use trusted identity from your application. The Open Messaging identity is the email; a Voiceflow user ID or a customer account ID is not the Genesys conversation ID.
Configure and route the Workflow
Studio
Open a Handoff step
In the test Environment, open Build → Workflows. Create Genesys support, add a Handoff step inside a block and choose Genesys as Handoff provider.
Map the queue and identity
Enter the Open Messaging Integration ID and both queue fields. For the pilot, use a dedicated test customer. For production, create the customer variables and supply them before Handoff as described in Map production customer data below.
Set context and continuation
Choose Full transcript for Handoff context. Enable Return path and Failure path. Link their exits to fixed follow-up blocks, or leave them unlinked to return control to the calling agent. Add the real fallback contact option to Instructions.
Attach the Workflow
Return to Agent, add Genesys support to Workflows and reference it in Instructions for customers asking for a person. Run a Draft test before publishing. Creating the Workflow alone does not attach it to the agent.
Code
Save genesys-workflow.json. Replace the queue placeholder and use one dedicated test customer. Do not deploy this fixed identity for multiple customers.
This pilot leaves Return and Failure exits unlinked, handing control back to the calling agent. Define the fallback in Instructions or link the exits to Workflow blocks.
Save prepare-genesys-patch.sh. Run it after Workflow creation and agent read succeed. Inspect genesys-created.json for workflow.id, unresolvedReferences and diagnostics first; stop on unresolved values. Keep the returned ID rather than repeating creation after a later failure.
The patch preserves the current Workflow registry and Instructions. Replace the fallback with your real contact option and review agent-patch.json before applying it. Both methods below cover create → read → patch → compile.
After inspecting the create result, prepare and review the attachment:
Apply the reviewed patch and compile Draft:
After inspecting the create result, prepare and review the attachment:
Apply the reviewed patch and compile Draft:
Read the agent back to confirm attachment and routing. Compilation prepares Draft without publishing it. Test Draft, then publish the reviewed Environment before the customer-facing test.
For production, replace the fixed identity using the variable setup below. Writes do not create missing variables; inspect unresolved references and compile again.
Map production customer data
Studio
In your project, open More → Variables and create variables named customer_id, customer_email and customer_name. Leave customer-specific defaults empty. In the Handoff step, insert those variables into Customer account ID, User email and Customer name. Before entering Handoff, populate them from your authenticated application; for an editor pilot, use a dedicated test identity rather than a shared production default.
Code
- Create
customer_id,customer_emailandcustomer_namewithPOST /v2/stable/variable?projectID=…&environmentAlias=…on the realtime API host. Each body suppliesname,colorand an emptydefaultValue. Alternatively use vf variable create, for examplevf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT_ALIAS" --name customer_id --color-param '#515A63' --default-value '""'. - Read
GET /v2/stable/variable?projectID=…&environmentAlias=…, or vf variable list, to obtain eachvariables[].id. Binding text uses the name, such as{customer_id}; Custom context uses the resource ID. - Read
GET /v1/stable/workflow/$WORKFLOW_ID?projectID=…&environmentAlias=…, or vf workflow get. Find the Handoff step’sidin the response’s top-levelblocks[].steps[]. Use it with Workflow update-step to replace the fixed identity fields. Compile again after the patch. - From your authenticated backend, send the actual values by name in the
variablesmap alongside the launch or text action before the Workflow enters Handoff. Session creation alone does not populate those values. Do not accept another customer’s identifiers directly from an untrusted browser.
Verify routing and replies
Have an agent available in the test queue. Ask the AI for a person. Confirm that the expected Genesys conversation enters the published message flow, reaches the intended queue and is accepted by that agent. Reply from Genesys and confirm the customer sees it in their original Chat.
A chat_started trace means Voiceflow created the hand-off; it does not prove that Architect selected the right queue or that a human accepted it. Test the separate Start callback and check the customer’s joined-agent state.
Sharing customer context
Give the Genesys teammate the AI exchange or a prepared escalation summary.
Choose the context
- Full transcript: sends the runtime’s available conversation memory as Customer/Bot lines in the initial inbound Text message. It does not fetch the complete stored Transcript archive or create a summary.
- Custom: sends a string variable prepared before Handoff, such as the order reference, issue and troubleshooting already attempted.
- None: sends
Customer connected via Voiceflow.as the initial message instead of AI context.
This is an inbound conversation message, not an internal note. Choose context appropriate to that visibility. Customer name, account ID and queue name are separate channel attributes; adding arbitrary Configuration keys does not create additional Genesys fields.
Prepare a summary
Studio
In More → Variables, create handoff_summary with an empty default. Set it to the escalation summary before Handoff, using a Set step or your trusted application. Open the Workflow’s Handoff step, choose Custom under Handoff context and select that variable. Naming a variable does not produce a summary.
Code
The pilot uses Full transcript. Create handoff_summary using the variable procedure above and retain its variable.id (or find it in variables[].id). Read the Workflow to obtain the Handoff step ID. Update that step with Workflow update-step:
Compile the updated Workflow. Before entering Handoff, send variables: {"handoff_summary":"Order 1042: damaged item; customer requested a specialist."} alongside an authenticated launch or text action. Use your actual, relevant summary. The runtime map uses the name handoff_summary; authoring uses its resource ID. Test the same Environment and execution variant.
Verify the received context
In Genesys, inspect the first inbound message and the customer attributes. Check that the transcript or summary contains the intended issue without credentials or unrelated records. Use two different test customers to confirm the identities and contexts remain separate.
Exchanging messages and images
Keep customer text and supported attachments in the same Chat session.
Keep the conversation connected
Studio
Use the Voiceflow Chat widget for the test. Send a customer message and reply from Genesys. Check that each arrives without starting another Chat. The widget handles teammate messages, assignment and the ended state; test the deployed widget as well as Draft.
Code
Use Socket.IO for asynchronous replies. A completed HTTP Streaming response cannot receive a teammate’s later message. Install socket.io-client on your trusted Node.js server. Use the customer’s existing session key, user ID and execution variant. Start this socket before asking the AI to enter Handoff and keep it running through the exchange; register listeners before connecting:
This pilot resumes Draft; use versionVariant: 'published' for an existing Published session. Use activeVersionID returned by client.started for uploads. This minimal pilot disables automatic reconnect. If the socket disconnects, disable customer controls. Before reconnecting to an already-active hand-off, restore its recorded chat_started configuration and process missed events using Recover an interrupted connection below; a closure may have arrived while disconnected. The server does not automatically resend initial configuration. A new session is not a replacement for an active hand-off. Replace logging with your message UI and handle chat_ended as described below. See Chat hand-off events for the shared connection and customer-action contract.
Send an attachment
Send one image at a time. Voiceflow storage accepts up to 26,214,400 bytes (25 MiB), but the Genesys supported content profile can impose a lower limit or narrower types. The customer-upload adapter declares attachments as Image; do not use this path to promise arbitrary document uploads.
Studio
In the active widget, use the attachment control to send one supported image. Have the teammate open it in Genesys, then send a file back and confirm that the customer can open it. To disable uploads, set disableFileUpload: true in the Handoff step’s Configuration.
Code
Request an upload
Call POST https://general-runtime.voiceflow.com/v1/handoff/file-storage with projectID, the current userID, versionID: activeVersionID from client.started, fileName, fileType and fileSize. Use the resolved execution version; an alias can resolve Published during a Draft test.
Upload the file
POST a multipart form to the returned url, including every returned fields value and the file. Wait for success. The upload URL expires after five minutes.
Send the uploaded reference
Send action.send on the ready socket with action type live-agent-handoff and payload:
Use fields.key from the upload response and the actual metadata. The adapter sends only the first file per action. Follow the handoff action schema for the full envelope.
Receive teammate events
Open Messaging Text notifications produce message_received, or file_received for the first attachment. A message with several attachments does not become several customer events. Receipt notifications are ignored. The lifecycle requests configured above produce participant_joined, chat_ended or chat_dismissed; this connector does not emit agent-typing notifications.
Test text and an allowed image in each direction. Confirm that inbound customer messages do not echo back as agent replies. HTTP 200 from the callback is not delivery proof: verify the content in the customer’s active session.
Recover an interrupted connection
Restore hand-off state before enabling customer controls after a disconnect.
Studio
Test a temporary disconnection in the deployed widget during human support. Confirm the same customer session resumes, later replies arrive and a conversation closed during the interruption stays ended. Do not start a replacement conversation to test recovery of the original one.
Code
The minimal socket example disables automatic reconnect. Add recovery before enabling it:
- Persist the initial
chat_started.config, current hand-off state and the latest receivedtrace.timetimestamp. Keep the same project, user, execution variant and session key. - Register a
session.historylistener before reconnecting. Restore the initial configuration, then include the saved timestamp aslastReceivedAtinclient.start. - Read
session.history.replayin order. For each entry, inspectentry.data: apply only traces withtype: 'live-agent-handoff'and apayload.event. Actions can share the outer type but havepayload.type; they are not teammate events. Apply missedchat_endedbefore allowing further support messages. - Advance the cursor from trace
time, using the entry’s parsedcreatedAttimestamp when needed. Replay contains events after the supplied cursor, not a fresh configuration snapshot. - The server emits replay before
client.started. Re-enable controls only after history has been applied andclient.startedconfirmsnewSessionRequired: false. If it requires a new session, stop and explicitly end recovery of the old one.
Persist this state outside the socket instance if your application can restart during a hand-off. Reconnecting without the cursor and replay handling can miss a closure or leave the wrong return controls visible.
Waiting and inactivity
Show the receiving queue’s estimate and distinguish warnings from disconnection.
Show the estimated delay
Genesys wait estimates use the configured Queue ID. Voiceflow requests an estimate immediately, then every 30 seconds while polling is active. It rounds seconds up to minutes; values up to one minute read “less than a minute.” The adapter uses the first estimate returned for that queue, so test it against your actual message routing.
Studio
In the Handoff step, open Configuration and enter:
Use "None" instead of "Delay" to disable it. Check the widget’s waiting state before an agent accepts.
Code
In Workflow update-step, retain the complete content.config object and set its metadata field to the JSON-encoded string "{\"waitTimeMessage\":\"Delay\"}". Use "{\"waitTimeMessage\":\"None\"}" to disable polling, then compile. metadata belongs inside config, not directly in content; replacing config with only this key would discard the required provider fields. Listen for wait_time events on the active socket; do not derive a queue position from the estimate.
An omitted mode retains estimates. Time and Position do not select additional Genesys behaviors. If estimates are missing, check Queue ID and the OAuth client’s queue access; message delivery and wait polling are separate checks.
Configure the inactivity warning
Studio
In the Handoff step, set Inactivity timeout warning (minutes) to a positive number, such as 5. Leave it empty to omit this Voiceflow warning timer.
Code
Set config.inactivityTimeout to text such as "5" only after configuring the matching provider policy. Supply a positive finite number of minutes as text; an empty value omits the timer. Compile again after changing it. Handle chat_dismissal_warning as a warning, not as a closed conversation.
The timer starts when a human joins through Start, and customer activity resets it. Its message says the session will expire in two minutes, but the timer itself does not disconnect the customer. Align it with your Genesys timeout policy and its Inactivity Timeout callback. Do not enable a countdown that your actual policy does not enforce.
Ending human support
Handle closure and return to the configured AI path explicitly.
Choose the continuation
Studio
Enable Return path to let the customer continue with AI. Link its exit to a follow-up block or leave it unlinked to resume the calling agent. Enable Failure path with a useful fallback. After End, the widget returns to AI when Return path is enabled. After an inactivity dismissal, select Return to AI when available. Continue conversation cannot reopen a Genesys conversation; test this dismissal experience before enabling the timeout policy.
Code
Retain config.returnToAI from the initial chat_started event; chat_ended does not repeat that configuration. After chat_ended or chat_dismissed, when return was enabled, send the control below on the ready socket to close the hand-off and continue the configured Workflow path or calling agent:
When return is disabled, show the ended state instead of continuing the relay. Stop sends after session.ended. A provider closure does not itself perform the custom client’s return action; see customer controls and terminal states.
The configured End callback ends the relay; Inactivity Timeout dismisses it. This connector does not reopen a dismissed or closed Genesys conversation through continue_conversation. Offer the supported return-to-AI or ended state instead. A socket reconnect to an existing active session is separate from reopening a closed provider conversation.
Test the finish and fallback
End support in Genesys and verify the End callback reaches the customer. Exercise the configured return to AI and confirm the intended follow-up. Test the inactivity policy separately, including customer activity resetting the warning.
If the customer explicitly ends support or returns to AI, Voiceflow attempts to disconnect the Genesys customer participant. Check the provider conversation too: Voiceflow removes its relay mapping even if that disconnect fails. Do not infer a successful Genesys close from a cleared customer interface alone.
In an isolated test project, use an invalid Integration ID to exercise the connection Failure path. Also test a valid integration with incorrect message routing: an accepted inbound message does not prove a staffed queue received it. Provide your real fallback contact option in Instructions.
Before routing customer traffic, complete the Contact Center test and launch checklist with real credentials, message routing and callbacks. Keep the previous route available for rollback.