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

# Human agent hand-off

> Relay support messages through a Custom Handoff connection.

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

```js title="Receive handoff updates for an existing Chat session"
import { io } from 'socket.io-client';

const socket = io('https://general-runtime.voiceflow.com', {
  path: '/v4/interact/socket',
  autoConnect: false,
});
let ready = false;

socket.on('connect', () => {
  ready = false;
  socket.emit('client.start', {
    projectID: 'YOUR_PROJECT_ID',
    userID: 'YOUR_USER_ID',
    environmentID: 'YOUR_ENVIRONMENT_ALIAS',
    sessionKey: 'CURRENT_SESSION_KEY',
    config: { modality: 'chat' },
  });
});
socket.on('client.started', ({ newSessionRequired }) => {
  ready = !newSessionRequired;
  if (!ready) console.error('The handoff session was not resumed.');
});
socket.on('action.trace', ({ trace }) => {
  if (trace.type === 'live-agent-handoff') console.log(trace.payload);
});
socket.on('session.ended', () => { ready = false; });
socket.on('disconnect', () => { ready = false; });
socket.on('error', error => { console.error(error); });
socket.connect();

// Send only after client.started confirms the session is ready.
function sendSupportMessage(message) {
  if (!ready) return;
  socket.emit('action.send', {
    action: { type: 'live-agent-handoff', payload: { type: 'message', message } },
  });
}
```

