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

# Set up AI-to-human handoff

> Send a customer from a Voiceflow agent to the right contact-center team, with the context that team needs.

Send a customer from a Voiceflow agent to the right contact-center team, with the context that team needs. Phone calls use **Call forward**; Chat uses a **Handoff** step and a live-message connection. Configure and validate them separately.

## Before you begin

- A working test entry point from [Integrate your contact center](/docs/guides/integrations/contact-centers/integrate), a non-production Environment and a staffed receiving destination.
- For Phone, a transfer number or SIP destination supplied by your contact-center administrator. Keep it separate from the number or route that sends calls into Voiceflow.
- For Chat, a connected Genesys, UJET or Dixa messaging integration, or a deployed [Custom Handoff service](/docs/developers/handoff/connect). Obtain the actual receiving queue/menu and test customer identity before configuring the step.
- For Code, the project ID, Environment alias and server-side API credential. Retain the current agent and Workflow configuration before changing them.

<a id="configure-the-transfer" />

## Set up the human route

### 1. Choose when to hand off and what to send

Use a clear condition such as a customer asking for a person or needing an exception the AI cannot approve. Choose the receiving team and minimum useful context: the customer's verified identity, reason for contact and unresolved task.

For Chat, prepare a summary string before Handoff or choose Full transcript or None explicitly. For SIP, agree which [transfer context headers](/docs/api-reference/agent-runtime/voice/sip/transfers#pass-transfer-context) the receiver accepts and how it maps them. Context delivery does not establish a live customer-message connection.

### 2. Configure the channel's transfer

#### Phone

#### Studio

Open [Agent studio](https://creator.voiceflow.com), select the project and test Environment, then open **Agent → System tools → Call forward**. Enable it, select **Phone number** or **SIP**, enter the staffed test destination and describe when the agent should transfer.

Agent Call forward system tool with a transfer condition and test phone destination — Set the human destination and the condition that should select Call forward.

Use a [Workflow Call forward step](/docs/documentation/build/steps/call-forward) instead when a fixed branch should make the transfer decision.

#### Developer

Read the agent with [Get agent](/docs/api-reference/agent/get-agent) and retain its current `callForwardTool`. Update only that tool in the test Environment:

```bash title="Set a staffed phone destination"
curl --fail-with-body --silent --show-error --request PATCH \
  "https://realtime-api.voiceflow.com/v2/stable/agent?projectID=$VF_PROJECT_ID&environmentAlias=$VF_ENVIRONMENT_ALIAS" \
  --header "Authorization: $VF_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"callForwardTool":{"enabled":true,"addressType":"phone","address":"+14165550123","description":"Transfer when the customer asks to speak to the support team.","messages":null,"toolSound":null}}'
```

Replace the example number with your staffed test destination. For SIP, set `addressType` to `"sip"` and use your administrator's destination in `address`; see [destination formats](/docs/documentation/build/steps/call-forward#configuration). Read the agent back, then [compile the test Environment](/docs/api-reference/environment/compile-environment). Confirm the phone connection targets that Environment and version.

A custom telephony client must implement the [call-forward trace](/docs/api-reference/agent-runtime/voice/handoff). An audio-only browser session has no provider call to transfer.

#### Chat

#### Studio

In the project's **Workflows**, open the escalation Workflow and add **Handoff** to its human-support branch. Open the step, select **Handoff provider**, then enter the customer and routing fields for your connected provider.

Genesys Agent handoff editor with customer identity and queue fields — Map the customer and receiving team in the contact-center Handoff step.

Set **Handoff context** explicitly. A Custom summary must be a populated string variable before the step runs. Enable and connect **Failure path** to an alternative contact option. Configure **Return path** for the intended continuation, or disable it to end the session on return.

Ensure the agent can reach this Workflow: add it to the Agent's Workflows list and describe when it should run. Publish to the test Environment used by your customer channel.

#### Developer

Create or update an escalation Workflow through [Platform APIs](/docs/api-reference/api-overview). The Handoff step's configuration needs the connected provider, resolved customer identity, provider routing fields, an explicit context mode, and return/failure paths. Use the [Handoff fields reference](/docs/documentation/build/steps/handoff) for the provider's exact configuration.

For a Custom Handoff connection, follow the complete [API configuration sequence](/docs/developers/handoff/connect#configure-voiceflow-through-the-api): connect your deployed HTTPS service, create the fallback Message and Handoff Workflow, register it in the agent's existing Workflows list, then publish the test Environment. Retain the returned Workflow ID and preserve existing agent instructions and Workflow entries when patching them. Creating an unreachable Workflow does not enable escalation.

For Genesys, UJET or Dixa, the connection must already be authorized and its receiving route supplied by your contact-center administrator. Do not use Custom Handoff service credentials as provider credentials. The same customer and routing checks apply after publishing.

In your customer client, keep the existing Chat session and subscribe to asynchronous human replies through [Socket.IO handoff events](/docs/api-reference/agent-runtime/chat/handoff). Register listeners before connecting, send `client.start` on each connection, and wait for `client.started` with `newSessionRequired: false`. During human support, send customer messages with `action.send` and action type `live-agent-handoff`; render the incoming `action.trace` events. The preceding SSE response cannot carry later human replies.

Implement the documented `chat_ended` and `chat_dismissed` controls as well as message delivery. A new session is not a continuation of the existing handoff.

### 3. Verify the receiving side

Make a test contact through the actual customer entry point and trigger the human route. Have a teammate answer the designated queue or number. Verify the customer identity and permitted context in that workspace, then exchange speech or public messages in both directions.

For Genesys, the integration sends a queue-name attribute that your provider routing flow must interpret; Queue ID is used for the wait estimate. For Dixa, creation can succeed even when the requested queue transfer fails. In both cases, check the receiving team rather than treating conversation creation as successful routing.

Complete the failure, closure and release checks in [Test and launch your integration](/docs/guides/integrations/contact-centers/test-connection).

<a id="verify-and-release" />

## Completion check

The customer reaches the intended human team once, the agreed context arrives, and the AI stops contributing while the human handles the conversation. For Chat, verify closure in the same customer session. For Phone, verify an answered call, not just an accepted transfer request.

<a id="transfer-limitations-and-recovery" />

## Phone transfer boundaries

This Call forward path does not provide a warm-transfer briefing or an automatic busy/no-answer recovery branch. A rejected transfer can end the call. Staff the test destination and inspect [SIP transfer results](/docs/api-reference/agent-runtime/voice/sip/troubleshooting) before releasing the route.
