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, 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. 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.
Set up the human route
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 the receiver accepts and how it maps them. Context delivery does not establish a live customer-message connection.
Configure the channel's transfer
Studio
Open Agent studio, 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.
Use a Workflow Call forward step instead when a fixed branch should make the transfer decision.
Code
Read the agent with Get agent and retain its current callForwardTool. Update only that tool in the test Environment:
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. Read the agent back, then compile the test Environment. Confirm the phone connection targets that Environment and version.
A custom telephony client must implement the call-forward trace. An audio-only browser session has no provider call to transfer.
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.
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.
Code
Create or update an escalation Workflow through Platform APIs. 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 for the provider’s exact configuration.
For a Custom Handoff connection, follow the complete API configuration sequence: 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. 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.
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.
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.
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 before releasing the route.