Receive live agent updates
An SSE request ends with its turn. Later human-agent messages are pushed as Socket.IO action.trace events; they do not reopen that SSE response. Connect a socket.io-client client to https://general-runtime.voiceflow.com with path /v4/interact/socket and config.modality: 'chat' for the active conversation.
Register listeners before connecting. On every Socket.IO connect, emit client.start with the current project, user, Environment and session key. Wait for client.started; newSessionRequired: false confirms the existing session is ready. If it is true, the key did not resume a session—do not create a replacement and treat it as the existing handoff. A session.ended event ends that conversation.
The example assumes a project with public API access. A private project requires an authorized trusted client; keep its API credential on your server. The Environment must be the one owning the session key.
Customer messages during handoff use action.type: "live-agent-handoff", with payload.type: "message" and the message string. The Sending actions request schema also defines file attachments and the continue_conversation and return_to_voiceflow payloads. The connection-service endpoints below are called by Voiceflow; your customer interface sends runtime actions instead.
Customer controls and terminal states
The Voiceflow widget implements the choices below. A custom client must render its own controls and send the applicable runtime actions; provider callbacks do not render this UI for it.
Transcript download is a client action, not a Custom Handoff callback type. A restart creates a fresh customer conversation; it is not a resume. Implement these state transitions separately from message rendering and ignore stale updates after the active handoff ends.
Handoff trace
live-agent-handoff trace
Signals a handoff of the conversation to a live agent platform. Every shape of the payload carries conversationID, message, and event; the remaining fields vary by shape, and some carry a provider naming the platform.
“Required” above means required in every payload shape. A field can be required for a particular state or event even when it is not required in every shape; the schema below defines those conditions.
live-agent-handoff payload schema
Look up nested fields, conditional requirements and constraints.
This is the OpenAPI payload schema, not an example response. Referenced definitions are included under components.schemas.
Custom Handoff connection
What this API connects
Voiceflow calls your HTTPS service, which translates requests into your support platform’s APIs. These are endpoints you implement, relative to the Base URL configured in Custom Handoff. They are not Voiceflow REST API endpoints.
Conversation lifecycle
Create one provider conversation, save its mapping to the ID your service returns, then relay messages until closure. Key the mapping by Voiceflow project and connection conversation ID. Persist the mapping before replying to create. Provider events may arrive immediately: queue them until creation has completed.
The support platform conversation ID and the ID your service returns may differ. Every callback must use the latter. Keep user identity separate from conversation identity.
Endpoints and authentication
Voiceflow sends the configured authentication header verbatim. Use a non-empty secret, such as Authorization: Bearer YOUR_SERVICE_TOKEN. Base URL must be HTTPS; redirects are not followed. The runtime rejects unsafe destinations.
Create fields
The runtime sends the following JSON members. Nullable means the member can contain JSON null; it does not mean an empty string is a useful identity.
Creation includes X-Voiceflow-Idempotency-Key. Repeated attempts with the same key must return the same conversation without creating another. Scope this key to the authenticated connection.
Message fields
The custom upload path permits up to 25 MB; vendor limits can be smaller. Download the file before expiry and validate its size and destination before storing it. The message ID is not a session-wide guarantee of deduplication for separately submitted customer requests.
Create response and end request
Return JSON from create with required non-empty string conversationId and optional nullable string message. Unknown response members are ignored. Null or empty message uses the runtime’s default connection message. Message and end endpoints need a successful 2xx status; their response bodies are not read. End receives one required timestamp ISO date-time string; repeated end requests must be safe after closure.
The create response’s conversationId is your connection ID. Callback conversationId uses that same value; the customer client’s runtime conversation ID is separately project-scoped. Do not substitute the Voiceflow user/session ID for either conversation ID.
Example create request
Example response:
These are illustrative IDs; use actual values from the request and the persisted mapping.
Related guides
Build the connection · Webhook events
Errors and retry behavior
Return an error object such as { "error": { "code": "unavailable", "message": "Provider unavailable", "retryAfterSeconds": 2 } } with an appropriate HTTP error status. Codes: invalid_request, unauthorized, not_found, rejected, rate_limited, internal, unavailable. retryAfterSeconds, when supplied, is a positive integer.
The custom service bounds individual requests to 10 seconds and retries eligible transient failures. Do not rely on an exact total delivery count: the handoff handler also retries. Use idempotency for creation and messages, durable event delivery, and a failure path. A timeout can happen after the provider accepted a request; reconcile before creating a duplicate.
HTTP status determines retryability, not the body code: 429 and 5xx are retryable; other 4xx are not. Timeouts and network failures are treated as 503. A malformed error body falls back to HTTP status/status text. Redirects become non-retryable 400 errors. The configured origin is checked before each request. A valid retryAfterSeconds supplies the delay; otherwise the service uses its internal backoff. Initial handoff creation has an additional bounded retry loop, so callers must not assume a fixed total attempt count.
Custom Handoff events
Your service translates support-platform events into Voiceflow’s handoff events. Send them to the runtime’s POST /handoff/webhook/custom route. Use the runtime base URL for your deployment; for the hosted runtime this is https://general-runtime.voiceflow.com/handoff/webhook/custom.
Event envelope and payload
Every request contains projectId and events. Send one event per request. The parser accepts 1–50 events; single-event delivery makes retries and failures easier to isolate.
Every event requires a stable id, conversationId, timestamp string, and type. Use the conversation ID returned by your connection service.
Internal notes and echoed customer messages must not become message.received. Files must be retrievable without a vendor credential. The current custom event vocabulary does not include typing or queue-position events.
Field types and requiredness
Unknown object members are stripped by the parser. Send only the fields belonging to the selected event type. Use the provider’s actual event time in timestamp and the current time for the signature header; they serve different purposes.
Example human reply
Replace IDs and timestamp with values from the active conversation. Do not send this historical timestamp as a live signature timestamp.
Sign, deliver and retry
Set X-Signature-Timestamp to the current Unix timestamp in seconds. Compute HMAC-SHA256 over the timestamp string concatenated directly with JSON.stringify(body), encode the digest as base64, and set X-Signature: primary=DIGEST. Use the same Webhook secret configured in Voiceflow; it must be at least 32 characters.
The runtime validates within a five-minute clock window. It verifies serialized parsed JSON, not the raw request bytes: build and send one JSON object consistently. During secret rotation, the signature header may carry both primary=DIGEST and secondary=DIGEST, separated by a space. Each is checked against the active conversation’s stored secret.
The starter signing helper implements this format. Retain the event ID across retries, refresh the signature timestamp, and deliver from a durable outbox. A 401 requires fixing signing; a 404 can mean the conversation is not active or creation has not completed. Retry an early callback only while creation is known to be pending; stop replaying events for closed sessions. A 2xx response acknowledges processing, not proof the customer has read the message.
Do not mint callback IDs beginning with vf_: that prefix is reserved for Voiceflow outbound messages and is ignored on callbacks. Deduplicate provider events before delivery; the runtime does not maintain a general event-ID deduplication store for Custom Handoff. It applies a batch in order, not as one atomic transaction. A callback can be retried after an earlier event has already been applied.
HTTP outcomes
The active-conversation lookup happens before signature validation. Consequently an unknown conversation can return 404 without testing your signature. A batch containing only reserved vf_ IDs produces no traces and can return 200 without delivering anything. Deduplicate and queue at your service boundary; the runtime does not provide atomic batch processing or general replay protection by event ID.