HTTP session creation returns a sessionKey for later Chat requests. The creation response is JSON; subsequent actions use HTTP Streaming. The non-streaming HTTP alternative uses the same session operations.

Voice creates or resumes sessions through the Socket.IO handshake.

Credentials

Keep personal and service keys out of browser code. Create a personal key or service key, then check its resource and action permissions. The session key grants access to that conversation; it does not authorize Platform API resource management.

Session identity

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.

Choosing an Environment

Select the Environment when starting a session. An Environment alias, such as main, identifies the target without using its display name.

Traffic-split routing uses the user identifier to assign the Environment consistently. Configure the distribution in Environments. This selects where a new session runs; an existing session key continues its existing conversation.

Continuing a conversation

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

Authenticate each action request with the same session key. Launch once, then send the customer’s subsequent actions to that conversation.

Resuming a session

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 delivery is interrupted, use Errors and recovery before replaying an action.

HTTP session creation

Authenticate creation requests with your project API credential. Use the returned session key, rather than the project credential, for interaction requests.

Creating a new HTTP session ends the previous session for the same user in the same project and resolved Environment. Reuse the existing key to continue that conversation.

Create a session in a specific Environment

Use the Environment’s alias, such as main, to target that Environment.

Endpoint
POST
/v4/project/{projectID}/environment/{environmentID}/session

Authentication

authorization
string
header
required

Voiceflow API key

Path parameters

projectID
string
required

The ID of the target Voiceflow project. You can find it in the settings for your agent.

environmentID
string
required

The alias of the environment to target (ie. main). You can find this in the environments page of your agent.

Request body

userID
string
required

Unique ID for the user. If a session already exists for this user, the existing session will end and a new session will be created with a new session key.

Minimum length: 1 · Maximum length: 256
contact
object

Response

200 - application/json
sessionKey
string
required

A session-scoped authentication key. Pass this as the authorization header when calling the interact endpoints.

Create a session using your traffic split

Omit the Environment from the route to use the project’s configured traffic split.

Endpoint
POST
/v4/project/{projectID}/session

Authentication

authorization
string
header
required

Voiceflow API key

Path parameters

projectID
string
required

The ID of the target Voiceflow project. You can find it in the settings for your agent.

Request body

userID
string
required

Unique ID for the user. If a session already exists for this user, the existing session will end and a new session will be created with a new session key.

Minimum length: 1 · Maximum length: 256
contact
object

Response

200 - application/json
sessionKey
string
required

A session-scoped authentication key. Pass this as the authorization header when calling the interact endpoints.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.