Step 1: Installation & Prerequisites

Prerequisites:
• Odoo 17.0 (Community or Enterprise Edition)
• WhatsApp Module (odoo/whatsapp) installed and configured
• Active WhatsApp Business Account connected to Odoo

Installation:
1. Download module from Odoo Apps Store
2. Extract to your Odoo addons directory
3. Update Apps List: Settings → Apps → Update Apps List
4. Search "WhatsApp Chat UI" and click Install
5. Module automatically inherits existing WhatsApp configuration

Step 2: Main Chat Interface

Access: Navigate to WhatsApp → Chat Interface

Left Sidebar (Chat List):
• Company header with current company name
• Search bar for filtering contacts
• Mode toggle: Internal Users | CRM Leads | WhatsApp
• Filter buttons: All | Pending | Replied
• Chat list with avatars, names, last messages
• Unread count badges
• Real-time sorting by latest message

Right Panel (Message View):
• Contact header with name, status, phone number
• WhatsApp-style message bubbles (green for sent, white for received)
• Message timestamps
• Delivery status indicators (✓ sent, ✓✓ delivered/read)
• Attachment previews (images, PDFs, voice messages)
• Message input area with emoji, attachment, voice buttons

Auto-Loading:
• Channels load automatically based on current company
• Last 100 messages per chat loaded
• Auto-scrolls to bottom on new messages
• Real-time refresh every 3-5 seconds

Step 3: Sending Messages & Attachments

Text Messages:
1. Select a chat from the left sidebar
2. Type your message in the input field
3. Press Enter or click Send button
4. Message appears instantly on right side (green bubble)
5. Syncs to WhatsApp via Odoo's WhatsApp integration

Emoji Support:
• Click 😊 emoji button
• Emoji picker appears with 20+ common emojis
• Click any emoji to insert into message
• Picker auto-closes after selection

File Attachments:
• Click 📎 paperclip button
• Select file (images, PDFs, documents up to 10MB)
• File uploads instantly with preview
• Supported formats: JPG, PNG, PDF, DOC, DOCX, TXT
• Images show thumbnail preview
• PDFs open in modal viewer
• Documents show with download button

Voice Messages:
• Click 🎤 microphone button
• Browser requests microphone permission (first time)
• Recording starts with red dot indicator
• Max duration: 60 seconds (WhatsApp limit)
• Click stop to end recording
• Preview modal appears with playback controls
• Click Send to share voice message
• Voice messages appear as audio waveforms in chat

Step 4: Template Messages (24-Hour Window)

WhatsApp 24-Hour Policy:
WhatsApp Business API allows free-form messages only within 24 hours of last customer message. After that, only approved templates can be sent.

Automatic Detection:
• Module checks time since last inbound customer message
• If > 24 hours: Shows yellow warning bar
• Message input is hidden
• "Send Template" button appears

Sending Templates:
1. Click "Send Template" button (or 📋 icon)
2. Template selector popup appears
3. Shows all approved templates for current company
4. Templates display with preview text
5. Click any template to send
6. Template variables auto-processed:
• [Name] → Customer name from record
• [Date] → Current date
• [Link] → Highlighted as link
7. Template sent via WhatsApp Business API
8. Appears in chat with special template indicator

Template Configuration:
• Templates managed in: Settings → WhatsApp → Templates
• Only approved templates appear in selector
• Company-wise filtering ensures correct templates
• Template status syncs from Facebook Business Manager

Step 5: Multi-Mode Communication

Internal Users Mode:
1. Click "👤 Internal Users" toggle button
2. Displays all active Odoo users (non-portal)
3. Shows user avatars, names, email addresses
4. Click any user to view details
5. Useful for quick reference to team members
6. Can see user's phone number if available

CRM Leads Mode:
1. Click "📊 CRM Leads" toggle button
2. Loads all CRM leads from database
3. Search by name, phone, or email
4. Click lead to view details
5. Right-click context menu:
• "Open Lead" → Opens CRM lead form
• "Send WhatsApp" → Opens WhatsApp web
6. Shows lead status and contact info
7. Perfect for sales team to quickly access leads

