Session life cycle

Session lifecycle in websocket API

This documentation explains how sessions are managed through Moveo's websocket API. While sessions can be created and managed through various interfaces, this section focuses on the websocket implementation, which is used by Moveo's web client

and publicly exposed.

In Moveo, a session represents the container for a conversation between a user and an Agent. Sessions are designed to be ephemeral, existing only for the duration of an active conversation.

note

Despite their temporary nature, all session data is automatically stored in analytics for later review.

Session creation and initialization via websocket

When using the websocket API, a session begins its lifecycle through a dedicated websocket event: session:create. During creation, Moveo captures essential user information from the initial context

, which remains accessible throughout the conversation. This context can be used within dialogs, for conditions, webhooks, and other operations. It can also be updated later in the conversation from either the client or server using the session:context:update event.

Upon successful creation, Moveo generates a unique session_id that identifies all subsequent interactions within that session. The response payload also includes a copy of the initial context (with sensitive fields obfuscated for security) and a source object that contains metadata about the integration, such as integration_id and account_id.

Session persistence and recovery in websocket implementation

Although sessions are ephemeral by design, the websocket implementation provides specific mechanisms to handle unexpected disconnections. Moveo preserves the session state server-side for the duration of the session_timeout period, allowing for recovery in the event of network issues or client-side disruptions.

This recovery mechanism enables clients to re-establish the connection while preserving message history and context variables, ensuring a continuous user experience. For details on reconnecting to an existing session, see the connection

documentation.

Session termination through websocket

Sessions created via the websocket API can be terminated in several ways:

• Client-initiated closure via websocket events.
• A resolve action triggered within a dialog flow.
• Manual resolution by a human agent using Moveo Live Chat.

When a session is marked for closure, Moveo initiates a shutdown process that includes:

1. Sending a closure notification to the client.
2. Keeping the session in a recoverable state for a short period in case it needs to be reopened.
3. Final expiration after receiving confirmation from the client.

This staged approach ensures that sessions can be resumed if needed before permanent termination.

Session expiration

Session expiration in Moveo is governed by configurable timeout settings that control different stages of the session lifecycle:

• Session timeout (session_timeout): Defines the absolute maximum duration for a conversation. Once elapsed, a new session must be created.

• Keep alive (keep_alive): Specifies how long a closed or resolved session remains accessible before expiring. This allows for follow-up interactions without creating a new session.

It is important to distinguish between conversation closure and session expiration:

• A closed conversation that hasn't expired can be reopened within the keep_alive window.
• An expired session is permanently removed and cannot be reopened.
• Closure is a change in state, while expiration is a final removal of the session.

For details on configuring these timeout mechanisms, refer to the timeout documentation

.