elevenlabs-webhook-nodejs 1.0.0

package/docs/WHATSAPP_AGENT.md

@@ -0,0 +1,1086 @@
+# WhatsApp AI Agent System — Complete Technical Documentation
+
+> Session-based WhatsApp AI agent that gives humans first chance to respond, then automatically hands off to ElevenLabs AI via real-time WebSocket.
+
+---
+
+## Table of Contents
+
+1. [System Overview](#1-system-overview)
+2. [Architecture](#2-architecture)
+3. [External Dependencies](#3-external-dependencies)
+4. [Database Models](#4-database-models)
+5. [Tenant Configuration](#5-tenant-configuration)
+6. [Session Lifecycle](#6-session-lifecycle)
+7. [Webhook Handler — Unipile](#7-webhook-handler--unipile)
+8. [Agent Service — WhatsAppAgentService](#8-agent-service--whatsappagentservice)
+9. [API Routes](#9-api-routes)
+10. [enrichChat — Backward Compatibility Layer](#10-enrichchat--backward-compatibility-layer)
+11. [Frontend](#11-frontend)
+12. [Blacklist System](#12-blacklist-system)
+13. [Timers, Recovery & Safety Nets](#13-timers-recovery--safety-nets)
+14. [ElevenLabs WebSocket Protocol](#14-elevenlabs-websocket-protocol)
+15. [Migration](#15-migration)
+16. [File Map](#16-file-map)
+17. [Constants & Timeouts](#17-constants--timeouts)
+18. [Decision Tables](#18-decision-tables)
+
+---
+
+## 1. System Overview
+
+The WhatsApp Agent is a fully backend-autonomous AI chat system. It requires **no cron jobs** and **no frontend dependency** to operate. The system:
+
+1. Receives WhatsApp messages via **Unipile** webhooks
+2. Creates a **session** with a configurable **grace period** (default: 180 seconds)
+3. During the grace period, humans can respond first — if they do, the session resolves
+4. If no human responds before the deadline, **ElevenLabs AI** takes over automatically
+5. The AI communicates via a **text-only WebSocket** to ElevenLabs, and sends responses back through **Unipile**
+6. Humans can **take over** from AI at any time, and later **release** back to AI
+
+The entire system is **event-driven**: Unipile webhook triggers processing, in-memory `setTimeout` timers handle grace periods, and the WebSocket connection to ElevenLabs handles AI responses.
+
+---
+
+## 2. Architecture
+
+```
+┌─────────────────┐                              ┌─────────────────┐
+│   WhatsApp      │                              │  ElevenLabs AI  │
+│   (Contact)     │                              │  (Conversational│
+│                 │                              │   Agent)        │
+└────────┬────────┘                              └────────▲────────┘
+         │                                                │
+         │ Messages                          WebSocket (text-only)
+         │                                   getSignedUrl → ws://
+         ▼                                                │
+┌─────────────────┐     POST /webhooks/unipile    ┌───────┴────────┐
+│                 │ ─────────────────────────────▶ │                │
+│   Unipile       │                               │  Fastify API   │
+│   (WhatsApp     │ ◀───────────────────────────  │  (Backend)     │
+│    Bridge)      │     sendMessage(chatId, text)  │                │
+│                 │                               │                │
+└─────────────────┘                               └───────┬────────┘
+                                                          │
+                                                   ┌──────┴──────┐
+                                                   │   MongoDB    │
+                                                   │  - Chats     │
+                                                   │  - Sessions  │
+                                                   │  - Messages  │
+                                                   └─────────────┘
+
+┌─────────────────┐    /api/whatsapp/*
+│  React Frontend │ ──────────────────────────────▶  (same Fastify)
+│  (Dashboard)    │ ◀──────────────────────────────
+└─────────────────┘    enrichChat() adds virtual fields
+```
+
+**Key insight**: The frontend is purely a management dashboard. The AI agent operates entirely on the backend. If the frontend is offline, the agent continues to work normally.
+
+---
+
+## 3. External Dependencies
+
+### 3.1 Unipile — WhatsApp Message Bridge
+
+| Operation | Method | Endpoint | Purpose |
+|-----------|--------|----------|---------|
+| Connect WhatsApp | POST | `/api/v1/accounts` | Returns QR code for phone scan |
+| Reconnect | POST | `/api/v1/accounts/:id/reconnect` | Re-establish dropped connection |
+| Account Status | GET | `/api/v1/accounts/:id` | Check if WhatsApp is connected |
+| Disconnect | DELETE | `/api/v1/accounts/:id` | Remove WhatsApp account |
+| Send Message | POST | `/api/v1/chats/:chatId/messages` | Send text to contact |
+| Register Webhook | POST | `/api/v1/webhooks` | Register URL for incoming messages |
+
+**Auth**: `X-API-KEY` header with `UNIPILE_API_KEY`.
+
+**Webhook payload** (incoming message):
+```typescript
+{
+  account_id: string;       // Which Unipile account received it
+  account_type: 'WHATSAPP';
+  event: 'message_received';
+  chat_id: string;          // Unipile's chat identifier
+  message_id: string;       // Unique message ID
+  message: string;          // Message text content
+  timestamp: string;        // ISO timestamp
+  is_sender: boolean;       // true = sent by us, false = received from contact
+  sender: {
+    attendee_name: string;
+    attendee_provider_id: string;
+    attendee_specifics?: { phone_number?: string };
+  };
+  attendees: [{             // attendees[0] = the contact
+    attendee_name: string;
+    attendee_provider_id: string;
+    attendee_specifics?: { phone_number?: string };
+  }];
+}
+```
+
+### 3.2 ElevenLabs — Conversational AI (Text-Only WebSocket)
+
+**Connection flow**:
+1. Call `elevenlabsService.getSignedUrl({ agentId })` → returns a time-limited signed URL (15min)
+2. Append `?textOnly=true` to the URL
+3. Open a `ws://` WebSocket connection
+4. Wait for `conversation_initiation_metadata` message (contains `conversation_id`)
+5. Send `contextual_update` with conversation history
+6. Send `user_message` with the contact's text
+7. Receive `agent_response` with AI reply text
+
+**WebSocket messages we send**:
+```json
+{ "type": "contextual_update", "text": "Previous conversation history:\nPatient: ...\nOperator: ..." }
+{ "type": "user_message", "text": "Contact's message text" }
+```
+
+**WebSocket messages we receive**:
+```json
+{ "type": "conversation_initiation_metadata", "conversation_initiation_metadata_event": { "conversation_id": "..." } }
+{ "type": "agent_response", "agent_response_event": { "agent_response": "AI reply text" } }
+```
+
+---
+
+## 4. Database Models
+
+### 4.1 WhatsAppChat
+
+**Collection**: `whatsappchats`
+
+Represents a 1:1 WhatsApp conversation between the business and a contact. One chat per contact per tenant. Never deleted, can be closed/reopened.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `tenant_id` | ObjectId → Tenant | required | Tenant ownership |
+| `unipile_chat_id` | String | required | Unipile's unique chat ID |
+| `unipile_account_id` | String | required | Which Unipile account this chat belongs to |
+| `contact_name` | String | `'Bilinmiyor'` | Contact's display name from WhatsApp |
+| `contact_phone` | String | `''` | Contact's phone number (e.g. `+905551234567`) |
+| `is_closed` | Boolean | `false` | Whether the chat has been manually closed |
+| `active_session_id` | ObjectId → WhatsAppSession | `null` | Currently active session (null = no session) |
+| `last_message_at` | Date | `Date.now` | Timestamp of the most recent message |
+| `last_message_preview` | String | `''` | First 100 characters of the last message |
+| `message_count` | Number | `0` | Total messages across all sessions |
+| `createdAt` | Date | auto | |
+| `updatedAt` | Date | auto | |
+
+**Indexes**:
+- `{ tenant_id: 1, last_message_at: -1 }` — List chats sorted by recency
+- `{ unipile_chat_id: 1 }` unique — Fast lookup from webhook
+
+### 4.2 WhatsAppSession
+
+**Collection**: `whatsappsessions`
+
+Represents one conversation "turn" within a chat. A chat can have many sessions over its lifetime. Each session tracks the grace period, AI connection, and human takeover state.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `chat_id` | ObjectId → WhatsAppChat | required | Parent chat |
+| `tenant_id` | ObjectId → Tenant | required | Tenant ownership |
+| `status` | `'waiting'` \| `'active'` \| `'resolved'` | `'waiting'` | Current lifecycle state |
+| `resolved_by` | `'human'` \| `'ai_timeout'` \| `'manual'` \| `'timeout'` \| `null` | `null` | How the session ended |
+| `started_at` | Date | `Date.now` | When this session was created |
+| `resolved_at` | Date \| null | `null` | When this session ended |
+| `grace_deadline` | Date \| null | `null` | When AI will take over if human doesn't respond |
+| `taken_over_by` | ObjectId → User \| null | `null` | User who took over (via dashboard UI) |
+| `taken_over_at` | Date \| null | `null` | When takeover happened (by UI or WhatsApp reply) |
+| `elevenlabs_conversation_id` | String \| null | `null` | Active ElevenLabs conversation ID |
+| `elevenlabs_conversation_created_at` | Date \| null | `null` | When EL conversation was established |
+| `elevenlabs_last_interaction_at` | Date \| null | `null` | Last message sent to/from ElevenLabs |
+| `message_count` | Number | `0` | Messages within this session |
+| `createdAt` | Date | auto | |
+| `updatedAt` | Date | auto | |
+
+**Indexes**:
+- `{ chat_id: 1, status: 1 }` — Find active session for a chat
+- `{ status: 1, grace_deadline: 1 }` — Stuck session sweeper query
+- `{ tenant_id: 1, status: 1 }` — Stats queries (count waiting/active sessions)
+
+**Status meanings**:
+| Status | Meaning | Who is handling? |
+|--------|---------|-----------------|
+| `waiting` | Grace period running, messages are being buffered | Nobody yet — waiting for human or timer |
+| `active` + no takeover | AI has taken over, ElevenLabs WebSocket active | AI |
+| `active` + `taken_over_by` set | Human claimed via dashboard "Devral" button | Human (via dashboard) |
+| `active` + `taken_over_at` set (no `taken_over_by`) | Human replied directly in WhatsApp app | Human (via WhatsApp) |
+| `resolved` | Session ended | Nobody — chat is idle |
+
+**resolved_by meanings**:
+| Value | Trigger |
+|-------|---------|
+| `'human'` | A self-sent message arrived while session was `waiting` |
+| `'ai_timeout'` | Grace period expired but no agent configured (unused currently) |
+| `'manual'` | User clicked "Close" or "Takeover" then "Close" in dashboard |
+| `'timeout'` | Session had no activity for 30 minutes and was auto-resolved by the inactivity sweeper |
+
+### 4.3 WhatsAppMessage
+
+**Collection**: `whatsappmessages`
+
+Every message exchanged in a WhatsApp chat. Messages from all three parties (contact, AI, human operator) are stored here.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `chat_id` | ObjectId → WhatsAppChat | required | Parent chat |
+| `session_id` | ObjectId → WhatsAppSession \| null | `null` | Which session this belongs to (null = blacklisted/legacy) |
+| `tenant_id` | ObjectId → Tenant | required | Tenant ownership |
+| `unipile_message_id` | String \| null | `null` | Unipile's message ID (for dedup of self-sent messages) |
+| `sender` | `'contact'` \| `'ai'` \| `'human'` | required | Who sent this message |
+| `sender_name` | String | `''` | Display name (contact name, `'AI'`, user ID, or `'WhatsApp'`) |
+| `text` | String | required | Message content |
+| `sent_via_unipile` | Boolean | `false` | `true` if we sent this through Unipile API |
+| `createdAt` | Date | auto | |
+
+**Indexes**:
+- `{ chat_id: 1, createdAt: 1 }` — Load chat messages chronologically
+- `{ session_id: 1, createdAt: 1 }` — Session-scoped queries (context building, replay)
+
+**sender field explanation**:
+| `sender` value | Origin | `sender_name` | `sent_via_unipile` |
+|---------------|--------|---------------|---------------------|
+| `'contact'` | Incoming from WhatsApp user | Contact's name | `false` |
+| `'human'` + sender_name=`'AI'` | AI response sent through Unipile | `'AI'` | `true` |
+| `'human'` + sender_name=userId | Manual message from dashboard | User's ID | `true` |
+| `'human'` + sender_name=`'WhatsApp'` | Self-sent from WhatsApp app directly | `'WhatsApp'` | `false` |
+
+> Note: AI messages use `sender: 'human'` (not `'ai'`) because from WhatsApp's perspective they appear as messages from the business number. The `sender_name: 'AI'` distinguishes them.
+
+---
+
+## 5. Tenant Configuration
+
+WhatsApp agent settings are stored in `Tenant.settings.whatsapp_agent`:
+
+```typescript
+{
+  unipile_account_id: string | null;     // Linked Unipile account
+  unipile_account_status: string | null;  // 'ok', 'pending', 'error', etc.
+  agent_id: ObjectId → Agent | null;     // Reference to Agent model (ElevenLabs ID resolved through Agent record)
+  connected_at: Date | null;              // When WhatsApp was connected
+  connected_phone: string | null;         // The connected WhatsApp phone number
+  grace_period_seconds: number;           // Default: 180 (3 minutes)
+  blacklisted_numbers: string[];          // Numbers excluded from AI
+}
+```
+
+**Agent resolution**: The tenant no longer stores a raw ElevenLabs agent ID string. Instead, `agent_id` is an ObjectId reference to the `Agent` model. When an ElevenLabs agent ID is needed (e.g. for WebSocket connection), it is resolved via `resolveAgentId(agentId)` which fetches the Agent document, checks `is_active`, and returns the ElevenLabs ID. If the agent is inactive or not found, AI handoff is skipped.
+
+**Feature flag**: The tenant must have `'whatsapp_agent'` in `enabled_features[]` for all `/whatsapp/*` routes to work. Checked via `requireFeature('whatsapp_agent')` middleware.
+
+**Grace period range**: Clamped to 30–1800 seconds (30s min, 30min max) in the config endpoint.
+
+---
+
+## 6. Session Lifecycle
+
+### 6.1 Complete State Machine
+
+```
+                     Contact sends message
+                              │
+                              ▼
+                  ┌───────────────────────┐
+                  │   Create Session      │
+                  │   status = 'waiting'  │
+                  │   grace_deadline =    │
+                  │     now + 180s        │
+                  └───────────┬───────────┘
+                              │
+          ┌───────────────────┼───────────────────┐
+          │                   │                   │
+   Human replies       Grace period        Dashboard user
+   in WhatsApp          expires            clicks "Devral"
+          │                   │                   │
+          ▼                   ▼                   ▼
+   ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐
+   │  RESOLVED    │  │  ACTIVE      │  │  ACTIVE          │
+   │  resolved_by │  │  (AI mode)   │  │  (Human mode)    │
+   │  = 'human'   │  │  no takeover │  │  taken_over_by   │
+   └──────────────┘  │  fields set  │  │  = userId        │
+                     └──────┬───────┘  └──────┬───────────┘
+                            │                 │
+                     Contact sends      Dashboard user
+                     more messages      clicks "AI'ya Birak"
+                            │                 │
+                            ▼                 ▼
+                     AI responds via    ┌──────────────────┐
+                     EL WebSocket →     │ Release dialog:  │
+                     Unipile sends      │ 1. "Hemen Yanit" │
+                     to WhatsApp        │ 2. "Mesaj Bekle" │
+                            │           └──────┬───────────┘
+                            │                  │
+                     ┌──────┴──────┐    ┌──────┴──────┐
+                     │ Human       │    │ immediate   │
+                     │ replies in  │    │ = true      │
+                     │ WhatsApp    │    │             │
+                     │ (is_sender) │    │ Replay      │
+                     └──────┬──────┘    │ pending     │
+                            │           │ messages    │
+                            ▼           └─────────────┘
+                     ┌──────────────┐
+                     │ taken_over_at│
+                     │ = now        │
+                     │ EL WS closed │
+                     └──────────────┘
+                            │
+                    (stays active until
+                     "Close" or new contact
+                     message creates new
+                     session after resolve)
+
+        ─── Any state ───
+              │
+        "Close" button
+              │
+              ▼
+       ┌──────────────┐
+       │  RESOLVED     │
+       │  resolved_by  │
+       │  = 'manual'   │
+       │  chat.is_     │
+       │  closed=true  │
+       └──────────────┘
+              │
+        "Yeniden Ac" button
+              │
+              ▼
+       chat.is_closed = false
+       (no new session until
+        contact sends message)
+```
+
+### 6.2 Session Boundaries
+
+A new session is created when:
+1. **First-ever message** from a new contact (new chat + new session)
+2. **Contact message arrives** and chat has **no active session** (previous session was resolved)
+3. **Contact message arrives** and chat was **closed** (`is_closed = true` → flipped to `false`, new session created)
+
+A session ends (resolves) when:
+1. **Human responds** during grace period (via WhatsApp or dashboard send) → `resolved_by = 'human'`
+2. **User clicks "Close"** in dashboard → `resolved_by = 'manual'`
+3. **Grace period expires** but no ElevenLabs agent is configured → `resolved_by = 'manual'`
+4. **No activity for 30 minutes** on an active session → `resolved_by = 'timeout'` (auto-resolved by inactivity sweeper)
+
+A session does **NOT** end when:
+- AI takes over (transitions to `active`)
+- Human takes over via dashboard (stays `active`, `taken_over_by` set)
+- Human replies directly in WhatsApp during AI mode (stays `active`, `taken_over_at` set)
+- User releases back to AI (stays `active`, takeover fields cleared)
+
+---
+
+## 7. Webhook Handler — Unipile
+
+**File**: `src/modules/webhooks/unipile.routes.ts`
+
+**Endpoint**: `POST /webhooks/unipile`
+
+**Auth**: Optional shared secret via `x-unipile-secret` header.
+
+**Response**: Always returns `200 { status: 'received' }` immediately. Processing happens asynchronously.
+
+### 7.1 Pre-Processing Filters
+
+Messages are discarded (not stored) if:
+1. `event !== 'message_received'`
+2. `account_type !== 'WHATSAPP'`
+3. `message` is empty or whitespace
+4. No tenant found for the `account_id` with `whatsapp_agent` feature enabled
+5. Contact phone is not a valid phone number (filters out group chats)
+
+Valid phone regex: `/^\+?\d{10,15}$/` (after stripping spaces, hyphens, parens)
+
+### 7.2 New Chat Flow
+
+When `unipile_chat_id` doesn't match any existing `WhatsAppChat`:
+
+1. Create `WhatsAppChat` document
+2. If contact is **blacklisted**: store message with `session_id: null`, return (no session)
+3. Create `WhatsAppSession` (status=`waiting`, `grace_deadline`=now + grace period)
+4. Set `chat.active_session_id` = new session ID
+5. Store `WhatsAppMessage` with `session_id` = new session
+6. Call `whatsappAgentService.startSession()` to begin grace period timer
+
+### 7.3 Self-Sent Message Flow (`is_sender = true`)
+
+When the webhook reports a message sent by the business (not received from contact):
+
+1. Look up active session via `chat.active_session_id`
+2. If session is `waiting` → **resolve as human** (cancel timer, `resolved_by = 'human'`). The session ID is preserved before resolution.
+3. Check if message already exists in DB (dedup by `unipile_message_id`) — if sent via our API, it's already stored
+4. Store the message with `session_id` of the resolved session (if just resolved) or the current active session (or `null` if no session)
+5. If session is `active` with no takeover (AI was responding) → set `taken_over_at = now`, close ElevenLabs WebSocket
+
+This handles the case where a human operator replies directly in WhatsApp (not through the dashboard), automatically switching from AI to human mode.
+
+### 7.4 Incoming Contact Message Flow (`is_sender = false`)
+
+When a contact sends a message:
+
+1. **Blacklisted**: Store with `session_id: null`, no session/AI activity. If chat was closed, reopen it.
+2. **Session is `waiting`**: Store message with `session_id`. Timer is still running. Multiple messages accumulate.
+3. **Session is `active`**: Forward to `whatsappAgentService.handleIncomingMessage()` which stores the message and triggers AI (unless human-taken).
+4. **No active session**: Create new session → store message → start grace period timer (same as new chat flow, but for existing chat)
+
+---
+
+## 8. Agent Service — WhatsAppAgentService
+
+**File**: `src/services/whatsapp-agent.service.ts`
+
+**Singleton**: `const whatsappAgentService = new WhatsAppAgentService()` exported as default.
+
+**State**: Three in-memory `Map` structures:
+- `connections: Map<unipileChatId, ActiveConnection>` — Active ElevenLabs WebSocket connections
+- `sessionTimers: Map<sessionId, NodeJS.Timeout>` — Grace period timers
+- `messageBufferTimers: Map<sessionId, NodeJS.Timeout>` — 20-second message buffer debounce timers
+
+### 8.1 ActiveConnection Interface
+
+```typescript
+interface ActiveConnection {
+  ws: WebSocket;                    // ElevenLabs WebSocket
+  chatId: string;                   // MongoDB chat._id
+  sessionId: string;                // MongoDB session._id
+  unipileChatId: string;            // Unipile chat identifier
+  agentId: string;                  // ElevenLabs agent ID
+  lastActivity: number;             // Date.now() of last activity
+  conversationId: string | null;    // ElevenLabs conversation ID
+  ready: boolean;                   // true after init metadata received
+  suppressFirstResponse: boolean;   // Suppresses agent greeting
+  reconnectAttempts: number;        // Number of reconnect attempts so far (0 initially)
+  intentionallyClosed: boolean;     // true when WS was closed on purpose (takeover, close, etc.)
+}
+```
+
+### 8.2 Public Methods
+
+#### `initialize()`
+Called on server startup. Sets up:
+- Idle connection cleanup interval (every 60s)
+- Stuck session sweeper interval (every 5min)
+- Inactive session sweeper interval (every 5min) — auto-resolves sessions idle for 30min
+- Recovers `waiting` sessions from DB (restarts timers or fires expired ones)
+
+#### `startSession({ session, gracePeriodSeconds, agentId, tenantId })`
+Creates an in-memory `setTimeout` for the grace period. When it fires, calls `onGracePeriodExpired()`.
+
+#### `cancelSession(sessionId: string)`
+Clears the in-memory timer for the given session.
+
+#### `resolveSessionAsHuman(session: IWhatsAppSession)`
+Cancels timer, sets session status to `resolved` with `resolved_by = 'human'`, clears `chat.active_session_id`.
+
+#### `replayPendingMessages({ tenantId, agentId, session })`
+Finds all `contact` messages in the session (by `session_id`), combines their text with newlines, and sends to AI as a single `user_message`. Used by:
+- Grace period expiry (replay all buffered messages)
+- "Hemen Yanit Ver" release option (replay messages accumulated during human takeover)
+
+Returns `{ pendingCount: number }`.
+
+#### `handleIncomingMessage({ tenantId, agentId, chat, session, messageText, senderName, unipileMessageId })`
+Stores the incoming message, updates chat/session metadata, then:
+- If session has `taken_over_by` or no `agentId` → skip AI response
+- Otherwise → starts/resets a **20-second message buffer timer**. Messages are NOT sent to ElevenLabs immediately. Each new contact message resets the 20s timer. When the buffer expires, all unanswered messages since the last AI response are combined and sent as a single `user_message`. This prevents the AI from responding to each rapid-fire message separately.
+
+#### `closeConnection(unipileChatId: string)`
+Closes the ElevenLabs WebSocket for a chat and removes it from the connections map.
+
+#### `getActiveConnectionCount(): number`
+Returns the number of active ElevenLabs WebSocket connections.
+
+#### `shutdown()`
+Cleans up all timers, intervals, and WebSocket connections. Called on graceful server shutdown.
+
+### 8.3 Private Methods
+
+#### `onGracePeriodExpired(sessionId, agentId, tenantId)`
+1. Fetch session from DB
+2. If session is no longer `waiting` (e.g. human already responded) → return
+3. If no `agentId` configured → resolve session as `manual`
+4. Otherwise → set session status to `active`, call `replayPendingMessages()`
+
+#### `recoverSessions()`
+On startup, finds all sessions with `status: 'waiting'` in DB:
+- If `grace_deadline` has already passed → immediately fire `onGracePeriodExpired`
+- If `grace_deadline` is in the future → create a new `setTimeout` with remaining time
+
+This handles server restarts without losing any sessions.
+
+#### `sweepStuckSessions()`
+Every 5 minutes, finds sessions where:
+- `status: 'waiting'`
+- `grace_deadline < now`
+- No in-memory timer exists
+
+For each stuck session, fires `onGracePeriodExpired`. This is a safety net for edge cases like timer GC or memory leaks.
+
+#### `sweepInactiveSessions()`
+Every 5 minutes, finds `active` sessions where no message activity has occurred for 30 minutes (`SESSION_INACTIVITY_TIMEOUT_MS`). For each inactive session:
+1. Resolves the session with `resolved_by: 'timeout'`
+2. Closes any active ElevenLabs WebSocket connection
+3. Clears `chat.active_session_id`
+4. Cancels any pending message buffer timer
+
+This prevents abandoned sessions from lingering indefinitely.
+
+#### `attemptReconnect(connection: ActiveConnection)`
+Called when an ElevenLabs WebSocket closes unexpectedly (close code !== 1000) and `intentionallyClosed` is `false`. Uses exponential backoff:
+- Attempt 1: 1.5s delay
+- Attempt 2: 3s delay
+- Attempt 3: 6s delay
+- Max attempts: 3 (`MAX_RECONNECT_ATTEMPTS`)
+
+On each attempt, creates a new WebSocket connection and replaces the old one in the connections map. If all attempts fail, the connection is removed.
+
+#### `onMessageBufferExpired(sessionId: string)`
+Fired when the 20-second message buffer timer expires. Collects all unanswered `contact` messages since the last AI response in the session, combines their text with newlines, and sends them as a single `user_message` to the ElevenLabs WebSocket. Removes the timer from `messageBufferTimers`.
+
+#### `cancelMessageBuffer(sessionId: string)`
+Cancels a pending message buffer timer for the given session, if one exists. Called during session resolution, takeover, and close operations.
+
+#### `triggerAiResponse({ tenantId, agentId, chat, session, messageText })`
+1. Check if an alive WebSocket connection exists for this chat
+2. If not → create new connection via `createConnection()`
+3. Update `elevenlabs_last_interaction_at` on session
+4. If new connection → send chat context first
+5. Send `user_message` with the message text
+
+#### `handleIncomingMessage(...)` [internal AI trigger]
+Same as `triggerAiResponse` but also checks `shouldStartNewConversation()` for conversation timeout.
+
+#### `shouldStartNewConversation(session): boolean`
+Returns `true` if:
+- No `elevenlabs_conversation_id` on session
+- No `elevenlabs_last_interaction_at`
+- Last interaction was > 30 minutes ago
+
+#### `createConnection(agentId, chat, session): Promise<ActiveConnection>`
+1. Get signed URL from ElevenLabs
+2. Open WebSocket with `?textOnly=true`
+3. Wait up to 15 seconds for `conversation_initiation_metadata`
+4. Store `conversation_id` on session in DB
+5. Set up persistent `agent_response` handler:
+   - First response is **suppressed** (it's the agent greeting)
+   - Subsequent responses → `sendResponse()` → Unipile → WhatsApp
+6. Return the `ActiveConnection` object
+
+#### `sendResponse(chat, session, text)`
+1. Send message via Unipile API
+2. Store as `WhatsAppMessage` with `sender: 'human'`, `sender_name: 'AI'`, `sent_via_unipile: true`
+3. Update chat and session atomically using `$inc` for `message_count` and `$set` for `last_message_at`/`last_message_preview` (prevents stale document overwrites from WebSocket closure captures)
+
+#### `buildChatContext(sessionId): string | null`
+Fetches last 20 messages in the session, formats as:
+```
+Previous conversation history:
+Patient: ...
+Operator: ...
+Patient: ...
+```
+Sent to ElevenLabs via `contextual_update` message type so the AI has conversation context.
+
+#### `cleanupIdle()`
+Every 60 seconds, closes WebSocket connections where `lastActivity` is > 10 minutes old.
+
+### 8.4 Standalone Helpers
+
+#### `resolveAgentId(agentId: string): Promise<string | null>`
+Takes an Agent model ObjectId, fetches the Agent document from MongoDB, checks `is_active`, and returns the ElevenLabs agent ID string. Returns `null` if the agent is not found or is inactive. Used throughout the service wherever an ElevenLabs agent ID is needed (grace period expiry, AI trigger, replay).
+
+---
+
+## 9. API Routes
+
+**File**: `src/modules/whatsapp/whatsapp.routes.ts`
+
+**Prefix**: `/whatsapp`
+
+**Auth**: All routes require JWT authentication + `whatsapp_agent` feature flag.
+
+### 9.1 Connection Management
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| POST | `/connect` | admin | Creates Unipile WhatsApp account (returns QR code). Tries reconnect first. Migrates chats if account ID changes. |
+| GET | `/connection-status` | any | Checks Unipile account status. Returns `{ connected, status, phone, agent_id, grace_period_seconds }`. |
+| POST | `/disconnect` | admin | Disconnects Unipile account, clears tenant settings. |
+| PUT | `/config` | admin | Updates `agent_id` (ObjectId reference to Agent model) and/or `grace_period_seconds`. Grace period clamped to 30–1800s. |
+| POST | `/register-webhook` | admin | Registers a webhook URL with Unipile. |
+| GET | `/agents` | any | Lists the tenant's agents for agent selection dropdown. Returns `[{ _id, name, is_active }]`. |
+
+### 9.2 Blacklist Management
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| GET | `/blacklist` | admin, manager | Get blacklisted phone numbers. |
+| POST | `/blacklist` | admin, manager | Add phone number. Body: `{ phone }`. |
+| DELETE | `/blacklist/:phone` | admin, manager | Remove phone number from blacklist. |
+
+### 9.3 Statistics
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| GET | `/stats` | any | Returns `{ totalChats, aiChats, humanChats, closedChats, waitingChats, totalMessages }`. |
+
+Stats derivation:
+- `totalChats` = all chats for tenant
+- `closedChats` = chats with `is_closed: true`
+- `waitingChats` = sessions with `status: 'waiting'`
+- `humanChats` = sessions with active takeover + waiting sessions
+- `aiChats` = active sessions without takeover
+
+### 9.4 Chat Management
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| GET | `/chats` | any | Paginated list. Query: `page`, `limit`, `mode` (ai/human/closed). Uses aggregation pipeline for mode filtering. All chats enriched via `enrichChat()`. |
+| GET | `/chats/:chatId` | any | Single chat detail, enriched. |
+| GET | `/chats/:chatId/messages` | any | Paginated messages. Query: `page`, `limit`. Max 200 per page. |
+| GET | `/chats/:chatId/sessions` | any | Paginated session history for a chat. Query: `page`, `limit`. Returns sessions sorted by `started_at` descending. |
+
+### 9.5 Chat Actions
+
+| Method | Path | Role | Body | Description |
+|--------|------|------|------|-------------|
+| POST | `/chats/:chatId/takeover` | admin, manager | — | Human takes over. Cancels grace timer if waiting, closes EL WebSocket, sets `taken_over_by` to current user. |
+| POST | `/chats/:chatId/release` | admin, manager | `{ immediate?: boolean }` | Releases to AI. Clears takeover fields, resets EL conversation fields. If `immediate: true`, replays pending messages immediately. |
+| POST | `/chats/:chatId/close` | admin, manager | — | Closes chat. Resolves active session (manual), closes EL WebSocket, sets `is_closed: true`. |
+| POST | `/chats/:chatId/reopen` | admin, manager | — | Reopens chat. Sets `is_closed: false`. No new session until contact sends a message. |
+| POST | `/chats/:chatId/send` | admin, manager | `{ text }` | Sends manual message via Unipile. Only works in human mode. If session is `waiting`, resolves it as human (cancels grace timer). Stores message with `session_id`. |
+
+---
+
+## 10. enrichChat — Backward Compatibility Layer
+
+**File**: `src/modules/whatsapp/whatsapp.routes.ts` (top-level function)
+
+The database stores `is_closed` and `active_session_id` on the chat, and all session state on `WhatsAppSession`. But the frontend expects flat fields like `mode`, `session_status`, `taken_over_by`.
+
+`enrichChat()` looks up the active session and derives virtual fields:
+
+| DB State | Derived `mode` | Derived `session_status` |
+|----------|----------------|--------------------------|
+| No active session + `is_closed: false` | `'ai'` | `'idle'` |
+| No active session + `is_closed: true` | `'closed'` | `'idle'` |
+| Session status `'waiting'` | `'human'` | `'waiting'` |
+| Session status `'active'` + taken over | `'human'` | `'idle'` |
+| Session status `'active'` + no takeover | `'ai'` | `'idle'` |
+
+Also populates: `taken_over_by` (populated with `name`, `email`), `taken_over_at`, `session_started_at`, `session_grace_deadline`, `session_resolved_by`.
+
+Removes internal fields: `active_session_id`, `is_closed`. Also removes aggregation pipeline temporary fields (`_session`, `_activeSession`, `_mode`) when present from mode-filtered queries.
+
+For the `/chats` list endpoint with mode filtering, a MongoDB aggregation pipeline with `$lookup` and `$switch` replicates this logic at the database level.
+
+---
+
+## 11. Frontend
+
+### 11.1 Layout Overview
+
+The WhatsApp frontend uses a **two-panel WhatsApp Web-style layout**. Both `/whatsapp` and `/whatsapp/:chatId` render the same root component (`WhatsApp.tsx`). The old `WhatsAppChat.tsx` page has been deleted.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Left Panel (ChatList)          │  Right Panel (Detail)  │
+│                                 │                        │
+│  ┌─ StatsBar ─────────────────┐ │  ┌─ ChatHeader ──────┐ │
+│  │ Total | AI | Human | Wait  │ │  │ Name, phone, mode │ │
+│  └────────────────────────────┘ │  │ Actions            │ │
+│  ┌─ ModeFilter ───────────────┐ │  └────────────────────┘ │
+│  │ All / AI / Human / Closed  │ │  ┌─ Tabs ─────────────┐ │
+│  └────────────────────────────┘ │  │ Mesajlar | Oturum   │ │
+│  ┌─ SearchBar ────────────────┐ │  │ Gecmisi             │ │
+│  │ 🔍 Search contacts...      │ │  └────────────────────┘ │
+│  └────────────────────────────┘ │  ┌─ MessageList ──────┐ │
+│  ┌─ ChatListItem ─────────────┐ │  │ Session dividers   │ │
+│  │ Contact name, preview,     │ │  │ Message bubbles    │ │
+│  │ time, mode badge           │ │  │ (color-coded)      │ │
+│  ├────────────────────────────┤ │  └────────────────────┘ │
+│  │ ChatListItem...            │ │  ┌─ MessageInput ─────┐ │
+│  │ ChatListItem...            │ │  │ Text input + send   │ │
+│  └────────────────────────────┘ │  └────────────────────┘ │
+│                                 │                        │
+│  ⚙️ Settings button → Dialog    │                        │
+└──────────────────────────────────────────────────────────┘
+```
+
+**Left panel**: Chat list with stats bar, mode filter (All/AI/Human/Closed), search bar, and scrollable chat list items. Settings (connection, agent selection, grace period, blacklist) are accessed via a settings dialog.
+
+**Right panel**: Selected chat detail with a header showing contact info and action buttons, tabbed content (Mesajlar for messages, Oturum Gecmisi for session history), message stream with session dividers, and a message input bar.
+
+### 11.2 Components (`web/src/components/whatsapp/`)
+
+10 new components power the two-panel layout:
+
+| Component | Purpose |
+|-----------|---------|
+| `ChatList.tsx` | Left panel container: stats bar, filters, search, scrollable chat items |
+| `ChatListItem.tsx` | Single chat row: contact name, preview, timestamp, mode badge |
+| `ChatHeader.tsx` | Right panel header: contact info, mode badge, action buttons (Takeover/Release/Close/Reopen) |
+| `MessageList.tsx` | Scrollable message stream with session dividers between sessions |
+| `MessageBubble.tsx` | Single message bubble, color-coded by sender (gray=contact, green=AI, blue=human) |
+| `MessageInput.tsx` | Text input bar with send button (only active in human mode) |
+| `SessionDivider.tsx` | Visual separator between sessions in the message stream |
+| `SessionHistory.tsx` | "Oturum Gecmisi" tab: paginated session list with status, duration, resolved_by |
+| `StatsBar.tsx` | Compact stats row: Total, AI Active, Human Active, Waiting, Closed |
+| `SettingsDialog.tsx` | Dialog for connection management, agent selection dropdown, grace period, blacklist |
+
+### 11.3 Routing
+
+Both routes render the same component:
+- `/whatsapp` — shows left panel only (or left + empty right panel on wide screens)
+- `/whatsapp/:chatId` — shows left panel + right panel with selected chat
+
+### 11.4 Frontend Types (`web/src/types/index.ts`)
+
+```typescript
+export type ChatMode = 'ai' | 'human' | 'closed';
+export type MessageSender = 'contact' | 'ai' | 'human';
+export type SessionStatus = 'idle' | 'waiting' | 'resolved';
+
+export interface WhatsAppChat {
+  _id: string;
+  tenant_id: string;
+  unipile_chat_id: string;
+  contact_name: string;
+  contact_phone: string;
+  mode: ChatMode;                                          // Derived by enrichChat()
+  taken_over_by: { _id: string; name: string; email: string } | null;
+  taken_over_at: string | null;
+  last_message_at: string;
+  last_message_preview: string;
+  message_count: number;
+  session_status: SessionStatus;                           // Derived by enrichChat()
+  session_started_at: string | null;
+  session_grace_deadline: string | null;
+  session_resolved_by: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WhatsAppMessage {
+  _id: string;
+  chat_id: string;
+  session_id: string | null;       // Which session this message belongs to
+  sender: MessageSender;
+  sender_name: string;
+  text: string;
+  sent_via_unipile: boolean;
+  createdAt: string;
+}
+
+export interface WhatsAppSession {
+  _id: string;
+  chat_id: string;
+  tenant_id: string;
+  status: 'waiting' | 'active' | 'resolved';
+  resolved_by: 'human' | 'ai_timeout' | 'manual' | 'timeout' | null;
+  started_at: string;
+  resolved_at: string | null;
+  grace_deadline: string | null;
+  taken_over_by: string | null;
+  taken_over_at: string | null;
+  message_count: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WhatsAppAgentSettings {
+  agent_id: string | null;          // ObjectId reference to Agent model
+  grace_period_seconds: number;
+  // ... other fields
+}
+
+export interface WhatsAppStats {
+  totalChats: number;
+  aiChats: number;
+  humanChats: number;
+  closedChats: number;
+  waitingChats: number;
+  totalMessages: number;
+}
+```
+
+### 11.5 Status Badges (`web/src/components/status-badge.tsx`)
+
+- **ChatModeBadge**: `ai` → green "AI", `human` → amber "Insan", `closed` → gray "Kapali"
+- **SessionStatusBadge**: Only renders for `'waiting'` → blue "Bekleniyor". Returns `null` for all other values.
+
+---
+
+## 12. Blacklist System
+
+Blacklisted numbers are stored in `Tenant.settings.whatsapp_agent.blacklisted_numbers[]`.
+
+**Behavior for blacklisted contacts**:
+1. Messages are **always stored** in DB (for audit/visibility)
+2. Messages have `session_id: null` — no session is ever created
+3. No grace period timer, no AI response
+4. Chat appears in the dashboard, but in a passive state
+5. If a blacklisted chat was closed, incoming messages reopen it (`is_closed = false`)
+6. Blacklist is checked by exact phone number match
+
+**Management**:
+- Can be managed via API (`GET/POST/DELETE /whatsapp/blacklist`)
+- Can be managed from the chat list UI (ban icon per row)
+- No limit on number of blacklisted numbers
+
+---
+
+## 13. Timers, Recovery & Safety Nets
+
+### 13.1 In-Memory Timers
+
+| Timer | Interval | Purpose |
+|-------|----------|---------|
+| Grace period timer | Per session (e.g. 180s) | Fires `onGracePeriodExpired()` when human doesn't respond |
+| Message buffer timer | 20 seconds (per session, resets on each new message) | Debounces rapid-fire contact messages before sending to AI |
+| Idle cleanup | Every 60 seconds | Closes EL WebSocket connections idle > 10 minutes |
+| Stuck session sweep | Every 5 minutes | Finds sessions stuck in `waiting` past deadline with no timer |
+| Inactive session sweep | Every 5 minutes | Auto-resolves `active` sessions with no activity for 30 minutes (`resolved_by: 'timeout'`) |
+| Reconnect backoff | 1.5s / 3s / 6s (exponential) | Retries EL WebSocket connection on unexpected close (max 3 attempts) |
+| Cleanup interval | Every 60 seconds | Same as idle cleanup |
+
+### 13.2 Startup Recovery
+
+When the server starts (`initialize()`):
+1. Queries all `WhatsAppSession` documents with `status: 'waiting'`
+2. For each:
+   - If `grace_deadline` has already passed → immediately fire `onGracePeriodExpired`
+   - If `grace_deadline` is in the future → create a new `setTimeout` with remaining milliseconds
+3. Logs count of recovered sessions
+
+This ensures no sessions are lost across server restarts.
+
+### 13.3 Stuck Session Sweeper
+
+Every 5 minutes, runs a MongoDB query:
+```javascript
+WhatsAppSession.find({
+  status: 'waiting',
+  grace_deadline: { $lt: new Date() }
+})
+```
+
+For each result, checks if an in-memory timer exists. If not, fires `onGracePeriodExpired`. This catches edge cases where:
+- Timer was garbage collected
+- Server memory pressure caused timer loss
+- Race condition between timer creation and webhook processing
+
+### 13.4 WebSocket Lifecycle
+
+- **15-second init timeout**: If ElevenLabs WebSocket doesn't send `conversation_initiation_metadata` within 15s, the connection is rejected
+- **10-minute idle timeout**: Connections with no activity for 10 minutes are automatically closed
+- **30-minute conversation timeout**: If `elevenlabs_last_interaction_at` is > 30 minutes old, a new conversation is started (new WebSocket connection)
+- **First response suppression**: The ElevenLabs agent sends a greeting on connection. This is suppressed (not forwarded to WhatsApp) because it would be contextually inappropriate.
+- **Automatic reconnection**: When the ElevenLabs WebSocket closes unexpectedly (close code !== 1000) and `intentionallyClosed` is `false`, the system automatically attempts reconnection with exponential backoff (1.5s, 3s, 6s — max 3 attempts). All intentional close paths (takeover, session close, manual disconnect) set `intentionallyClosed = true` on the connection before closing to prevent unwanted reconnection.
+
+---
+
+## 14. ElevenLabs WebSocket Protocol
+
+### 14.1 Connection Setup
+
+```
+1. GET signed URL via elevenlabsService.getSignedUrl({ agentId })
+2. Append ?textOnly=true to URL
+3. Open WebSocket
+4. Wait for: { "type": "conversation_initiation_metadata" }
+5. Extract conversation_id
+6. Mark connection as ready
+```
+
+### 14.2 Sending Messages
+
+**Context (sent once per new connection)**:
+```json
+{
+  "type": "contextual_update",
+  "text": "Previous conversation history:\nPatient: Merhaba, randevu almak istiyorum\nOperator: Tabii, hangi doktor icin?"
+}
+```
+
+**User message**:
+```json
+{
+  "type": "user_message",
+  "text": "Yarin saat 10'da musait misiniz?"
+}
+```
+
+### 14.3 Receiving Responses
+
+```json
+{
+  "type": "agent_response",
+  "agent_response_event": {
+    "agent_response": "Evet, yarin saat 10:00 icin randevunuzu olusturuyorum."
+  }
+}
+```
+
+**Response handling**:
+1. First `agent_response` → suppressed (`suppressFirstResponse` flag)
+2. Subsequent responses → `sendResponse()` → Unipile → WhatsApp
+
+### 14.4 Connection Reuse & Reconnection
+
+- One WebSocket per `unipile_chat_id` (not per session)
+- If a connection already exists and is alive + not timed out → reuse it
+- If connection is dead or conversation timed out → create new one
+- On unexpected close (code !== 1000, `intentionallyClosed` = false) → `attemptReconnect()` with exponential backoff
+- On intentional close → removed from connections map, no reconnection attempted
+
+---
+
+## 15. Migration
+
+### 15.1 Session Migration — `scripts/migrate-sessions.ts`
+
+Migrates from the old chat-centric architecture (session fields embedded on `WhatsAppChat`) to the session-centric architecture (`WhatsAppSession` documents).
+
+**Usage**:
+```bash
+npx tsx scripts/migrate-sessions.ts --dry-run   # Preview changes
+npx tsx scripts/migrate-sessions.ts              # Execute migration
+```
+
+**What it does**:
+1. Reads all chats from `whatsappchats` collection (raw MongoDB, not Mongoose)
+2. For each chat with old session fields:
+   - Creates a `WhatsAppSession` document with mapped fields
+   - Backfills `session_id` on `WhatsAppMessage` documents created since session start
+   - Updates `message_count` on the new session
+3. Updates each chat:
+   - Sets `is_closed` (true if old `mode` was `'closed'`)
+   - Sets `active_session_id` (if session is not resolved)
+   - `$unset` removes 10 old fields: `mode`, `session_status`, `session_started_at`, `session_grace_deadline`, `session_resolved_by`, `taken_over_by`, `taken_over_at`, `elevenlabs_conversation_id`, `elevenlabs_conversation_created_at`, `elevenlabs_last_interaction_at`
+
+**Idempotent**: Skips chats that already have `active_session_id` set.
+
+### 15.2 Agent Reference Migration — `scripts/migrate-agent-ref.ts`
+
+Migrates the old `elevenlabs_agent_id` string in tenant WhatsApp settings to the new `agent_id` ObjectId reference to the Agent model.
+
+**Usage**:
+```bash
+npx tsx scripts/migrate-agent-ref.ts --dry-run   # Preview changes
+npx tsx scripts/migrate-agent-ref.ts              # Execute migration
+```
+
+**What it does**:
+1. Finds all tenants that have `settings.whatsapp_agent.elevenlabs_agent_id` set
+2. For each tenant, looks up the Agent document by matching the ElevenLabs agent ID
+3. Sets `settings.whatsapp_agent.agent_id` to the Agent's ObjectId
+4. Removes the old `settings.whatsapp_agent.elevenlabs_agent_id` field
+
+**Idempotent**: Skips tenants that already have `agent_id` set or where the old field is absent.
+
+---
+
+## 16. File Map
+
+```
+src/
+├── modules/
+│   ├── whatsapp/
+│   │   ├── whatsapp-chat.model.ts        # WhatsAppChat Mongoose model
+│   │   ├── whatsapp-session.model.ts     # WhatsAppSession Mongoose model
+│   │   ├── whatsapp-message.model.ts     # WhatsAppMessage Mongoose model
+│   │   └── whatsapp.routes.ts            # All /whatsapp/* API routes + enrichChat()
+│   └── webhooks/
+│       └── unipile.routes.ts             # POST /webhooks/unipile handler
+├── services/
+│   ├── whatsapp-agent.service.ts         # Session timers, EL WebSocket, AI orchestration
+│   ├── unipile.service.ts                # Unipile REST API client
+│   └── elevenlabs.service.ts             # ElevenLabs SDK wrapper (getSignedUrl)
+│
+web/src/
+├── pages/
+│   └── WhatsApp.tsx                      # Two-panel layout (both /whatsapp and /whatsapp/:chatId)
+├── components/
+│   ├── whatsapp/
+│   │   ├── ChatList.tsx                  # Left panel: stats, filters, search, chat items
+│   │   ├── ChatListItem.tsx              # Single chat row in the list
+│   │   ├── ChatHeader.tsx                # Right panel header: contact info, actions
+│   │   ├── MessageList.tsx               # Scrollable message stream with session dividers
+│   │   ├── MessageBubble.tsx             # Single message bubble (color-coded)
+│   │   ├── MessageInput.tsx              # Text input bar + send button
+│   │   ├── SessionDivider.tsx            # Visual separator between sessions
+│   │   ├── SessionHistory.tsx            # "Oturum Gecmisi" tab content
+│   │   ├── StatsBar.tsx                  # Compact stats row
+│   │   └── SettingsDialog.tsx            # Connection, agent, grace period, blacklist settings
+│   └── status-badge.tsx                  # ChatModeBadge, SessionStatusBadge
+└── types/
+    └── index.ts                          # WhatsAppChat, WhatsAppMessage, WhatsAppSession, WhatsAppStats types
+
+scripts/
+├── migrate-sessions.ts                   # Old → new session architecture migration
+└── migrate-agent-ref.ts                  # elevenlabs_agent_id → agent_id (ObjectId) migration
+```
+
+---
+
+## 17. Constants & Timeouts
+
+| Constant | Value | Location | Purpose |
+|----------|-------|----------|---------|
+| Default grace period | 180 seconds (3 min) | Tenant settings | Time before AI takes over |
+| Min grace period | 30 seconds | whatsapp.routes.ts config endpoint | Lower bound |
+| Max grace period | 1800 seconds (30 min) | whatsapp.routes.ts config endpoint | Upper bound |
+| MESSAGE_BUFFER_MS | 20 seconds | whatsapp-agent.service.ts | Debounce window for rapid-fire contact messages before sending to AI |
+| SESSION_INACTIVITY_TIMEOUT_MS | 30 minutes | whatsapp-agent.service.ts | Auto-resolve active sessions with no activity |
+| MAX_RECONNECT_ATTEMPTS | 3 | whatsapp-agent.service.ts | Max EL WebSocket reconnection attempts on unexpected close |
+| RECONNECT_BASE_DELAY_MS | 1500 ms (1.5 seconds) | whatsapp-agent.service.ts | Base delay for exponential backoff (1.5s, 3s, 6s) |
+| Conversation timeout | 30 minutes | whatsapp-agent.service.ts | If EL conversation idle > 30min, start new one |
+| Idle connection timeout | 10 minutes | whatsapp-agent.service.ts | Close EL WebSocket after 10min idle |
+| WS init timeout | 15 seconds | whatsapp-agent.service.ts | Reject EL WebSocket if no init in 15s |
+| Idle cleanup interval | 60 seconds | whatsapp-agent.service.ts | How often to check for idle connections |
+| Stuck session sweep interval | 5 minutes | whatsapp-agent.service.ts | How often to check for stuck sessions |
+| Inactive session sweep interval | 5 minutes | whatsapp-agent.service.ts | How often to check for inactive sessions to auto-resolve |
+| Chat context messages | 20 messages | whatsapp-agent.service.ts | Max messages sent to EL as context |
+| Message preview length | 100 characters | webhook + routes | Truncated for `last_message_preview` |
+| Frontend poll interval | 3 seconds | WhatsApp.tsx | How often to refresh messages |
+| Frontend list poll interval | 5 seconds | WhatsApp.tsx | How often to refresh chat list |
+| Max messages per page | 200 | whatsapp.routes.ts | Limit on messages endpoint |
+| Max chats per page | 100 | whatsapp.routes.ts | Limit on chats endpoint |
+
+---
+
+## 18. Decision Tables
+
+### 18.1 Incoming Contact Message → What Happens?
+
+| Blacklisted? | Session Exists? | Session Status | Action |
+|-------------|-----------------|----------------|--------|
+| Yes | — | — | Store message (no session_id), no AI |
+| No | No | — | Create session (waiting), start timer |
+| No | Yes | `waiting` | Store message in session, timer keeps running |
+| No | Yes | `active` + no takeover | Forward to AI via ElevenLabs WebSocket |
+| No | Yes | `active` + taken over | Store message in session, skip AI |
+| No | Yes | `resolved` | Clear stale ref, create new session |
+
+### 18.2 Self-Sent Message → What Happens?
+
+| Session Exists? | Session Status | Action |
+|-----------------|----------------|--------|
+| Yes | `waiting` | Resolve session as human, cancel timer |
+| Yes | `active` + AI mode | Set `taken_over_at`, close EL WebSocket |
+| Yes | `active` + already human | Store message only |
+| No | — | Store message (no session_id) |
+
+### 18.3 Dashboard Action → What Happens?
+
+| Action | Precondition | Session Changes | Side Effects |
+|--------|-------------|-----------------|-------------|
+| **Takeover** | Active session exists | If waiting: cancel timer, → active. Set `taken_over_by/at`. | Close EL WebSocket |
+| **Release** | Human-taken session | Clear takeover fields, reset EL fields. | If immediate: replay pending messages |
+| **Close** | Any | Resolve session (manual). Set `chat.is_closed = true`. | Close EL WebSocket, cancel timer |
+| **Reopen** | Chat is closed | — | Set `chat.is_closed = false` |
+| **Send** | Human mode | If waiting: resolve as human, cancel grace timer | Send via Unipile, store in DB |