> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Genesys integration

> Connect Voiceflow AI Chat agents to Genesys Cloud queues with customer context, two-way messages and human agent hand-off.

## 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](#human-agent-hand-off)** — send a customer who needs a person to the right staffed queue.
- **[Share customer context](#customer-context)** — give the receiving agent the AI exchange or a prepared escalation summary.
- **[Exchange messages and images](#support-messages)** — keep customer and agent replies in the same conversation.
- **[Show waiting information](#waiting-and-inactivity)** — display a queue estimate and warn an inactive customer.
- **[Return to AI](#ending-human-support)** — 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](/docs/documentation/deploy/environments/overview), and the Voiceflow Chat widget or a custom client implementing [Chat hand-off events](/docs/api-reference/agent-runtime/chat/handoff).
- 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](https://creator.voiceflow.com) for the connection and Handoff step. A Genesys administrator prepares the Open Messaging integration, message routing and lifecycle callbacks described below.

#### Developer

Set `PROJECT_ID`, `ENVIRONMENT_ALIAS` and `VF_TOKEN` in your shell. Use a server-side [Voiceflow API credential](/docs/api-reference/authentication) with project access. Examples use cURL, jq and a current [Voiceflow CLI](/docs/cli/install). Keep OAuth credentials, callback secrets and `VF_TOKEN` out of customer browsers and source control. Genesys-side administration is required for both methods.

<a id="start-with-the-shared-guides" />

<a id="connecting-genesys"></a>

## 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](https://help.genesys.cloud/articles/create-an-oauth-client/) 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:

```text title="Voiceflow Genesys callback"
https://general-runtime.voiceflow.com/handoff/webhook/genesys
```

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](https://help.genesys.cloud/articles/configure-an-open-messaging-integration/) 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](https://help.genesys.cloud/articles/set-up-a-transfer-to-acd-action/) and [inbound message routing](https://help.genesys.cloud/articles/add-inbound-message-route/) 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:

```text title="Agent connected request template"
{"type":"Start","conversationID":"$esc.jsonString(${input.conversationId})"}
```

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:

```text title="Conversation finished request template"
{"type":"End","conversationID":"$esc.jsonString(${input.conversationId})"}
```

Use [Genesys event triggers](https://help.genesys.cloud/articles/create-a-trigger/) 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](https://help.genesys.cloud/articles/add-contracts-custom-actions-integrations/), [request configuration](https://help.genesys.cloud/articles/request-configuration-data-actions/) and [User Defined credentials](https://help.genesys.cloud/articles/how-to-use-the-user-defined-credential-type/) 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](https://creator.voiceflow.com). In the left sidebar, open **More → Integrations**, find **Genesys** and select **Connect**.

Integrations navigation spotlighted beside the Genesys Connect card — Open More → Integrations in the same project as the Chat agent.

### 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.

Genesys connection dialog with Domain, Client ID, Webhook secret and OAuth secret key — Store the regional domain, OAuth client and matching callback secret.

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.

#### Developer

Save `genesys-connection.json` outside your repository. Replace each placeholder; use your organization's regional domain suffix without a scheme or host prefix.

```json title="genesys-connection.json"
{
  "integration": "genesys",
  "credentials": {
    "domain": "mypurecloud.com",
    "clientId": "YOUR_GENESYS_CLIENT_ID",
    "oauthSecretKey": "YOUR_GENESYS_OAUTH_CLIENT_SECRET",
    "secretKey": "YOUR_CALLBACK_SECRET"
  }
}
```

`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.

#### API

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/integration/genesys?projectID=$PROJECT_ID" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @genesys-connection.json
```

#### CLI

```bash
vf --output-format json integration connect --integration genesys \
  --project-id "$PROJECT_ID" < genesys-connection.json
```

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.

#### Developer

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.

<a id="human-agent-hand-off"></a>

## 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.

Complete Genesys Handoff editor with integration, customer, queue and continuation settings — Match the Open Messaging integration and queue, then choose context and continuation.

### 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.

#### Developer

Save `genesys-workflow.json`. Replace the queue placeholder and use one dedicated test customer. Do not deploy this fixed identity for multiple customers.

```json title="genesys-workflow.json"
{
  "name": "Genesys support",
  "entry": "handoff",
  "blocks": [{
    "key": "handoff",
    "name": "Connect Genesys support",
    "steps": [{
      "kind": "handoff",
      "content": {
        "config": {
          "provider": "genesys",
          "integrationId": "YOUR_OPEN_MESSAGING_INTEGRATION_ID",
          "customerAccountId": "customer-ns-2048",
          "userEmail": "ada@customer.example",
          "customerName": "Ada Nguyen",
          "queueName": "Customer support",
          "queueId": "YOUR_GENESYS_QUEUE_ID"
        },
        "handoffContext": { "type": "full" },
        "returnPath": true,
        "failPath": true
      }
    }]
  }]
}
```

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.

```bash title="prepare-genesys-patch.sh"
set -euo pipefail
WORKFLOW_ID=$(jq -er '.workflow.id' genesys-created.json)
jq --arg id "$WORKFLOW_ID" '
  .agent | {
    workflows: ((.workflows // []) + [{workflowID: $id, description: null}]),
    instructions: ((.instructions // "") + "\nWhen a customer asks for a person, use `Genesys support`. If it cannot connect, offer the approved alternative contact route.")
  }
' agent-before.json > agent-patch.json
```

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.

#### API

```bash
curl --fail-with-body --silent --show-error --request POST \
  "https://realtime-api.voiceflow.com/v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @genesys-workflow.json > genesys-created.json

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS&includeInstructions=true" \
  --header "Authorization: $VF_TOKEN" > agent-before.json
```

After inspecting the create result, prepare and review the attachment:

```bash
bash prepare-genesys-patch.sh
cat agent-patch.json
```

Apply the reviewed patch and compile Draft:

```bash
curl --fail-with-body --silent --show-error --request PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_TOKEN" --header 'Content-Type: application/json' \
  --data-binary @agent-patch.json

curl --fail-with-body --silent --show-error --request PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT_ALIAS/compile?projectID=$PROJECT_ID" \
  --header "Authorization: $VF_TOKEN"
```

#### CLI

```bash
vf --output-format json workflow create --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" < genesys-workflow.json > genesys-created.json

vf --output-format json agent get --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" --include-instructions > agent-before.json
```

After inspecting the create result, prepare and review the attachment:

```bash
bash prepare-genesys-patch.sh
cat agent-patch.json
```

Apply the reviewed patch and compile Draft:

```bash
vf --output-format json agent update --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS" < agent-patch.json

vf --output-format json environment compile --project-id "$PROJECT_ID" \
  --environment-alias "$ENVIRONMENT_ALIAS"
```

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](/docs/documentation/build/data/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.

#### Developer

- 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](/docs/cli/commands/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](/docs/cli/commands/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](/docs/cli/commands/workflow/get). Find the Handoff step's `id` in the response's top-level `blocks[].steps[]`. Use it with [Workflow update-step](/docs/cli/commands/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](/docs/api-reference/v4interact/interact-non-stream#streaming-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.

<a id="customer-context"></a>

## 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.

#### Developer

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](/docs/cli/commands/workflow/update-step):

```json title="Custom context patch"
{
  "kind": "handoff",
  "content": {
    "handoffContext": {
      "type": "custom",
      "variableID": "YOUR_SUMMARY_VARIABLE_ID"
    }
  }
}
```

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.

<a id="support-messages"></a>

## 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.

#### Developer

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:

```js title="Receive replies on the existing Chat session"
import { io } from 'socket.io-client';
const socket = io('https://general-runtime.voiceflow.com', {
  path: '/v4/interact/socket', autoConnect: false, reconnection: false,
  transports: ['websocket'],
  extraHeaders: {
    'x-voiceflow-project-id': process.env.PROJECT_ID,
    authorization: process.env.VF_TOKEN,
  },
});
let ready = false;
let activeVersionID;
let handoffActive = false;
let returnToAI = false;
socket.on('connect', () => {
  ready = false;
  socket.emit('client.start', {
    projectID: process.env.PROJECT_ID, userID: 'CURRENT_VF_USER_ID',
    environmentID: process.env.ENVIRONMENT_ALIAS,
    versionVariant: 'draft', sessionKey: 'CURRENT_SESSION_KEY',
    config: { modality: 'chat' },
  });
});
socket.on('client.started', ({ newSessionRequired, versionID }) => {
  if (newSessionRequired) {
    ready = false;
    console.error('The current session could not resume; do not replace an active handoff.');
    socket.disconnect();
    return;
  }
  activeVersionID = versionID;
  ready = true;
});
socket.on('action.trace', ({ trace }) => {
  if (trace.type !== 'live-agent-handoff') return;
  if (trace.payload.event === 'chat_started') {
    handoffActive = true;
    returnToAI = trace.payload.config?.returnToAI === true;
  }
  if (['chat_ended', 'chat_dismissed'].includes(trace.payload.event)) handoffActive = false;
  console.log(trace.payload);
});
socket.on('disconnect', () => { ready = false; });
socket.on('session.ended', () => { ready = false; });
socket.on('error', error => console.error(error));
socket.on('connect_error', error => console.error('Connection failed:', error));
socket.connect();

function sendSupportMessage(message) {
  if (!ready || !handoffActive) throw new Error('Wait for an active human hand-off.');
  socket.emit('action.send', {
    action: { type: 'live-agent-handoff', payload: { type: 'message', message } },
  });
}
```

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](/docs/api-reference/agent-runtime/chat/handoff) 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**.

#### Developer

### 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:

```json title="Uploaded file payload"
{
  "type": "file_upload",
  "files": [{
    "id": "UPLOADED_FIELDS_KEY",
    "name": "damage.jpg",
    "type": "image/jpeg",
    "size": 12000,
    "status": "uploaded"
  }]
}
```

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](/docs/api-reference/v4interact/interact-non-stream#streaming-action) 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.

#### Developer

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.

<a id="waiting-and-inactivity"></a>

## 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:

```json title="Queue wait estimate configuration"
{"waitTimeMessage": "Delay"}
```

Use `"None"` instead of `"Delay"` to disable it. Check the widget's waiting state before an agent accepts.

#### Developer

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.

#### Developer

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.

<a id="ending-human-support"></a>

## 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.

#### Developer

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:

```js title="Return from Genesys to AI"
if (ready && !handoffActive && returnToAI) {
  returnToAI = false;
  socket.emit('action.send', {
    action: {
      type: 'live-agent-handoff',
      payload: { type: 'return_to_voiceflow' },
    },
  });
}
```

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](/docs/api-reference/agent-runtime/chat/handoff#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](/docs/guides/integrations/contact-centers/test-connection) with real credentials, message routing and callbacks. Keep the previous route available for rollback.
