Build with

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

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

1

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:receive to send customer messages into Open Messaging.
  • routing:queue:view to retrieve the queue’s estimated wait time.
  • conversation:communication:disconnect to 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.

2

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:

Voiceflow Genesys callback

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.

3

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:

Agent connected 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:

Conversation finished request template

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 sending Start; exclude unrelated media and queue activity.
  • Reconcile user.end and customer.end with the conversation’s current participants before sending End. An agent leaving during a transfer does not mean customer support has finished. Send End only when the intended support conversation is over.
  • If you enforce an inactivity-disconnect policy, invoke a separate action with type: "Inactivity Timeout" and conversationID when 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

1

Find Genesys in your project

Open the Chat project in Agent studio. In the left sidebar, open More → Integrations, find Genesys and select Connect.

Open More → Integrations in the same project as the Chat agent. Photo:
2

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.

Store the regional domain, OAuth client and matching callback secret. Photo:

Select Connect. This stores credentials; it does not validate OAuth, routing or callback delivery.

3

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.

genesys-connection.json

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 customerName participant attribute.
  • Customer account ID: the customerAccountId participant attribute. It does not look up or verify a CRM account.
  • Queue name: the queue_name participant 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

1

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.

2

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.

Match the Open Messaging integration and queue, then choose context and continuation. Photo:
3

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.

4

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.

genesys-workflow.json

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.

prepare-genesys-patch.sh

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:

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_email and customer_name with POST /v2/stable/variable?projectID=…&environmentAlias=… on the realtime API host. Each body supplies name, color and an empty defaultValue. Alternatively use vf variable create, for example vf 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 each variables[].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’s id in the response’s top-level blocks[].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 variables map 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:

Custom context patch

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:

Receive replies on the existing Chat session

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

1

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.

2

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.

3

Send the uploaded reference

Send action.send on the ready socket with action type live-agent-handoff and payload:

Uploaded file 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:

  1. Persist the initial chat_started.config, current hand-off state and the latest received trace.time timestamp. Keep the same project, user, execution variant and session key.
  2. Register a session.history listener before reconnecting. Restore the initial configuration, then include the saved timestamp as lastReceivedAt in client.start.
  3. Read session.history.replay in order. For each entry, inspect entry.data: apply only traces with type: 'live-agent-handoff' and a payload.event. Actions can share the outer type but have payload.type; they are not teammate events. Apply missed chat_ended before allowing further support messages.
  4. Advance the cursor from trace time, using the entry’s parsed createdAt timestamp when needed. Replay contains events after the supplied cursor, not a fresh configuration snapshot.
  5. The server emits replay before client.started. Re-enable controls only after history has been applied and client.started confirms newSessionRequired: 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:

Queue wait estimate configuration

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:

Return from Genesys to AI

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.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.