Sessions

Session lifecycle

A session tracks the entire interaction from the moment a user sends their first message until the conversation is concluded. The typical lifecycle states include:

Session metadata

Every session collects valuable metadata to help agents (and human operators) provide better support. This can include the user's browser information, geographic location, device type, and custom variables passed securely from your application (e.g., user ID, subscription tier).

Session storage

Messages and metadata within a session are securely stored within your isolated Workspace. Botrelic retains session history to maintain conversational context for multi-turn interactions and to provide analytics on agent performance. You can configure data retention policies to comply with your organization's privacy requirements.

Session timeout

To optimize resources and ensure context remains relevant, sessions automatically expire after a period of inactivity. By default, a session times out after 30 minutes of no user interaction. When a user returns after a timeout, a new session is created.

Example Session Object

When interacting with the Botrelic API, a session object looks like this:

{
  "id": "sess_987654321",
  "workspace_id": "ws_12345",
  "agent_id": "agt_123456789",
  "status": "active",
  "created_at": "2026-03-13T14:30:00Z",
  "last_activity_at": "2026-03-13T14:35:12Z",
  "metadata": {
    "browser": "Chrome",
    "os": "macOS",
    "custom_data": {
      "user_id": "usr_abc123",
      "plan": "enterprise"
    }
  },
  "message_count": 6
}

Next Steps

Learn what happens when an AI agent needs to escalate a session to a human:

• Handoff