Skip to content

BRD-001 Persistent Session SDK

BRD – Persistent Chatbot Session Across Website Navigation (SDK-Based)

Product: MachineAvatars
Feature: SDK-Level Chat Session Persistence

1. Background & Problem Statement

  • MachineAvatars is deployed on customer websites via a JavaScript SDK.
  • Currently, when users navigate between internal URLs, the chatbot UI and/or session state may reset.
  • This breaks conversation continuity and negatively impacts user experience and lead conversion.

2. Objective

Ensure that once initialized via the SDK, the chatbot window remains open and the active chat session continues uninterrupted across internal URL changes within the same browser tab.

3. Scope

In-Scope

  • Chatbot UI persists across internal page navigations handled by the SDK.
  • Chat history and conversation context remain intact during navigation.
  • Same Session ID is retained throughout navigation within a single tab.

Out-of-Scope

  • Persistence across browser refresh.
  • Persistence across new tabs, browsers, or devices.
  • Long-term session recovery after session expiry.

4. User Personas

  • End User: Interacts with the chatbot while browsing multiple pages.
  • Customer Admin (Indirect): Embeds SDK and expects consistent chatbot behavior.

5. High-Level User Flow

  1. Customer embeds MachineAvatars SDK on the website.
  2. User opens the chatbot on any page.
  3. SDK initializes a chatbot session and Session ID.
  4. User navigates to another internal URL.
  5. SDK retains chatbot state without reinitialization.
  6. User continues the same conversation seamlessly.

6. Functional Requirements

  • FR-1: SDK shall initialize the chatbot only once per browser tab session.
  • FR-2: SDK shall prevent chatbot UI unmount or re-render on internal URL changes.
  • FR-3: Chat history and conversation context shall persist across navigation.
  • FR-4: SDK shall maintain the same Session ID during internal navigation.
  • FR-5: Backend requests after navigation shall reference the existing Session ID.

7. Constraints & Non-Functional Requirements

  • SDK must not increase page load time perceptibly.
  • Solution must work for both SPA and non-SPA websites.
  • No visual flicker or re-animation during navigation.

8. Acceptance Criteria

  • Given the SDK is installed, when a user opens the chatbot, then a session is initialized once.
  • Given the chatbot is open, when the user navigates to another internal URL, then the chatbot remains open.
  • Given a conversation is ongoing, when navigation occurs, then chat history remains visible.
  • Given a new message is sent after navigation, then it continues the same session context.