> ## Documentation Index
> Fetch the complete documentation index at: https://brokeros.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Team Inbox

> A collaborative multi-agent shared inbox where sales executives and managers manage WhatsApp conversations with live WebSocket updates, CRM context, and internal notes.

## Unified Multi-Agent Team Inbox

The BrokerOS WhatsApp Team Inbox provides a centralized communication hub for your entire sales and closing department. Rather than client conversations remaining locked inside individual sales agents' personal phones, every WhatsApp interaction is tied to the central CRM lead record and accessible through a real-time web workspace.

Key organizational benefits include:

* **Zero Lead Leakage**: Inquiries are logged centrally, ensuring full visibility even during agent handoffs or absences.
* **Role-Based Visibility**: Sales executives manage their assigned chats, while sales managers supervise all department threads with SLA tracking.
* **Single Business Number**: All outbound and inbound messages route through your verified WhatsApp Business Account (WABA) number.

***

## Real-Time Messaging Architecture

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Lead as Buyer / Lead
    participant Meta as Meta Cloud API
    participant Ingest as API Webhook Handler
    participant DB as Postgres CRM Database
    participant Gateway as WebSocket Gateway
    actor Agent as Sales Executive
    actor Mgr as Sales Manager

    Lead->>Meta: Sends WhatsApp Message (Text or Media)
    Meta->>Ingest: Inbound Webhook (POST /marketing/whatsapp/webhook)
    Ingest->>DB: Upsert Contact, Message, & Conversation Thread
    Ingest->>Gateway: Broadcast Event 'conversation.message.new'
    Gateway-->>Agent: Live Stream Update (Chat Window)
    Gateway-->>Mgr: Live Stream Update (Manager Overview)
    
    Note over Agent,DB: Agent Internal Collaboration
    Agent->>DB: Add Internal Yellow Note ("Buyer requested corner 3BHK unit")
    DB->>Gateway: Broadcast Event 'conversation.note.added'
    Gateway-->>Mgr: Display Internal Note in Audit Thread

    Note over Agent,Meta: Outbound Reply (24h Window Active)
    Agent->>Ingest: Send Agent Reply ("We have sent the brochure!")
    Ingest->>Meta: POST /messages (Session Message)
    Meta-->>Lead: Deliver to Lead WhatsApp
    Ingest->>Gateway: Update Message Status: Sent -> Delivered -> Read