Customer messages during handoff use `action.type: "live-agent-handoff"`, with `payload.type: "message"` and the message string. The [Sending actions request schema](/docs/api-reference/v4interact/interact-non-stream#streaming-action) 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.

| Trace / configuration | Customer-facing behavior |
| --- | --- |
| `chat_ended`, return enabled | Send `return_to_voiceflow` to resume the configured continuation |
| `chat_ended`, return disabled | Offer transcript download and a new conversation; do not resume the ended relay |
| `chat_dismissed` | Offer `continue_conversation` for the same human conversation; offer `return_to_voiceflow` only when enabled. Download/restart are separate client actions |
| `chat_dismissal_warning` | The widget offers **I am still here**, sending that text as a handoff `message` |

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.

| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `agent` | object | no | always |
| `config` | LiveAgentHandoffWidgetConfig | no | `event` is `chat_started` |
| `continueMessage` | string | no | `event` is `chat_ended` or `chat_dismissed` |
| `conversationID` | string | yes | always |
| `downloadMessage` | string | no | `event` is `chat_ended` or `chat_dismissed` |
| `event` | `"chat_started"` or `"chat_ended"` or `"chat_dismissed"` or `"file_received"` or `"participant_joined"` or `"message_received"` or `"event"` or `"wait_time"` or `"chat_dismissal_warning"` or `"agent_typing"` | yes | always |
| `file` | object | no | `event` is `file_received` |
| `message` | string | yes | always |
| `newConversationMessage` | string | no | `event` is `chat_ended` or `chat_dismissed` |
| `provider` | `"ujet"` or `"genesys"` or `"kustomer"` or `"dixa"` or `"sunshine"` or `"custom"` | no | `event` is `chat_started` |
| `translationKey` | string | no | always |
| `translationParams` | object | no | always |

“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`.

```json title="OpenAPI payload schema"
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "conversationID": {
          "type": "string",
          "minLength": 1
        },
        "message": {
          "type": "string"
        },
        "translationKey": {
          "type": "string"
        },
        "translationParams": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "agent": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "imageUrl": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "name"
          ]
        },
        "event": {
          "type": "string",
          "enum": [
            "chat_started"
          ],
          "x-enumNames": [
            "CHAT_STARTED"
          ]
        },
        "provider": {
          "allOf": [
            {
              "$ref": "#/components/schemas/LiveAgentHandoffProvider"
            }
          ]
        },
        "config": {
          "allOf": [
            {
              "$ref": "#/components/schemas/LiveAgentHandoffWidgetConfig"
            }
          ]
        }
      },
      "required": [
        "conversationID",
        "message",
        "event"
      ]
    },
    {
      "type": "object",
      "properties": {
        "conversationID": {
          "type": "string",
          "minLength": 1
        },
        "message": {
          "type": "string"
        },
        "translationKey": {
          "type": "string"
        },
        "translationParams": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "agent": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "imageUrl": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "name"
          ]
        },
        "event": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "chat_ended"
              ],
              "x-enumNames": [
                "CHAT_ENDED"
              ]
            },
            {
              "type": "string",
              "enum": [
                "chat_dismissed"
              ],
              "x-enumNames": [
                "CHAT_DISMISSED"
              ]
            }
          ]
        },
        "downloadMessage": {
          "type": "string"
        },
        "continueMessage": {
          "type": "string"
        },
        "newConversationMessage": {
          "type": "string"
        }
      },
      "required": [
        "conversationID",
        "message",
        "event"
      ]
    },
    {
      "type": "object",
      "properties": {
        "conversationID": {
          "type": "string",
          "minLength": 1
        },
        "message": {
          "type": "string"
        },
        "translationKey": {
          "type": "string"
        },
        "translationParams": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "agent": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "imageUrl": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "name"
          ]
        },
        "event": {
          "type": "string",
          "enum": [
            "file_received"
          ],
          "x-enumNames": [
            "FILE_RECEIVED"
          ]
        },
        "file": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "type": {
              "type": "string"
            }
          },
          "required": [
            "url",
            "name"
          ]
        }
      },
      "required": [
        "conversationID",
        "message",
        "event",
        "file"
      ]
    },
    {
      "type": "object",
      "properties": {
        "conversationID": {
          "type": "string",
          "minLength": 1
        },
        "message": {
          "type": "string"
        },
        "translationKey": {
          "type": "string"
        },
        "translationParams": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "agent": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "imageUrl": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "name"
          ]
        },
        "event": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "participant_joined"
              ],
              "x-enumNames": [
                "PARTICIPANT_JOINED"
              ]
            },
            {
              "type": "string",
              "enum": [
                "message_received"
              ],
              "x-enumNames": [
                "MESSAGE_RECEIVED"
              ]
            },
            {
              "type": "string",
              "enum": [
                "event"
              ],
              "x-enumNames": [
                "EVENT"
              ]
            },
            {
              "type": "string",
              "enum": [
                "wait_time"
              ],
              "x-enumNames": [
                "WAIT_TIME"
              ]
            },
            {
              "type": "string",
              "enum": [
                "chat_dismissal_warning"
              ],
              "x-enumNames": [
                "CHAT_DISMISSAL_WARNING"
              ]
            },
            {
              "type": "string",
              "enum": [
                "agent_typing"
              ],
              "x-enumNames": [
                "AGENT_TYPING"
              ]
            }
          ]
        }
      },
      "required": [
        "conversationID",
        "message",
        "event"
      ]
    }
  ],
  "components": {
    "schemas": {
      "LiveAgentHandoffProvider": {
        "type": "string",
        "enum": [
          "ujet",
          "genesys",
          "kustomer",
          "dixa",
          "sunshine",
          "custom"
        ],
        "x-enumNames": [
          "UJET",
          "GENESYS",
          "KUSTOMER",
          "DIXA",
          "SUNSHINE",
          "CUSTOM"
        ]
      },
      "LiveAgentHandoffWidgetConfig": {
        "type": "object",
        "properties": {
          "returnToAI": {
            "type": "boolean"
          },
          "disableFileUpload": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

## Custom Handoff connection

<a id="handoff-connection" />

<a id="handoff-connection-what-this-api-connects" />

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

<a id="handoff-connection-conversation-lifecycle" />

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

<a id="handoff-connection-endpoints-and-authentication" />

### Endpoints and authentication

| Method and path | Request | Successful result |
| --- | --- | --- |
| `POST /conversations` | Customer, context, routing and Voiceflow metadata below | JSON with non-empty string `conversationId`; optional `message` |
| `POST /conversations/{id}/messages` | Text or file message | A successful HTTP status |
| `POST /conversations/{id}/end` | `{ "timestamp": "ISO_TIMESTAMP" }` | A successful HTTP status |

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.

<a id="handoff-connection-create-fields" />

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

| Field | Type / presence | Meaning |
| --- | --- | --- |
| `endUser` | object, always | Customer fields below |
| `endUser.externalId` | non-empty string, always | Configured customer ID, falling back to the Voiceflow user ID |
| `endUser.name`, `.email`, `.phone` | string or null, always | Empty/unconfigured values become null |
| `endUser.locale` | string, always | Configured language; fallback `en` |
| `queueId` | string or null, always | Destination your service translates into provider routing |
| `context` | object, always | Context fields below |
| `context.type` | `full`, `custom`, or `none`, always | Selected Handoff context mode |
| `context.summary` | string or null, always | Custom context text; null for Full or None |
| `context.transcript` | array, always | Empty for Custom and None; Full contains conversational messages |
| `context.transcript[].role` | `user` or `assistant` | Message author |
| `context.transcript[].content` | string | Message text |
| `context.transcript[].timestamp` | string or null | Recorded timestamp when present |
| `metadata` | JSON object, always | Resolved configuration metadata, otherwise `{}` |
| `voiceflow` | object, always | Runtime identifiers below |
| `voiceflow.projectId` | string | Project owning this handoff |
| `voiceflow.environmentId` | string or null, always | Resolved project Environment ID when available |
| `voiceflow.sessionId` | string | Runtime user/session identity |
| `voiceflow.transcriptId` | string or null, always | Transcript ID when recording is available |
| `voiceflow.channel` | string or null, always | Runtime interface identifier when available; do not require `webchat` |

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.

<a id="handoff-connection-message-fields" />

#### Message fields

| Field | Type / presence | Meaning |
| --- | --- | --- |
| `type` | `text` or `file`, always | Message variant |
| `id` | string, always | Stable for retries of this outbound call; deduplicate before creating a provider message |
| `timestamp` | ISO date-time string, always | Time Voiceflow constructed the message |
| `text` | string for text; null for file | Customer text |
| `file` | object, file only | One attachment per request |
| `file.url` | URL string | Signed download URL |
| `file.name`, `.contentType` | string | Original filename and MIME type |
| `file.size` | number | File size in bytes |
| `file.expiresAt` | ISO date-time string | One hour after the URL was issued |
| `file.checksumSha256` | null | No checksum is supplied by the current runtime |

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.

<a id="handoff-connection-create-response-and-end-request" />

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

<a id="handoff-connection-example-create-request" />

### Example create request

```json
{
  "endUser": {
    "externalId": "customer-123",
    "name": "Alex",
    "email": "alex@example.com",
    "phone": null,
    "locale": "en"
  },
  "queueId": "support",
  "context": {
    "type": "custom",
    "summary": "Customer needs help with order 123.",
    "transcript": []
  },
  "metadata": {},
  "voiceflow": {
    "projectId": "YOUR_PROJECT_ID",
    "environmentId": "YOUR_ENVIRONMENT_ID",
    "sessionId": "test-user",
    "transcriptId": "YOUR_TRANSCRIPT_ID",
    "channel": "webchat"
  }
}
```

Example response:

```json
{
  "conversationId": "connection-conversation-123",
  "message": "Connecting you to support."
}
```

These are illustrative IDs; use actual values from the request and the persisted mapping.

<a id="handoff-connection-related-guides" />

### Related guides

[Build the connection](/docs/developers/handoff/connect) · [Webhook events](/docs/api-reference/agent-runtime/chat/handoff#handoff-events)

<a id="handoff-connection-errors-and-retry-behavior" />

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

| Error member | Type / requiredness |
| --- | --- |
| `error` | Required object on a structured error |
| `error.code` | Required enum: `invalid_request`, `unauthorized`, `not_found`, `rejected`, `rate_limited`, `internal`, `unavailable` |
| `error.message` | Optional string or null |
| `error.retryAfterSeconds` | Optional positive integer or null; delay in seconds |

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

<a id="handoff-events" />

<a id="handoff-events-what-these-events-do" />

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

<a id="handoff-events-event-envelope-and-payload" />

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

| Type | Additional fields | Meaning |
| --- | --- | --- |
| `agent.joined` | `agent` with required `name`, optional `id` and `avatarUrl`; optional `message` | A human has joined |
| `message.received` | `agent`, non-empty `text` | A customer-visible human reply |
| `file.received` | `agent`, `file.url`; optional text and file name/contentType/size | A human attachment |
| `conversation.ended` | Optional `message` | The human conversation has ended |

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.

<a id="handoff-events-field-types-and-requiredness" />

#### Field types and requiredness

| Field | Type / requiredness |
| --- | --- |
| `projectId` | Required non-empty string |
| `events` | Required array, 1–50 items |
| `events[].id`, `.conversationId`, `.timestamp` | Required non-empty strings; timestamp is passed through by this parser, not validated as an ISO date-time |
| `events[].type` | Required discriminator: one of the four types above |
| `agent` | Required object on joined/message/file events; absent on ended events |
| `agent.name` | Required non-empty string |
| `agent.id` | Optional non-empty string or null |
| `agent.avatarUrl` | Optional valid URL string or null |
| `text` | Required non-empty string for `message.received`; optional string or null for `file.received` |
| `message` | Optional string or null on `agent.joined` and `conversation.ended` |
| `file` | Required object on `file.received` |
| `file.url` | Required valid URL string, retrievable by the customer without vendor credentials |
| `file.name`, `.contentType` | Optional non-empty strings or null |
| `file.size` | Optional positive integer or null, in bytes |

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.

<a id="handoff-events-example-human-reply" />

### Example human reply

```json
{
  "projectId": "YOUR_PROJECT_ID",
  "events": [
    {
      "id": "provider-event-123",
      "conversationId": "YOUR_CONNECTION_CONVERSATION_ID",
      "timestamp": "2026-10-18T12:00:00Z",
      "type": "message.received",
      "agent": {
        "id": "agent-1",
        "name": "Sam"
      },
      "text": "I can help with that order."
    }
  ]
}
```

Replace IDs and timestamp with values from the active conversation. Do not send this historical timestamp as a live signature timestamp.

<a id="handoff-events-sign-deliver-and-retry" />

### 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](/docs/examples/live-agent-handoff/protocol.mjs) 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.

<a id="handoff-events-http-outcomes" />

#### HTTP outcomes

| Status | Meaning / handling |
| --- | --- |
| 200 with `{"success":true}` | Processing completed; not a read receipt. Unknown conversations in a mixed batch can still be skipped |
| 400 | Invalid event envelope/fields, or an unclassified processing failure. Correct the payload; a batch may already have applied earlier events |
| 401 | A known conversation's signature or signing timestamp was rejected |
| 404 | Every non-filtered event named an unknown/inactive conversation. Check project ID, mapping and whether creation has finished |

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.

<a id="handoff-events-related-reference" />

### Related reference

[Connection API](/docs/api-reference/agent-runtime/chat/handoff#handoff-connection) · [Troubleshooting](/docs/documentation/handoff/troubleshooting)
