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

# Human agent hand-off

> Keep the customer in the same Chat conversation while a human replies from your help desk. This walkthrough uses Zendesk Agent Workspace; the other provider manuals…

Keep the customer in the same Chat conversation while a human replies from your help desk. This walkthrough uses Zendesk Agent Workspace; the other provider manuals supply their own connection and routing configuration.

## Before you begin

- A Voiceflow agent, test Environment and working customer Chat connection. Use a test customer and a teammate who can reply in the help desk.
- A stable customer ID supplied by your application, plus the permitted customer details and escalation reason.
- Administrator access for the help-desk connection. For Zendesk, prepare the Sunshine Conversations app credentials, Agent Workspace integration and reply webhook described in [Human agent hand-off for Zendesk](/docs/guides/integrations/zendesk/overview#live-agent). Ticket-tool authorization alone does not establish this connection.
- For [Intercom](/docs/guides/integrations/intercom/overview#live-agent), [Gorgias](/docs/guides/integrations/gorgias/overview#live-agent), [Chatwoot](/docs/guides/integrations/chatwoot/overview#live-agent) or [Freshchat](/docs/guides/integrations/freshchat/overview#live-agent), a developer-hosted relay is a separate prerequisite. Use the provider's **Human agent hand-off** section to deploy it and hand its HTTPS URL, service authorization and callback signing secret to the builder.

This guide covers Chat messages. Use [Transfer a phone call](/docs/guides/studio/voice/transfer-calls) for an active phone or SIP call.

## Configure the escalation

### 1. Connect the help desk

#### Studio

Open [Agent studio](https://creator.voiceflow.com), choose the test project, then open **More → Integrations**. For Zendesk, select **Sunshine Conversations**, enter the app credentials and webhook secret, then connect. This is separate from the Zendesk ticket-tools card.

Sunshine Conversations connection fields in Creator Integrations — Connect Sunshine Conversations for the Zendesk human reply path.

For a relay-based provider, select **Custom Handoff** and enter the service details supplied by your developer.

#### Developer

Complete the provider's connection setup in its Code view. For Zendesk, [save the Sunshine connection and configure the Workflow](/docs/guides/integrations/zendesk/overview?view=developer#connect-and-configure-handoff) with the project ID, app credentials and webhook secret. For a relay, use that provider's Code instructions and [connection service contract](/docs/developers/handoff/connect).

Before continuing, retain the Workflow ID and the Handoff step's node ID in the same project. The connection stores credentials; the Workflow owns routing and context.

### 2. Map the customer, destination and context

#### Studio

Open **Build → Workflows**, add or open the escalation Workflow, then add a **Handoff step**. Select the connected provider. For Sunshine, map **End user ID** to the verified customer ID; set the needed **User email**, **Customer name**, **Group ID**, **Brand ID** and **Priority** from your account.

Choose **Handoff context**: **Full transcript**, a **Custom variable** containing your support summary, or **None**. Send only the information the support agent needs.

Handoff step with Sunshine Conversations, customer identity and routing fields — Map the verified customer and the destination your support team uses.

#### Developer

Read the existing step before updating it. Use the [provider's Workflow configuration](/docs/guides/integrations/zendesk/overview?view=developer#connect-and-configure-handoff) to set the verified customer variables, destination and context on that Handoff node. Create any referenced variables first and populate them before escalation. Register the Workflow with the agent; saving a connection alone does not make it callable.

For Sunshine, a Group ID populates the Zendesk routing field. It does not create a queue or establish a queue position. Relay-based providers need their own explicit mapping.

### 3. Define when to escalate and what happens afterward

#### Studio

Add the Workflow to the agent and describe when to use it, such as a customer asking for a person or a request requiring human approval. Connect the Handoff **Failure path** to a useful fallback. Enable and connect **Return path** if the customer should be able to return to AI afterward.

#### Developer

Set the attached Workflow's trigger and connect the Handoff node's failure and return ports. Compile the Draft after changing the graph or attachment. Follow the provider's exact node fields and port IDs; do not create a new session to represent a return to AI.

If connection fails, tell the customer and offer the fallback contact. Do not announce that a human has joined merely because the request was sent.

### 4. Use a customer client that receives human replies

#### Studio

Use the Voiceflow Chat widget for this walkthrough. It handles the human-support messages and return controls. Publish the tested Environment, then open a fresh widget session that targets it.

#### Developer

Your Chat client must receive asynchronous hand-off updates. An HTTP streaming response alone is insufficient. Implement the [Chat hand-off runtime contract](/docs/api-reference/agent-runtime/chat/handoff):

1. Register Socket.IO listeners before connecting and resume the existing project, user, Environment and `sessionKey` with `client.start`.
2. Wait for `client.started` with `newSessionRequired: false` before sending customer messages. A replacement session is not a resumed hand-off.
3. Render incoming `action.trace` events whose `trace.type` is `live-agent-handoff` for the active conversation.
4. Send customer text through `action.send` with `action.type: "live-agent-handoff"`, `payload.type: "message"` and the message string. Handle end, return and disconnect states separately.

Publish the configured Environment and test that client against a fresh session. Keep project and provider credentials on your trusted backend.

## Verify the live exchange

With the customer session and help-desk inbox open:

1. Ask for a human. Confirm the correct customer, issue and permitted context arrive in the intended inbox.
2. Send a customer message and a public human reply. Each must arrive once in the other interface; private notes must stay private.
3. Send a final reply, then end the human conversation. Confirm that reply arrives before closure and that the configured end or return behavior works.
4. Test a failed connection and confirm the customer sees the fallback.

The relay examples for Intercom, Gorgias, Chatwoot and Freshchat cover text delivery. Follow the provider manual before enabling attachments.

### A connected help desk does not deliver replies

Trace the provider receiver, active conversation and customer client.

Check the provider webhook or relay receiver, stored customer/conversation mapping and callback authorization first. Then check that the customer client resumed the same session and processes the hand-off events. Use [handoff troubleshooting](/docs/documentation/handoff/troubleshooting) rather than repeatedly reconnecting a working account.