```

***

## Workspace Layout and Controls

The Team Inbox interface is divided into three functional columns:

### Conversation Directory (Left Column)

* **Folder Tabs**: Filter conversations by **Mine** (assigned to logged-in user), **Unassigned** (pending routing), and **All Conversations** (manager view).
* **Status & Label Filters**: Sort by pipeline stage, unread status, active 24-hour window, or custom tags (such as `Hot Investor`, `NRI`, `High Budget`).
* **SLA Badges**: Visual indicators highlighting conversations pending a response for more than 5 minutes.

### Conversation Stream (Center Column)

* **Unified Timeline**: Displays incoming buyer messages, outgoing agent replies, automated chatbot responses, and internal team notes in chronological order.
* **Internal Team Notes**: Yellow-tinted notes visible exclusively to internal staff. Used for sharing buyer background, credit verification details, or handover instructions.
* **24-Hour Session Timer**: A persistent indicator showing remaining time in the Meta customer service window. If expired, the input area transitions to template selection mode.
* **Quick Replies (`/` shortcuts)**: Pre-configured message snippets for instant answers (for example, `/directions`, `/brochure`, `/payment-terms`).

### Lead Context Drawer (Right Column)

* **CRM Profile Summary**: Immediate access to lead name, phone number, email, assigned project, and budget range.
* **Temperature & Score**: Live display of lead temperature (`HOT`, `WARM`, `COLD`) and AI qualification score.
* **Inline Actions**: One-click shortcuts to update lead status, schedule an on-site visit, or reassign the conversation to another closing specialist.

***

## The 24-Hour Customer Service Window

Meta enforces strict messaging guidelines to prevent customer spam:

| Window Status | Eligible Actions | Cost and Approval |
| :- | :- | :- |
| **Active Session (Under 24 Hours)** | Sales agents can send arbitrary free-form text, voice notes, PDFs, location cards, and images. | Standard service conversation rate; no template pre-approval needed. |
| **Expired Session (Over 24 Hours)** | Input box is locked for free-form typing. Agents must select a pre-approved Meta template (Utility or Marketing) to reopen the conversation. | Standard business-initiated template rate; template must be Meta-approved. |

***

## Conversation Assignment and Routing

BrokerOS supports both automated and manual assignment policies:

* Automatic Project Matching: If an incoming phone number matches an existing lead in the CRM, the conversation is automatically assigned to that lead's existing sales executive.
* Round-Robin Queue: New inquiries from first-time prospects are distributed evenly among on-duty sales agents assigned to the active campaign project.
* Manager Override: Sales managers can reassign active threads at any time with an accompanying internal transition note.

***

## Scheduled WhatsApp Messaging

Sales agents can compose messages ahead of time and schedule them for future delivery directly from the team inbox. This ensures timely communications (such as appointment reminders, morning follow-ups, or weekend check-ins) without requiring agents to be logged in at the exact dispatch moment.

### Scheduling Flow and Controls

1. **Triggering the Modal**: In the composer toolbar at `Dashboard -> Marketing -> WhatsApp -> Inbox`, click the `<CalendarClock />` icon or click the split Send button dropdown and select **Schedule Message**.
2. **Scheduling Options Modal**:
   * **Quick Presets**: Select from convenient shortcuts such as **In 1 hour**, **Tomorrow 9:00 AM**, **Tomorrow 2:00 PM**, or **Monday 9:00 AM**.
   * **Custom Date and Time**: Use the date and time picker to configure any future execution timestamp.
3. **Smart Meta 24-Hour Window Enforcement**:
   * If the scheduled time falls within the active 24-hour customer service window, free-form text or media messages are permitted.
   * If the scheduled time falls outside the 24-hour window (or if the customer session is currently closed), BrokerOS prompts the agent to select an approved Meta Message Template. This guarantees delivery when the scheduled timestamp arrives, regardless of session expiration.
4. **Pending State and Inline Actions**:
   * The message enters the conversation thread as a dashed-border bubble marked with an amber clock badge and status `SCHEDULED`.
   * Any sales agent with thread permissions can click inline action buttons directly on the scheduled bubble:
     * **Send Now**: Immediately dispatches the message and bypasses the remaining countdown.
     * **Edit**: Opens the in-place editor modal to modify the message text, template selection, or target dispatch time.
     * **Cancel**: Removes the scheduled message from the queue and flags it as `CANCELLED`.
5. **Floating Scheduled Messages Dock**:
   * When a conversation has one or more pending scheduled messages, a floating amber dock appears directly above the message composer.
   * Agents can review pending messages, check time remaining, or trigger quick edits and cancellations without scrolling through historical messages.
6. **Directory Scheduled Chip**:
   * On the left conversation directory, conversations containing pending scheduled messages display a compact amber chip `[Scheduled: <Date>]`, preventing duplicate follow-ups across the sales team.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Agent as Sales Executive
    participant Web as Web Composer (apps/web)
    participant API as NestJS API (apps/api)
    participant DB as Postgres CRM Database
    participant Worker as Scheduled Processor (apps/workers)
    participant Meta as Meta Cloud API
    actor Lead as Buyer / Lead

    Agent->>Web: Compose Message & Click Schedule (e.g. Tomorrow 9:00 AM)
    Web->>API: POST /marketing/whatsapp/inbox/schedule
    API->>DB: Store WhatsAppMessage (status: SCHEDULED, scheduledAt)
    API-->>Web: 201 Created (Message with SCHEDULED status)
    Web-->>Agent: Render Dashed Bubble & Floating Scheduled Dock

    Note over DB,Worker: Worker Scanner (Every 10s)
    Worker->>DB: Scan for scheduledAt <= NOW() and status = SCHEDULED
    Worker->>DB: Atomic Lock (status: PROCESSING)
    Worker->>Meta: POST /messages (Template or Free-form)
    Meta-->>Lead: WhatsApp Message Delivered
    Worker->>DB: Update Message status = SENT, sentAt = NOW()
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.