Skip to main content
Voiceflow supports handing off conversations to human agents through native integrations to contact center systems, using a handoff step. The handoff step manages the whole lifecycle: connecting the user to an agent, relaying messages and files in both directions, logging everything to your transcripts, and optionally returning the user to your AI agent afterward. Systems currently supported include:
  • Genesys
  • Ujet
  • Kustomer
  • Dixa
We add providers on request. If yours isn’t listed, contact support or speak to your account representative.

​
Core functionality

The following functionality is available for all supported platforms: File upload: Users and agents exchange files in both directions. Accepted types and size limits
depend on the provider. Conversation context: Pass context to the agent when the handoff starts: the full conversation
transcript, the contents of any variable you choose: a generated summary, an order ID, a routing reason or nothing at all. Back to AI: Return the user to your Voiceflow agent when the live conversation ends, with a
summary of the handoff already in the AI context. Useful for post-handoff surveys and follow-up flows. Transcript logging: Live agent messages are written to your Voiceflow transcripts as they
happen, so handoffs appear in transcript history and analytics alongside AI turns instead of
disappearing into the provider. Fail path: If the handoff can’t be started, the step follows a fail path instead of leaving the
user stranded, so you can retry, offer a callback, or fall back to AI. Transient provider errors are
retried automatically first, the fail path is only taken once those attempts are exhausted. Agent identity: Where the provider reports it, the agent’s name is shown to the user
rather than an anonymous “agent”.

​
Provider-specific capabilities

The table below outlines capabilities that have been implemented for each of these providers. With most providers, there is additional capability that has not yet been implemented. We can extend any of the providers based on their underlying APIs. Contact support or your accout representative if there is additional capability required for a specific provider. Wait time message. Tells the user how long they’re likely to wait. See waitTimeMessage below for the available formats. Internal note to agent. Attaches a note to the conversation that agents can see but the user
can’t. See noteBodyText. Inactivity timeout. After a period of user silence, warns that the session is about to expire.
The timer resets whenever the user responds. Configured on the handoff step. Dismiss and resume. If the user closes the chat, they’re offered a transcript download and can
either continue the same conversation or start a new one. Localized system messages. Status messages such as “agent joined”, “agent left”, and “chat
ended” follow the conversation language. English, French, and Spanish are supported today. Agent-to-agent transfer. When an agent hands the user to a colleague, the user sees the transfer happen instead of sitting in silence.

​
Configuration

The step supports a number of optional settings. These are can be specified using a JSON object in the Metadata field of the live agent handoff step:
All settings are optional. Omit the ones you don’t need, or leave the field empty for provider
defaults. The provider coverage noted for each setting reflects current functionality, but is not fixed. Where a provider’s API exposes the capability, we can extend any setting to it.

​
Using variables

Any value can reference Voiceflow variables with {variable_name}, including mid-sentence as shown above. When a value is exactly one variable, it keeps that variable’s type — so
"disableFileUpload": "{upload_flag}" works when upload_flag holds a boolean.

​
JSON syntax

The field must be valid JSON. Two rules that are important to follow:
  • Text and enum values need quotes: "waitTimeMessage": "None", not waitTimeMessage: None.
  • Booleans don’t: "disableFileUpload": true, not "true".
If the JSON is invalid, the entire metadata object is ignored — not just the offending line — so
a single unquoted value will silently drop your other settings too. Validate the JSON before
publishing. If one setting merely has the wrong type, only that setting is dropped and the rest
still apply. Unknown JSON keys are preserved rather than rejected, but only the settings below are supported:

​
Settings reference

​
noteBodyText

Type: string · Providers: Kustomer An internal note attached to the conversation, visible to agents but not to the user. Commonly used to pass an escalation reason or a conversation summary.

​
disableFileUpload

Type: boolean · Providers: all When true, hides the file upload control so the user can’t send files. Agents can still send files to the user.

​
waitTimeMessage

Type: enum · Providers: Genesys, Ujet Controls how the expected wait is communicated while the user waits for an agent. How each provider presents it:
  • Genesys updates the estimate repeatedly while the user waits. None stops these updates.
  • Ujet states the estimate once, in the opening message. None keeps that message but drops the estimate from it.
  • Kustomer and Dixa don’t show a wait time message, so this setting has no effect.
If you pick a value a provider doesn’t currently support, that provider falls back to its own
default rather than turning the message off. To disable the message, set None explicitly.
Each provider has additional functionality available that has not yet been implemented. Where the provider’s API exposes the data, we can add others on request — Delay or Position for Ujet, or Position for Genesys, for example. Live agent workflows tend to be specific to how each team operates, and we are excited to continue extending the supported functionality. If you need a setting extended to another provider, a new configuration option, or a provider we don’t yet support, contact support or reach out to your account representative.