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, or use the project’s traffic split.
  • Reconnect a socket client: resume a valid session after a temporary disconnection instead of starting the conversation again.

User, session and connection

The Sessions reference owns the HTTP request and response fields. The socket event reference owns the connection and session event payloads.

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. Choose a specific Environment or the project’s traffic split. REST and Streaming create sessions on your server using a project API credential.

2

Start the conversation session

For REST or Streaming, call the session-creation operation and retain the returned sessionKey. For Voice, complete the session handshake and retain the key from session.created.

3

Send turns using the same session

Launch the agent once, then send customer messages or other supported actions. Render the returned traces. Continue with the existing session rather than creating one for each message.

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 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 with project, user, Environment and any saved key.
  • Check readiness: when client.started reports newSessionRequired: true, emit 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.

Choosing an Environment

Target one Environment or let the project route new conversations.

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

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 with the returned session key.
  • Voice: send 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 separately from turn completion. On WebSocket, 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.

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 or Voice reconnection 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 covers subsequent turns.

Session handshake

Register these listeners once, outside the connect callback, so reconnecting does not add duplicate handlers. Check client.started to distinguish a resumed session from one that must be created.

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