Skip to main content

Entity relationships

User (platform user)
  └── belongs to → Organization (many-to-many, with roles)
        └── has many → Chatbot
              ├── has many → Conversation
              │     └── has many → Message
              │           └── has many → AnalysisAnnotation
              ├── has many → Workflow
              │     └── has many → WorkflowRun
              ├── has many → ClientOrganization
              │     └── has many → ClientUser
              ├── has one → AnalysisConfig
              │     ├── MetadataFields[]
              │     ├── UserFlags[]
              │     ├── AssistantBehaviors[]
              │     └── AnalysisPrompts[]
              ├── has many → ApiKey
              ├── has many → Webhook
              └── has many → ChatbotMember

Multi-tenancy

OpenBat has a two-level tenancy model:
LevelEntityDescription
PlatformOrganizationYour team using OpenBat. Contains chatbots, members, settings.
ClientClientOrganization, ClientUserYour customers interacting with the chatbot. Tracked via SDK metadata.
These are separate entities. A platform organization at /platform/members represents your team. Client organizations at /platform/{chatbotId}/organizations represent the end users of your chatbot.

Key entities

Conversation

A conversation represents a single chat session between a user and your chatbot.
FieldDescription
Conversation IDUnique identifier
MessagesArray of user and assistant messages
MetadataCustom fields from SDK (userId, email, plan, mrr, etc.)
SessionBrowser context (page URL, referrer, device, country)
Created / Last messageTimestamps

AnalysisAnnotation

Each message can have multiple annotations produced by the analysis pipeline:
TypeExamples
SentimentScore (-1 to 1), label (“Very Negative”, “Positive”)
Behavior flagsFrustrated User, Churn Risk, Buying Signal
Quality flagsHallucination, premature closure, dodging
ResolutionFully Resolved, Partially Resolved, Unresolved
IntentAsking about pricing, requesting support
TopicsBilling, integration, onboarding

Workflow

FieldDescription
NameDescriptive workflow name
ConditionsAnalysis signals that trigger the workflow
ActionsWhat happens when triggered (webhook call)
StatusActive or inactive

WorkflowRun

FieldDescription
WorkflowParent workflow reference
StatusPending, Triggered, Success, Failed, Skipped
TimestampWhen the run occurred

Revenue tracking

Client entities (ClientOrganization and ClientUser) include revenue fields:
  • MRR — monthly recurring revenue
  • Plan — subscription tier name
These fields are populated from SDK metadata and enable revenue-aware analysis. The analytics dashboard uses MRR data for revenue signals (churn risk on high-MRR accounts, buying signals).

Session tracking

The conversation detail sidebar displays session metadata:
FieldSource
Session IDSDK-generated
Page URLBrowser location where chat occurred
ReferrerPrevious page URL
DeviceDesktop, mobile, tablet
CountryIP-based geolocation

Next steps

Architecture overview

Tech stack, URL structure, and API surface.

Analysis pipeline

How the AI analysis processes conversations.