WhatsApp Channels Mode (Default):
1. Default view on opening chat interface
2. Shows all actual WhatsApp conversations
3. Only channels for current company visible
4. Full messaging capabilities enabled
5. Real-time message synchronization
6. Supports all features: text, voice, files, templates

Step 6: Chatter Widget Integration

Available On:
• CRM Leads
• CRM Opportunities
• Contacts (res.partner)
• HR Recruitment Applications
• Any model with chatter enabled

Usage:
1. Open any record (e.g., CRM Lead)
2. Find "💬 WhatsApp Chat" button in chatter toolbar
3. Click to open popup chat (bottom-right corner)

First-Time Setup:
• If record has mobile/phone field: Auto-loads chat
• If no number found: Shows input form
• Enter WhatsApp number with country code
• Click "Start Chat" button
• Number saved to record for future use

Popup Chat Features:
• Header shows record name and WhatsApp number
• Message history loads from discuss.channel
• Send text messages directly
• Template button for quick templates
• Message input with Enter key support
• Close and reopen: State persists via localStorage
• Each record has separate chat state (unique storage key)

State Persistence:
• localStorage key format: whatsapp_chatter_{model}_{id}
• Saves: channel_id, whatsapp_number, last_message_id
• Auto-restores chat when reopening same record
• Old states (>7 days) automatically cleaned up
• No cross-record contamination

Step 7: Multi-Company Management

Company Filtering:
• Automatically detects current company from user context
• this.user.context.allowed_company_ids[0]
• Only loads WhatsApp accounts for current company
• Channels filtered by account ownership
• Complete data isolation between companies

Switching Companies:
1. Use Odoo's company switcher (top-right)
2. Module listens to 'company_switched' event
3. Triggers automatic reload:
• Clears current channels and messages
• Reloads accounts for new company
• Fetches channels for new accounts
• Shows welcome screen
• Updates header with company name
4. Notification shows: "Switched to {CompanyName}"
5. Real-time updates continue for new company

Backend Company Filtering:
Python Code:
def get_current_company_accounts(self): current_company = self.env.company return self.search([ ('allowed_company_ids', 'in', current_company.ids), ('active', '=', True) ])

Frontend Company Detection:
// JavaScript this.currentCompany = this.user.context.allowed_company_ids[0]; this.companyName = this.user.context.companies_names?.[this.currentCompany];

Benefits:
✅ Perfect for agencies managing multiple clients
✅ Multi-brand companies with separate WhatsApp accounts
✅ Franchise businesses with location-based accounts
✅ No data leakage between companies
✅ Automatic filtering - no manual configuration needed

Step 8: Real-time Updates System

Two Auto-Refresh Mechanisms:

