Conversations & Sessions

Conversation Data Model

Conversations are managed across four relational tables: - conversations: The primary conversation record, linked to an organizationId and an optional leadProfileId. - conversation_messages: Individual user and assistant turns with message roles (user, assistant, system), token usage, and latency. - conversation_sessions: Active communication sessions tracking start time, end time, channel type, and status (active, ended, abandoned). - conversation_events: Audit trail of events (e.g., intent_detected, slot_selected, booking_created, escalated).

Thread Lifecycle

1. Initiation: When a message arrives from an external channel or the web widget, the router searches for an active conversation for that sender.
2. Session Window: If the last message was received within the active session timeout window, the message appends to the current thread. Otherwise, a new session is initialized.
3. Completion: When an appointment is finalized or the customer confirms resolution, the conversation state is updated to resolved.

Dual Message Storage

To support both external channel fidelity and AI reasoning, messages are saved in two formats: - channel_messages: Stores raw provider payloads (e.g., Twilio SIP metadata, WhatsApp message IDs, delivery statuses). - conversation_messages: Stores sanitized, normalized text used by the LLM context window.

Context Window Assembly

When assembling the prompt for the AI: - Recent turns (up to the token limit) are fetched in chronological order. - Injected system instructions include: business profile, business hours, services menu, and relevant knowledge chunks retrieved via RAG. - Internal staff notes are excluded from customer-facing context.