Skip to main content

Sessions

In Moveo, conversations between users and an AI Agent

occur within a structure called a session. A session is a temporary container used to store all context needed for an ongoing conversation, including:

  • Context variables
  • User information
  • Metadata

Sessions enable contextual and coherent conversations by persisting data throughout the interaction.

How sessions work​

Each time a user starts a new conversation, Moveo creates a new session. This session remains active throughout the interaction, allowing the AI Agent to maintain continuity and respond meaningfully.

Sessions are automatically closed under the following conditions:

  • The conversation is resolved either through a dialog action or by a human agent.
  • The session expires due to inactivity for a time that may vary depending on the session timeout setting.

Once closed, sessions cannot be reopened unless they are still within a defined grace period (see session timeout).

Although sessions themselves are ephemeral, the conversation history is preserved. This allows you to:

  • Review and audit past conversations.
  • Extract insights from analytics.
  • Improve AI Agent performance over time.

Session life cycle​

The session life cycle describes how sessions are created, maintained, and ultimately closed or expired. This process ensures a balance between maintaining continuity during a conversation and releasing unused resources after it ends.

1. Creation​

Sessions are created automatically when a new conversation is initiated. This typically happens:

  • When a user sends the first message.
  • When a session:create event is received from the websocket API.
  • When a broadcast message is sent to the user.

At creation, the session is initialized with context data and assigned a unique session_id.

2. Active state​

While a conversation is ongoing, the session remains in an active state. During this period:

  • The user can send and receive messages.
  • The context can be updated dynamically.
  • Dialogs and conditions have access to all session context variables.
  • User metadata and preferences are preserved.

3. Closure​

A session can be closed under the following conditions:

  • A resolve action is triggered within a dialog.
  • A human agent manually resolves the conversation and the user doesn't reopen it within the keep-alive period.
  • The client explicitly signals the session should be closed.

Closed sessions transition to a recoverable state for a short time.

4. Grace period (keep-alive)​

After a session is closed, it enters a grace period defined by the keep_alive setting. During this time:

  • The session can be reopened if needed (only if it is not expired).
  • Context and message history are retained.

This allows for short breaks in conversation without losing context.

5. Expiration​

When the session_timeout is reached or the keep_alive period ends, the session is permanently expired. Once expired:

  • The session can no longer be accessed or resumed.
  • A new session must be created for future interactions.

Sessions and the user experience​

Sessions ensure that users receive consistent responses by preserving context across messages. Each session is uniquely identified and can include custom metadata that enriches how conversations are handled and analyzed.

You can monitor active and past sessions through the Analytics section of the platform. While sessions are temporary, the information is stored for future reference and debugging purposes.

For information about how sessions behave specifically in the websocket API, including recovery mechanisms and timeout behavior, see the Session life cycle

documentation.

Last updated on