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

# Sessions

> Manage conversation identity, start a session in an Environment, continue turns and resume a Socket.IO connection.

## Overview

A session holds the conversation state an agent uses across turns. Your application creates a session when a customer starts a conversation, then keeps its `sessionKey` to continue that conversation. Creating a session and sending a message are separate actions.

### Examples of when to use Sessions

Use Sessions to connect your interface to a continuing customer conversation. For example:

- **Handle a multi-turn request:** keep the same session while a customer provides an order number and asks a follow-up question.
- **Choose the agent release:** start a new conversation in a specific [Environment](#choosing-an-environment), or use the project's traffic split.
- **Reconnect a socket client:** [resume a valid session](#resuming-a-session) after a temporary disconnection instead of starting the conversation again.

### User, session and connection

| Concept | What it identifies | How your app uses it |
| --- | --- | --- |
| `userID` | The customer in your integration | Supply your user's identifier when starting or resuming a session. |
| `sessionKey` | An active conversation | Retain it to continue that conversation; treat it as a credential. |
| Socket.IO connection | The current connection to the runtime | Reconnect it when interrupted, then check whether its saved session can resume. |

The [Sessions reference](/docs/api-reference/v4interact/start-session-specific-environment) owns the HTTP request and response fields. The [socket event reference](/docs/api-reference/conversations-api/interact-socket#client-events) owns the connection and session event payloads.

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

### How to use Sessions

Create one session, then reuse it for the conversation's turns.

#### 1. Choose the project and Environment

Obtain your [project ID](/docs/cookbook/find-your-project). Choose a specific [Environment](#choosing-an-environment) or the project's traffic split. REST and Streaming create sessions on your server using a [project API credential](/docs/api-reference/authentication).

#### 2. Start the conversation session

For REST or Streaming, call the [session-creation operation](/docs/api-reference/v4interact/start-session-specific-environment#create-a-session-in-a-specific-environment) and retain the returned `sessionKey`. For Voice, complete the [session handshake](#starting-a-session) and retain the key from `session.created`.

#### 3. Send turns using the same session

[Launch the agent](/docs/api-reference/v4interact/interact-non-stream#send-an-action) once, then send customer messages or other supported actions. Render the [returned traces](/docs/api-reference/trace-types). Continue with the existing session rather than creating one for each message.

<a id="starting-a-session"></a>

## Starting a session

Create a conversation and retain the key that continues it.

Create a session once, then retain its key for the conversation. Creating a new HTTP session ends the previous session for that user in the same project and resolved Environment.

### Chat sessions

Call the [HTTP session-creation operation](/docs/api-reference/v4interact/start-session-specific-environment#http-session-creation) with your project API credential and `userID`. Save the returned `sessionKey` and use it to authenticate later interaction requests. Creation returns JSON even when later actions use SSE. The non-streaming HTTP alternative uses the same creation operation.

### Voice sessions

- **Initialize:** on Socket.IO `connect`, emit [`client.start`](/docs/api-reference/conversations-api/interact-socket#client-start) with project, user, Environment and any saved key.
- **Check readiness:** when [`client.started`](/docs/api-reference/conversations-api/interact-socket#client-started) reports `newSessionRequired: true`, emit [`session.create`](/docs/api-reference/conversations-api/interact-socket#session-create).
- **Retain the key:** save `session.created.sessionKey` before sending actions. When `newSessionRequired` is `false`, the supplied session is already ready.

A browser can omit the project API credential only when the project allows public API access. Private projects require an authorized trusted client; keep secret credentials on your server.

<a id="choosing-an-environment"></a>

## Choosing an Environment

Target one Environment or let the project route new conversations.

Select the Environment when starting a session. An [Environment alias](/docs/documentation/deploy/environments/overview#aliases), such as `main`, identifies the target without using its display name.

| Routing choice | HTTP: REST and Streaming | WebSocket |
| --- | --- | --- |
| **Specific Environment** | Use the [Environment-specific session operation](/docs/api-reference/v4interact/start-session-specific-environment#create-a-session-in-a-specific-environment). | Set `environmentID` on [`client.start`](/docs/api-reference/conversations-api/interact-socket#client-start). |
| **Project traffic split** | Use the [project session operation](/docs/api-reference/v4interact/start-session-specific-environment#create-a-session-using-your-traffic-split). | Omit `environmentID` from `client.start`. |

Traffic-split routing uses the user identifier to assign the Environment consistently. Configure the distribution in [Environments](/docs/documentation/deploy/environments/traffic-split). This selects where a new session runs; an existing session key continues its existing conversation.

<a id="continuing-a-conversation"></a>

## Continuing a conversation

Send each turn to the session you already created.

Keep the user's session key in your application's conversation state. A `userID` alone does not replace the session credential.

- **Chat:** authenticate [interaction requests](/docs/api-reference/v4interact/interact-non-stream#send-an-action) with the returned session key.
- **Voice:** send [`action.send`](/docs/api-reference/conversations-api/interact-socket#action-send) after the session handshake has completed. When reconnecting, pass the saved key again.
- **All transports:** launch once for a new session, then send the customer's later messages as text or another supported action.

### Turn completion and conversation end

Finishing a reply does not end the conversation. REST returns the completed turn as JSON; Streaming finishes delivery with an SSE `end` event; WebSocket reports action completion through `action.status`. Your app can then accept another customer turn.

Handle a [conversation-ending trace](/docs/api-reference/traces/conversation-control#end) separately from turn completion. On WebSocket, [`session.ended`](/docs/api-reference/conversations-api/interact-socket#session-ended) means the session has ended: stop sending actions to it and clear its saved key. A socket `disconnect` alone does not mean the conversation has ended.

<a id="resuming-a-session"></a>

## Resuming a session

Reconnect without replacing a conversation that is still active.

A Socket.IO connection and a conversation session have different lifetimes. After a temporary disconnection:

- **Reconnect:** reconnect the socket, then emit `client.start` with the same project, user, Environment choice and saved `sessionKey`.
- **Resume:** wait for `client.started`. When `newSessionRequired` is `false`, continue the existing session.
- **Replace when required:** when `newSessionRequired` is `true`, create a new session and replace the saved key with the one from `session.created`.

For HTTP, there is no socket handshake to repeat between requests. Continue with the same valid session key. Creating another session starts a new conversation rather than resuming the previous one.

If the connection failed during an action, follow [Chat recovery](/docs/api-reference/agent-runtime/chat/recovery) or [Voice reconnection](/docs/api-reference/conversations-api/interact-socket#reconnect-after-an-interruption) before resending it. Restoring the session does not confirm that the interrupted action completed.

### Create or resume a browser conversation

Register the session listeners before connecting, then reuse the saved key.

This example assumes the project allows public API access. It keeps the key in application memory; pass the saved key again on reconnect. It stops at session readiness—[Sending actions](/docs/api-reference/v4interact/interact-non-stream) covers subsequent turns.

```js title="Session handshake"
import { io } from 'socket.io-client';

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

socket.on('connect', () => {
  socket.emit('client.start', {
    projectID: 'YOUR_PROJECT_ID',
    userID: 'customer-1042',
    environmentID: 'main',
    sessionKey,
  });
});
socket.on('client.started', ({ newSessionRequired }) => {
  if (newSessionRequired) socket.emit('session.create', {});
  // Otherwise the existing session is ready for actions.
});
socket.on('session.created', (session) => {
  sessionKey = session.sessionKey;
  // The new session is ready for actions.
});
socket.on('session.ended', () => {
  sessionKey = undefined;
});
socket.connect();
```

Register these listeners once, outside the `connect` callback, so reconnecting does not add duplicate handlers. Check [`client.started`](/docs/api-reference/conversations-api/interact-socket#client-started) to distinguish a resumed session from one that must be created.
