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

# Chat and SMS handoff

> Handoff pauses the AI conversation and connects the customer to a human through your support platform.

## Overview

Handoff pauses the AI conversation and connects the customer to a human through your support platform. A **Handoff** step in a Workflow selects the provider, supplies customer context and defines the return and failure paths. Human agents answer in their own support workspace.

### Examples of when to use Handoff

Use Handoff when resolving the request requires a person. For example:

- **Resolve an order exception:** pass the customer and order details to the team authorized to make the decision.
- **Honor a request for a person:** route the customer to support without asking them to restate their issue.
- **Continue support by SMS:** let a customer and support teammate exchange replies on the same text conversation.

For phone calls, use [Call forward](/docs/guides/studio/voice/transfer-calls). Creating a ticket alone does not establish a live message connection.

<a id="how-to-use"></a>

### How to use Handoff

#### 1. Connect the support platform

Open **Settings → Integrations** and connect a [supported provider](/docs/documentation/handoff/platforms). For another platform, first build the [Custom Handoff connection](/docs/developers/handoff/connect).

Creator Integrations catalog with support-platform connections — Connect your support provider in the project’s Integrations.

#### 2. Configure the Handoff step

Add **Handoff** to the escalation branch of a Workflow. Open the step, select **Handoff provider** and populate that provider’s customer and routing fields.

Handoff settings in the native Workflow editor — Configure the provider and customer fields in the Handoff step.

#### 3. Choose context and follow-up paths

Choose **Handoff context**. Enable and connect **Return path** for your follow-up and **Failure path** for an alternative contact option if creation fails.

Handoff settings in the native Workflow editor — Choose the escalation context and connect return and failure branches.

#### Verify the conversation

Run the Workflow, exchange replies with a teammate in the support workspace and end the handoff. Check the configured follow-up. Repeat on the actual published channel; an editor run does not verify SMS delivery.

<a id="connections"></a>

## Connecting support platforms

Choose a native provider or connect your own support platform.

Native providers are **Genesys**, **UJET**, **Kustomer**, **Dixa** and **Zendesk**. Zendesk uses Sunshine Conversations and Agent Workspace. Other platforms require a service implementing the [connection API](/docs/developers/handoff/connection-api); select **Custom Handoff** for that service.

Provider-specific controls appear after the connection is selected and connected. Changing the provider replaces the step’s provider configuration; recheck its fields. Where Draft connections are configured, Draft runs can use credentials different from published runs.

Follow [Set up handoff](/docs/documentation/handoff/setup) for the Studio workflow or [Build a connection](/docs/developers/handoff/connect) for the service implementation.

<a id="context-and-routing"></a>

## Customer context and routing

Send the customer details and escalation reason to the right team.

Map the customer identity and destination supported by your provider. **Queue ID**, **Assigned team ID** and Zendesk **Group ID** refer to different provider objects; they are not interchangeable.

### Choosing Handoff context

**Handoff context** has three choices:

- **Full transcript:** sends conversational text from the AI’s memory. This is not an export of every trace, attachment or debug log.
- **Custom:** sends the current value of a selected string variable. Populate it before handoff; selecting it does not generate a summary.
- **None:** sends no handoff context.

Handoff settings in the native Workflow editor — Select a populated variable for Custom handoff context.

Use [Context and routing](/docs/documentation/handoff/context) for the setup. Kustomer also accepts a private note through `noteBodyText` in **Configuration**. Keep provider credentials in Integrations, not in this JSON.

### Order-support context example

Pass an escalation summary without exposing unrelated customer data.

Before the step, store “Order NS-2048 arrived damaged; the customer requests a replacement” in `handoff_summary`. Choose **Custom** and select that variable. Set the destination your service maps to order support. Verify the human sees the summary and can respond in the correct inbox. These are illustrative names, not built-in queues.

<a id="waiting"></a>

## Waiting and agent availability

Set realistic expectations using the statuses your provider supplies.

### Provider wait estimates

