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.
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.
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.
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, emitclient.startwith project, user, Environment and any saved key. - Check readiness: when
client.startedreportsnewSessionRequired: true, emitsession.create. - Retain the key: save
session.created.sessionKeybefore sending actions. WhennewSessionRequiredisfalse, 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.sendafter 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.startwith the same project, user, Environment choice and savedsessionKey. - Resume: wait for
client.started. WhennewSessionRequiredisfalse, continue the existing session. - Replace when required: when
newSessionRequiredistrue, create a new session and replace the saved key with the one fromsession.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.
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.