> ## 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.

# Departmental WhatsApp Inbox

> Role-scoped 1-on-1 WhatsApp messaging across CRM operational departments with automated executive routing, chat history preservation, and Meta Cloud API integration.

## Departmental Scoping Overview

In BrokerOS, real estate client communications are not isolated to marketing broadcasts. Every operational department requires direct, real-time WhatsApp messaging with prospects, clients, and channel partners while strictly honoring data governance boundaries.

Rather than maintaining separate chat applications or permitting agents to use unmonitored personal phones, BrokerOS implements a **Universal Engine with Role-Scoped Workspaces**:

* **Pre-Sales**: Communicates only with assigned early discovery leads (`NEW`, `CONTACTED`, `INTERESTED`).
* **Sales Executive**: Takes over lead communication immediately upon site visit scheduling (`SITE_VISIT_SCHEDULED`, `NEGOTIATION`, `BOOKING`).
* **Post-Sales**: Direct WhatsApp engagement with confirmed buyers for documentation, home loans, milestone billing, and possession handover.
* **Sourcing Manager**: Communicates strictly with assigned Channel Partner (CP) brokers regarding inventory availability, site visits, and commission settlements.
* **Closing Manager**: Stationed on-site at sales galleries, managing walk-in leads and on-site negotiation prospects.
* **Finance**: Oversees payment collections, demand notices, receipts, and CP commission disbursements.
* **Managers & Directors**: Maintain team-wide oversight with interactive filters to inspect subordinate conversation velocity.

***

## Architectural Workflow: Lead Handoff & History Preservation

When a lead transitions across departments, such as from Pre-Sales to Sales Executive upon scheduling a site visit, the conversation history remains unified while the active inbox routing shifts automatically.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Buyer as Property Buyer
    actor PreSales as Pre-Sales Rep
    participant CRM as BrokerOS CRM API
    participant Meta as Meta Cloud API
    actor SalesExec as Sales Executive
    actor PostSales as Post-Sales Rep

    Buyer->>Meta: Inbound WhatsApp Inquiry
    Meta->>CRM: Webhook Ingestion
    CRM->>PreSales: Routes to Pre-Sales Rep Inbox (/dashboard/pre-sales/whatsapp)
    PreSales->>Buyer: Direct WhatsApp Reply (*Agent Name* signature)
    
    Note over PreSales,SalesExec: Lead Qualifies and Schedules Site Visit
    PreSales->>CRM: Schedule Site Visit -> Reassigns to Sales Executive
    CRM->>SalesExec: Conversation moves to Sales Exec Inbox (/dashboard/sales-executive/whatsapp)
    Note over SalesExec: Full prior chat history seamlessly visible
    SalesExec->>Buyer: Sends Location Pin & Meeting Confirmation
    
    Note over SalesExec,PostSales: Unit Booked -> Booking Confirmed
    SalesExec->>CRM: Creates Booking -> Customer Profile Generated
    CRM->>PostSales: Routes to Post-Sales Inbox (/dashboard/inbox/whatsapp)
    PostSales->>Buyer: Automated Welcome Letter & Payment Demand Notice
```

***

## Role Scoping Matrix

The backend enforces data isolation through [whatsapp-conversations.service.ts](file:///c:/Users/Sumama/Desktop/enterprise-crm-realtors/apps/api/src/marketing/whatsapp/conversations/whatsapp-conversations.service.ts):

| Department Role | Scope Filter | Visible Entities | In-App UI Route |
| :- | :- | :- | :- |
| **Pre-Sales Executive** | `my` | Leads where `assignedUserId = currentUser.id` and status in (`NEW`, `CONTACTED`, `INTERESTED`) | `/dashboard/inbox/whatsapp` |
| **Pre-Sales Manager** | `team` | All leads assigned to direct subordinates, with executive dropdown filter | `/dashboard/inbox/whatsapp` |
| **Sales Executive** | `my` | Leads where `assignedUserId = currentUser.id` and status in (`SITE_VISIT_SCHEDULED`, `NEGOTIATION`, `BOOKING`) | `/dashboard/inbox/whatsapp` |
| **Sales Manager** | `team` | All leads assigned to subordinate sales executives, with deal velocity tracking | `/dashboard/inbox/whatsapp` |
| **Post-Sales Executive** | `my` | Customers where `booking.assignedPostSalesId = currentUser.id` | `/dashboard/inbox/whatsapp` |
| **Post-Sales Manager** | `team` | All post-booking customer threads across all team post-sales executives | `/dashboard/inbox/whatsapp` |
| **Sourcing Manager** | `my` | External CP Brokers where `broker.sourcingManagerId = currentUser.id` | `/dashboard/inbox/whatsapp` |
| **Closing Manager** | `my` | Walk-in leads created on-site or leads assigned at their project sales gallery | `/dashboard/inbox/whatsapp` |
| **Finance Department** | `all` | Customers with payment transactions and Brokers with commission claims | `/dashboard/inbox/whatsapp` |
| **Business Manager** | `all` | Enterprise-wide operational visibility across both Brokerage and CP network | `/dashboard/inbox/whatsapp` |
| **Director and Admin** | `all` | Full organizational oversight with real-time audit capabilities | `/dashboard/inbox/whatsapp` |

> [!NOTE]
>
> All roles access the unified route `/dashboard/inbox/whatsapp`. The page dynamically resolves department scope from the user authenticated session. Legacy role-specific URLs (such as `/dashboard/sales-manager/whatsapp`) automatically redirect to `/dashboard/inbox/whatsapp`.

***

## Key Operational Features

### 1. Automated Executive Provisioning

When a manager assigns new leads or brokers to an executive, BrokerOS automatically provisions conversation records even if the contact has not sent an inbound message yet. The contact appears in the executive's directory with a `"New • Uncontacted"` badge, allowing immediate outbound engagement.

### 2. Verified Sender Signatures

Because all departmental messages route through a single verified Meta WhatsApp Business Account (WABA), BrokerOS automatically prefixes outgoing agent replies with their name:

```text theme={null}
*John Doe*: Hello Mr. Sharma, I have attached the updated floor plan for Tower C.
```

This ensures buyers always know which representative they are speaking with while maintaining company brand identity.

### 3. Meta 24-Hour Session Enforcement

* **Within 24 Hours**: Executives can send free-form text, attachments, photos, and location coordinates.
* **Outside 24 Hours**: The input bar locks automatically, presenting a one-click template selector. When the client replies, the free-form window reopens automatically.

### 4. Deep-Linking from CRM Profiles

In both the Lead Profile and Broker Profile headers, clicking the **WhatsApp** action navigates directly to the current department's WhatsApp inbox:

* `/dashboard/pre-sales/whatsapp?leadId=[id]`
* `/dashboard/sales-executive/whatsapp?leadId=[id]`
* `/dashboard/sourcing-manager/whatsapp?brokerId=[id]`
  Hold **Alt + Click** to open external WhatsApp Web if an executive specifically needs personal web access.


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