Wait estimates are provider-specific. Genesys can send repeated estimated delays; UJET can include an estimated connection time in its opening message. In **Configuration**, `"waitTimeMessage": "None"` disables the estimate. `Position` is not currently rendered by any provider.

### Inactivity and resuming human support

Genesys exposes **Inactivity timeout warning (minutes)**. A positive value controls when a warning appears after customer inactivity; a customer reply resets the warning timer. The warning itself does not close the conversation.

UJET can dismiss an inactive chat and offer **Continue conversation** to resume that same conversation. An unavailable resume can leave the customer able to try again; a failed resume ends handoff. UJET’s supported system messages can follow English, French or Spanish. Human replies are not translated by this setting.

Dixa can send agent typing indicators. See the [provider differences](/docs/documentation/handoff/platforms#capability-boundaries) before relying on a status in your chosen provider.

### Customer inactivity response

When the widget receives a dismissal warning, it offers **I am still here**. Selecting it sends that text as a handoff customer message and resets the provider's customer-activity timer. The warning itself does not end the conversation. This widget control does not create a new Custom Handoff callback event type.

<a id="messages-and-files"></a>

## Messages and attachments

Exchange text and supported files without competing AI replies.

After handoff starts, customer messages go to the support conversation and human replies return through the same connection. Provider events supply agent identity where available; Zendesk messaging can identify the brand instead of an individual teammate.

### Customer attachments

The web chat upload control allows one pending attachment. Its current checks allow images up to 100 MB for UJET, files up to 100 MB for Kustomer and files up to 25 MB for other providers. The provider and upload service can impose additional restrictions. These widget checks do not establish SMS attachment support.

### Upload controls

Set `"disableFileUpload": true` in **Configuration** to hide the widget’s customer upload control. This does not prevent human agents from sending files and is not server-side file authorization. Custom clients must honor the returned configuration and implement the [client lifecycle](/docs/api-reference/agent-runtime/chat/handoff).

For Custom Handoff, your service must fetch and relay the file; accepting a file message without forwarding its bytes is not attachment support.

<a id="returning-to-ai"></a>

## Returning to AI

Continue the conversation after human support finishes.

Enable **Return path** on the Handoff step. Connect its output to a follow-up block when the Workflow should continue there. In an agentic Workflow, an enabled but unconnected return can return control to the parent agent. Disabling Return path ends the session when the return request is handled.

When the provider ends chat, the Voiceflow web chat sends the return request if enabled. The Twilio SMS relay also performs the enabled return. A custom client must implement this behavior; a provider closure callback alone does not make every interface resume.

On return, the runtime attempts to summarize the recorded customer/human text exchange into the AI’s context. Attachments and typing indicators are not part of that text summary. Follow [Return to AI](/docs/documentation/handoff/return-to-ai) to configure and verify the path.

### Customer choices in Webchat

| Handoff state | Available behavior |
| --- | --- |
| Ended, Return path enabled | The widget requests return to AI automatically |
| Ended, Return path disabled | **Download transcript** or **Start new conversation** |
| Dismissed | **Continue conversation**, **Download transcript** and **Start new conversation**; **Return to AI** also appears when enabled |

**Continue conversation** resumes the dismissed human conversation; **Start new conversation** restarts the customer chat. Downloading a transcript does not resume AI. These are widget choices, not SMS commands. A custom customer interface must implement its own controls and the [Chat handoff requests](/docs/api-reference/agent-runtime/chat/handoff).

<a id="failure-and-review"></a>

## Failure and conversation review

Offer a useful fallback and inspect the exchange in Transcripts.

Enable **Failure path** and connect an alternative route before testing. If handoff creation fails, the runtime retries eligible transient errors and then takes that route. This is a startup failure path; it does not catch every later message-delivery error.

Handoff text and supported lifecycle events join the conversation’s [Transcript](/docs/documentation/measure/transcripts). Agent typing is transient and is not logged. Use the conversation and provider IDs to investigate a failed stage rather than assuming that a successful connection means a human received the message.

Follow [Handoff troubleshooting](/docs/documentation/handoff/troubleshooting) for creation, delivery, routing, files and closure checks.