1. Channel List Refresh (Every 5 seconds):
this.channelRefreshInterval = setInterval(() => { this.loadWhatsAppChannels(true); // silent=true }, 5000);
• Updates chat list in sidebar
• Fetches new channels
• Updates last messages
• Refreshes unread counts
• Runs silently (no loading indicators)

2. Message Refresh (Every 3 seconds):
this.messageRefreshInterval = setInterval(() => { if (this.state.activeChannel) { this.loadChannelMessages(this.state.activeChannel.id, false); } }, 3000);
• Only runs when a chat is open
• Fetches new messages for active chat
• Auto-scrolls to bottom if near bottom
• Preserves scroll position if user scrolled up

Smart Scroll Management:
• this.state.userHasScrolled flag tracks user scroll
• If user near bottom (• If user scrolled up: Preserves position
• Sending message: Always scrolls to bottom

Optimistic UI Updates:
• Sent messages appear instantly (before API confirmation)
• Temporary message with current timestamp
• Replaced with actual message after 500ms refresh
• Smooth user experience with no delays

Performance Optimization:
• Silent refresh (no loading spinners)
• Only updates changed data
• Efficient DOM rendering
• Automatic cleanup on component unmount

Complete Data Flow Diagram

End-to-End Process:

👤 User Opens WhatsApp Chat Interface ↓ 🏢 JavaScript detects current company this.currentCompany = user.context.allowed_company_ids[0] ↓ 📞 Load WhatsApp Accounts for Company orm.searchRead('whatsapp.account', [company filter]) ↓ 💬 Load Channels for Accounts orm.searchRead('discuss.channel', [account filter]) ↓ 📨 Load Last Messages per Channel orm.searchRead('mail.message', [channel filter]) ↓ 🎨 Render Chat List (Left Sidebar) Display channels with avatars, names, last messages ↓ 👆 User Selects a Chat ↓ 📜 Load Full Message History GET mail.message WHERE res_id = channel_id ↓ 🔍 Fetch WhatsApp Direction GET whatsapp.message.message_type (inbound/outbound) ↓ 🖼️ Render Messages (Right Panel) Green bubbles (sent) | White bubbles (received) ↓ ⌨️ User Types & Sends Message ↓ ⚡ Instant UI Update (Optimistic) Message appears immediately in green bubble ↓ 📡 API Call to Backend discuss.channel.message_post(body, type='whatsapp_message') ↓ 💾 Save to Database Creates mail.message + whatsapp.message records ↓ 📤 Send via WhatsApp API Odoo's WhatsApp integration sends to customer ↓ 🔄 Auto-Refresh (3 seconds) Confirms message saved, updates status ↓ ✅ Customer Receives on WhatsApp
Processing Time: Messages appear in UI instantly, sync to WhatsApp within 1-2 seconds, confirmed with checkmarks.

Key Benefits & ROI

✅ Time Savings:
• WhatsApp-style interface - No learning curve
• Quick access from any form via chatter
• Real-time updates - No manual refreshing
• Template quick-send for common responses
• Average 30% faster response times

✅ Better Customer Experience:
• Faster response times with real-time updates
• Professional formatting with emojis
• Voice messages for complex explanations
• File sharing for documents/images
• Complete conversation history

✅ Team Productivity:
• Multiple team members can access same chats
• Search and filter to find conversations quickly
• CRM integration for lead tracking
• Multi-company support for agencies
• No switching between WhatsApp Web and Odoo

✅ Sales & Marketing:
• Direct WhatsApp from CRM leads
• Template campaigns for bulk messaging
• Track conversation history per lead
• Measure response times and engagement
• Better lead nurturing capabilities

✅ Technical Advantages:
• Built on Odoo's native WhatsApp module
• Clean OWL framework implementation
• No external dependencies
• Mobile responsive design
• Easy to customize and extend

Quick Start

1. Install Prerequisites: Ensure WhatsApp module (odoo/whatsapp) is installed and configured
2. Configure WhatsApp Business: Settings → WhatsApp → WhatsApp Accounts → Set up your accounts
3. Install Module: Apps → Search "WhatsApp Chat UI" → Install
4. Access Interface: WhatsApp → Chat Interface menu
5. Start Chatting: Select any chat from sidebar and start messaging

Main Chat Interface

• Access: WhatsApp → Chat Interface
• Left Sidebar: Shows all chats with search and filter options
• Right Panel: Message view with full chat history
• Mode Toggle: Switch between WhatsApp/Internal/CRM modes
• Search: Type in search box to filter chats by name/number
• Filters: All | Pending Reply | Replied

Using Chatter Widget

1. Open Any Record: CRM Lead, Contact, HR Application, etc.
2. Find WhatsApp Button: In chatter toolbar (right side)
3. Click to Open: Popup chat appears bottom-right
4. Enter Number (if needed): First time may ask for WhatsApp number
5. Start Messaging: Type and press Enter to send
6. Use Templates: Click template button for quick messages
7. Close & Reopen: State persists automatically

Template Management

• Create Templates: Settings → WhatsApp → Templates
• Get Approval: Submit to Facebook for approval (required)
• Use in Chat: Click template button when 24-hour window passed
• Auto-Detection: Module shows template option automatically
• Company-Wise: Only approved templates for current company shown

Multi-Company Setup

• Company Setup: Settings → Companies → Configure each company
• WhatsApp Accounts: Assign WhatsApp accounts to each company
• Automatic Filtering: Module shows only current company's chats
• Switch Companies: Use Odoo company switcher - chats reload automatically
• Data Isolation: Complete separation between company data

User Access Rights

• System Administrators: Full access to all features
• Sales Users: Can access chat interface and send messages
• Sales Managers: Can view all team's conversations
• Multi-Company Users: See chats from their assigned companies only
• Portal Users: No access (internal tool)