> ## 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 Marketing and Communication Suite

> Send high-throughput broadcasts, manage multi-agent team inboxes, build visual chatbot flows, deploy interactive messages, and automate lead drips using the official Meta WhatsApp Cloud API.

## Enterprise WhatsApp Architecture

BrokerOS integrates directly with the official **Meta WhatsApp Cloud API** through the dedicated `@brokeros/int-whatsapp` package. Designed for high-volume brokerage operations, the system handles incoming buyer inquiries, broadcasts project launches, and synchronizes real-time conversation state directly with CRM lead records.

Operating on the official Cloud API guarantees:

* Verified Business Profile status with green badge verification.
* Direct delivery through Meta global infrastructure with no third-party intermediary latency.
* Full compliance with Meta business messaging policies and 24-hour customer service window guidelines.
* Support for interactive components including Quick Reply buttons, List Menus, CTA URLs, phone dialers, and media headers (PDF brochures, images, walkthrough videos).

***

## Architecture and Execution Flow

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Lead as Buyer / Lead
    participant Meta as Meta WhatsApp Cloud API
    participant Worker as BullMQ (marketing-whatsapp)
    participant API as BrokerOS API
    participant WS as WebSocket Gateway
    actor Agent as Sales Executive

    Note over API,Worker: Outbound Broadcast / Drip Flow
    API->>Worker: Enqueue Campaign Job (Template + Audience)
    Worker->>Meta: POST /v20.0/{phone-id}/messages (Rate-Limited Batches)
    Meta-->>Lead: Deliver WhatsApp Message (Interactive)
    
    Note over Lead,API: Real-time Inbound & Inbox Flow
    Lead->>Meta: User Replies / Inbound Inquiry
    Meta->>API: POST /marketing/whatsapp/webhook (Signature Verified)
    API->>API: Match/Create Lead & Conversation Record
    API->>WS: Emit 'whatsapp.message.received'
    WS-->>Agent: Render Message in Shared Team Inbox
    Agent->>API: Send Free-form Reply (Within 24h Window)
    API->>Meta: POST /messages (Free-form Session Message)
    Meta-->>Lead: Deliver Agent Message to Device
```

***

## Core WhatsApp Modules

> **[Team Inbox](https://brokeros.mintlify.site/marketing/whatsapp/team-inbox.md)**
>
> Unified multi-agent shared inbox for real-time customer conversations. Includes agent assignment, internal team notes, quick replies, and lead status syncing.

> **[Contact Directory](https://brokeros.mintlify.site/marketing/whatsapp/contacts.md)**
>
> Centralized WhatsApp contact management, CSV audience list import, custom field tracking, and 5-tab Lead 360 detail drawers.

> **[Broadcast Campaigns](https://brokeros.mintlify.site/marketing/whatsapp/broadcasts.md)**
>
> High-throughput messaging to segmented leads or imported CSV lists using Meta-approved utility and marketing templates with live read receipt tracking.

> **[Tiers, Pricing & Pre-Flight](https://brokeros.mintlify.site/marketing/whatsapp/preflight-and-tiers.md)**
>
> Meta messaging tiers (1K to Unlimited), phone quality score protection, conversation category pricing, and pre-flight capacity audits.

> **[Interactive Messages](https://brokeros.mintlify.site/marketing/whatsapp/interactive-messages.md)**
>
> Build zero-typing Quick Reply buttons and multi-section List Menus validated against Meta API limits with real-time mobile preview.

> **[Chatbot Flows](https://brokeros.mintlify.site/marketing/whatsapp/chatbot-flows.md)**
>
> Visual no-code conversation builder for automated lead qualification, project brochure delivery, FAQs, and instant site visit booking.

> **[Drip Automations](https://brokeros.mintlify.site/marketing/whatsapp/drip-automations.md)**
>
> Multi-stage automated messaging sequences triggered by lead creation, stage transitions, or site visit follow-ups across structured day intervals.

> **[Visual Pipelines](https://brokeros.mintlify.site/marketing/whatsapp/pipelines.md)**
>
> Kanban-style conversation management board mapping chats across qualification stages from initial discovery to contract signing.

> **[Template Manager](https://brokeros.mintlify.site/marketing/whatsapp/template-manager.md)**
>
> Create, preview, submit, and track approval status for Meta templates across Marketing, Utility, and Authentication categories.

> **[AI Assistant & Settings](https://brokeros.mintlify.site/marketing/whatsapp/ai-assistant-and-settings.md)**
>
> Configure Groq language models (`openai/gpt-oss-120b`), custom system prompts, HMAC-SHA256 webhook diagnostics, and CRM tags.

***

## Message Types and Service Windows

Meta enforces strict distinction between pre-approved template messages and free-form session messages:

| Message Classification | Allowed Timing | Meta Pre-Approval Required | Typical Use Case |
| :- | :- | :- | :- |
| **Business-Initiated (Template)** | Anytime (with opted-in recipients) | Required (Meta review: 2 to 60 mins) | Project announcements, payment alerts, appointment confirmations, drip sequences |
| **User-Initiated (Session Window)** | Within 24 hours of customer's last message | Not required (Free-form text, audio, images) | Sales agent 1-on-1 chats, negotiation discussions, real-time customer support |

> [!NOTE]
>
> Every inbound message from a lead resets the **24-hour customer service window**. During this window, sales agents can communicate freely without paying template conversation fees or requiring pre-approved copy. Once the window expires, outgoing communication must initiate via an approved template message.


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