# Messages UI Overhaul - 0.1% Plan > **Status:** ✅ CC2 COMPLETE - Built and deployed Jan 17, 2026 > **Created:** Jan 17, 2026 > **CC1 Investigation Complete** ## Implementation Complete (CC2 Session 3) All critical features implemented: - ✅ Step 1: SearchBar component created - ✅ Step 2: SearchBar integrated into Messages header - ✅ Step 3: NewMessageModal component created - ✅ Step 4: Lead search API endpoint added - ✅ Step 5: + New Message button added to header - ✅ Step 6: Handle conversation API endpoint added - ✅ Step 7: Done action added to conversation cards - ✅ Step 8: Filters updated to exclude handled conversations - ✅ Step 9: Unknown numbers handled in UI - ⏭️ Steps 10-12: Vertical filters and bulk actions (deferred to Phase 2) --- ## Executive Summary The Messages UI has been significantly built out but is missing 5 critical features for 0.1% standard. The user's "broken" screenshot was outdated - the current implementation has 12+ features working. This plan focuses on the gaps. --- ## Current State Audit ### What EXISTS and WORKS (12 features) | # | Feature | Component | Status | |---|---------|-----------|--------| | 1 | Sender name prominently displayed | EnhancedConversationCard:155 | ✅ Working | | 2 | Message preview (line-clamp-2) | EnhancedConversationCard:185-188 | ✅ Working | | 3 | Relative timestamp ("2m ago") | EnhancedConversationCard:174-176 | ✅ Working | | 4 | Lead context (type, score, company) | EnhancedConversationCard:158-181 | ✅ Working | | 5 | Quick action buttons per triage | EnhancedConversationCard:201-220 | ✅ Working | | 6 | Unread count badge | EnhancedConversationCard:143-147 | ✅ Working | | 7 | AI Triage categories | AITriageSection + Messages.jsx | ✅ Working | | 8 | Filter tabs with counts | InboxFilterTabs (6 filters) | ✅ Working | | 9 | AI reply suggestions (3 options) | AiSuggestionBar, /api/sms/ai-suggest | ✅ Working | | 10 | Template picker | TemplatePicker, Messages.jsx:369-530 | ✅ Working | | 11 | Schedule send | SchedulePicker, Messages.jsx:264-356 | ✅ Working | | 12 | Long-press context menu | MessageContextMenu, MiniLeadPopup | ✅ Working | ### File Structure (8 inbox components) ``` admin/src/components/inbox/ ├── AITriageSection.jsx # Collapsible triage category sections ├── AIExplainModal.jsx # AI explanation for messages ├── EnhancedConversationCard.jsx # Main conversation card ├── InboxFilterTabs.jsx # Filter tabs (horizontal) ├── LeadCardPreview.jsx # Lead info in conversation view ├── MessageContextMenu.jsx # Long-press context menu ├── MiniLeadPopup.jsx # Long-press lead popup └── SmartMessageContent.jsx # Clickable phone/email/date detection ``` ### API Endpoints (all working) | Endpoint | Purpose | |----------|---------| | `GET /api/sms/conversations/prioritized` | AI-triaged conversation list | | `GET /api/sms/conversation/:leadId` | Single conversation messages | | `POST /api/sms/send` | Send SMS (supports scheduling) | | `POST /api/sms/ai-suggest` | Get 3 AI reply suggestions | | `GET /api/sms/templates` | List all templates | | `GET /api/sms/stats` | SMS analytics | --- ## Gap Analysis (17 Issues → 5 Critical Missing) ### Already Working (12/17 issues) | Issue | Status | Evidence | |-------|--------|----------| | #1 No sender name visible | ✅ FIXED | EnhancedConversationCard:155 | | #2 No message preview | ✅ FIXED | EnhancedConversationCard:185 | | #3 No phone number | ✅ WORKS | LeadCardPreview:87-93 (in conv view) | | #4 No timestamp | ✅ FIXED | timeAgo() in EnhancedConversationCard | | #7 No lead context | ✅ FIXED | Score badge, W/C type, company | | #8 Horizontal scroll tabs | ⚠️ PARTIAL | Works but user wants vertical on desktop | | #9 Empty right panel | ✅ FIXED | ConversationView shows selected convo | | #10 No quick reply | ✅ FIXED | Quick action buttons per triage | | #11 No script picker | ✅ FIXED | TemplatePicker component | | #12 No unread indicator | ✅ FIXED | Red badge with count | | #14 "Continue conversation" | ✅ FIXED | Now shows actual quick actions | | #17 No empty state CTA | ✅ FIXED | "Send Messages" button in empty state | ### MISSING (5/17 issues) - This Plan Addresses | Issue | Priority | Solution | |-------|----------|----------| | #5 **No "+ New Message" button** | P0 | Add NewMessageModal component | | #6 **No link to Leads from inbox** | P0 | Add "Browse Leads" secondary CTA | | #13 **No search** | P0 | Add SearchBar component with fuzzy search | | #15 **No "Mark as handled"** | P1 | Add "Done" action to mark conversation handled | | #16 **No bulk actions** | P2 | Add bulk select mode (phase 2) | ### Additional Missing (not in original 17) | Issue | Priority | Solution | |-------|----------|----------| | Unknown number handling | P1 | Add "+ Add as Lead" action for unmatched numbers | | Vertical filters on desktop | P2 | Responsive layout with sidebar filters at md+ | --- ## Solution Design ### Feature 1: Search Bar (P0) **Component:** `SearchBar.jsx` (new) ```jsx // Search through conversations by: // - Lead name (first_name, last_name) // - Company name // - Message content (last message preview) // - Phone number ``` **Location:** Add to Messages header between title and buttons **API:** Client-side filtering of loaded conversations (no new endpoint needed) ### Feature 2: New Message Button (P0) **Component:** `NewMessageModal.jsx` (new) ```jsx // Two modes: // 1. Search existing leads to start conversation // 2. Enter phone number directly (creates temp lead or unmatched record) // Flow: // [+ New Message] → Modal opens // → Search leads OR enter phone // → Select lead → Opens compose view // → Type message → Send ``` **Location:** Header next to Refresh button ### Feature 3: Mark as Done (P1) **Action:** Add "Done" button to quick actions **Behavior:** - Marks conversation as "handled" (metadata.handled = true) - Removes from active filters (Hot, Waiting on Me) - Still visible in "All" filter - Can be undone **API Change:** Add `PATCH /api/sms/conversation/:leadId/handle` endpoint ### Feature 4: Unknown Number Handling (P1) **Detection:** Messages from phone numbers not linked to a lead **UI Treatment:** - Show phone number instead of name - Show "Unknown" badge - Add "+ Add as Lead" action button - Opens quick lead creation form **API Change:** Update `/api/sms/conversations/prioritized` to include unmatched conversations --- ## Implementation Plan ### Phase 1: Search (Critical - 2 steps) **Step 1:** Create SearchBar component ``` File: admin/src/components/inbox/SearchBar.jsx (NEW) Features: - Text input with Search icon - Debounced onChange (300ms) - Clear button when has value - Filters conversations prop based on query ``` **Step 2:** Integrate SearchBar into Messages.jsx ``` File: admin/src/pages/Messages.jsx Location: Line 1158 (after header title) Change: Add SearchBar component, connect to filter state ``` ### Phase 2: New Message (Critical - 3 steps) **Step 3:** Create NewMessageModal component ``` File: admin/src/components/inbox/NewMessageModal.jsx (NEW) Features: - Lead search with autocomplete - Phone number input option - Recent contacts list - Template quick-select ``` **Step 4:** Add API endpoint for lead search ``` File: src/routes/leads.js Add: GET /api/leads/search?q=query&limit=10 Returns: Matching leads with phone numbers ``` **Step 5:** Integrate NewMessageModal into Messages.jsx ``` File: admin/src/pages/Messages.jsx Location: Line 1177 (header buttons) Change: Add "+ New Message" button that opens modal ``` ### Phase 3: Mark as Done (High - 3 steps) **Step 6:** Add API endpoint for marking handled ``` File: src/routes/sms.js Add: PATCH /api/sms/conversation/:leadId/handle Body: { handled: boolean } Updates: communications.metadata.handled ``` **Step 7:** Update EnhancedConversationCard with Done action ``` File: admin/src/components/inbox/EnhancedConversationCard.jsx Location: Line 201-220 (quick actions) Change: Add Done action button to all triage configs ``` **Step 8:** Update filter logic to respect handled state ``` File: admin/src/components/inbox/InboxFilterTabs.jsx Change: Exclude handled conversations from Hot, Waiting on Me filters ``` ### Phase 4: Unknown Numbers (Medium - 2 steps) **Step 9:** Update API to include unmatched numbers ``` File: src/routes/sms.js Location: /conversations/prioritized endpoint Change: Include messages where lead_id is null ``` **Step 10:** Update UI to handle unknown numbers ``` File: admin/src/components/inbox/EnhancedConversationCard.jsx Change: Handle null lead case, show phone number, add "+ Add as Lead" action ``` ### Phase 5: Polish (Optional - 2 steps) **Step 11:** Add vertical filters for desktop ``` File: admin/src/pages/Messages.jsx Change: Add responsive sidebar with vertical filters at md+ breakpoint ``` **Step 12:** Add bulk actions ``` File: admin/src/pages/Messages.jsx Change: Add checkbox selection mode, bulk Done/Archive actions ``` --- ## Files to Create | File | Purpose | |------|---------| | `admin/src/components/inbox/SearchBar.jsx` | Search conversations | | `admin/src/components/inbox/NewMessageModal.jsx` | Compose new message | ## Files to Modify | File | Changes | |------|---------| | `admin/src/pages/Messages.jsx` | Add Search, New Message button, state for modals | | `admin/src/components/inbox/EnhancedConversationCard.jsx` | Add Done action, handle unknown numbers | | `admin/src/components/inbox/InboxFilterTabs.jsx` | Update filter logic for handled state | | `src/routes/sms.js` | Add handle endpoint, update prioritized for unknowns | | `src/routes/leads.js` | Add search endpoint | --- ## Component Designs ### SearchBar Component ```jsx // admin/src/components/inbox/SearchBar.jsx import { useState, useEffect } from 'react'; import { Search, X } from 'lucide-react'; export default function SearchBar({ onSearch, placeholder = "Search messages..." }) { const [query, setQuery] = useState(''); useEffect(() => { const timer = setTimeout(() => { onSearch(query); }, 300); return () => clearTimeout(timer); }, [query, onSearch]); return (
setQuery(e.target.value)} placeholder={placeholder} className="w-full pl-10 pr-10 py-2 bg-slate-100 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500" /> {query && ( )}
); } ``` ### NewMessageModal Component ```jsx // admin/src/components/inbox/NewMessageModal.jsx import { useState, useEffect } from 'react'; import { X, Search, Phone, User, Send, Loader2 } from 'lucide-react'; export default function NewMessageModal({ onClose, onSelectLead, onSendToPhone }) { const [mode, setMode] = useState('search'); // 'search' | 'phone' const [query, setQuery] = useState(''); const [phone, setPhone] = useState(''); const [results, setResults] = useState([]); const [loading, setLoading] = useState(false); // Search leads as user types useEffect(() => { if (mode !== 'search' || query.length < 2) { setResults([]); return; } const timer = setTimeout(async () => { setLoading(true); try { const res = await fetch(`/api/leads/search?q=${encodeURIComponent(query)}&limit=10`); const data = await res.json(); setResults(data.leads || []); } catch (e) { console.error(e); } finally { setLoading(false); } }, 300); return () => clearTimeout(timer); }, [query, mode]); return (
{/* Header */}

New Message

{/* Mode Toggle */}
{/* Content */}
{mode === 'search' ? ( <>
setQuery(e.target.value)} placeholder="Search by name, company, or phone..." className="w-full pl-10 pr-4 py-3 bg-slate-100 rounded-lg" autoFocus />
{loading && (
)} {!loading && results.map(lead => ( ))} {!loading && query.length >= 2 && results.length === 0 && (

No leads found

)}
) : ( <>
setPhone(e.target.value)} placeholder="04XX XXX XXX" className="w-full pl-10 pr-4 py-3 bg-slate-100 rounded-lg" autoFocus />
)}
); } ``` --- ## API Changes ### 1. Add Lead Search Endpoint ```javascript // src/routes/leads.js /** * GET /api/leads/search * Search leads by name, company, or phone */ router.get('/search', async (req, res) => { try { const { q, limit = 10 } = req.query; if (!q || q.length < 2) { return res.json({ leads: [] }); } const { data, error } = await supabase .from('leads') .select('id, first_name, last_name, company, phone, score, lead_type') .is('deleted_at', null) .or(`first_name.ilike.%${q}%,last_name.ilike.%${q}%,company.ilike.%${q}%,phone.ilike.%${q}%`) .order('score', { ascending: false }) .limit(parseInt(limit)); if (error) throw error; res.json({ leads: data || [] }); } catch (error) { console.error('Lead search error:', error); res.status(500).json({ error: 'Failed to search leads' }); } }); ``` ### 2. Add Handle Conversation Endpoint ```javascript // src/routes/sms.js /** * PATCH /api/sms/conversation/:leadId/handle * Mark conversation as handled/done */ router.patch('/conversation/:leadId/handle', async (req, res) => { try { const { leadId } = req.params; const { handled = true } = req.body; // Update all messages for this lead const { error } = await supabase .from('communications') .update({ metadata: supabase.raw(`COALESCE(metadata, '{}'::jsonb) || '{"handled": ${handled}}'::jsonb`) }) .eq('lead_id', leadId) .in('type', ['sms_inbound', 'sms_outbound']); if (error) throw error; // Also update lead await supabase .from('leads') .update({ conversation_handled: handled }) .eq('id', leadId); res.json({ success: true, handled }); } catch (error) { console.error('Handle conversation error:', error); res.status(500).json({ error: 'Failed to update conversation' }); } }); ``` --- ## Build Order | # | Task | File(s) | Priority | |---|------|---------|----------| | 1 | Create SearchBar component | SearchBar.jsx (new) | Critical | | 2 | Integrate search into Messages header | Messages.jsx | Critical | | 3 | Create NewMessageModal component | NewMessageModal.jsx (new) | Critical | | 4 | Add lead search API endpoint | leads.js | Critical | | 5 | Add "+ New Message" button to header | Messages.jsx | Critical | | 6 | Add handle conversation API endpoint | sms.js | High | | 7 | Add Done action to conversation cards | EnhancedConversationCard.jsx | High | | 8 | Update filters to exclude handled | InboxFilterTabs.jsx | High | | 9 | Handle unknown numbers in UI | EnhancedConversationCard.jsx | Medium | | 10 | Test on mobile viewport (390px) | Manual | Critical | | 11 | Build and deploy | npm run build | Required | --- ## Testing Checklist ### Search Tests - [ ] Search by first name finds lead - [ ] Search by last name finds lead - [ ] Search by company finds lead - [ ] Search by phone number finds lead - [ ] Search clears when X clicked - [ ] Search debounces (doesn't fire on every keystroke) ### New Message Tests - [ ] Modal opens on button click - [ ] Lead search returns results - [ ] Selecting lead opens conversation - [ ] Phone number input validates format - [ ] Modal closes after selecting ### Mark as Done Tests - [ ] Done button appears on conversation cards - [ ] Clicking Done marks as handled - [ ] Handled conversations hidden from Hot filter - [ ] Handled conversations hidden from Waiting on Me - [ ] Handled conversations still visible in All - [ ] Can undo handled state ### Mobile Tests (390px viewport) - [ ] Search bar visible and usable - [ ] New Message button visible - [ ] Modal fits on screen - [ ] All touch targets 44px+ --- ## Before/After ### Before (Current State) ``` ┌─────────────────────────────────────────────────────────────┐ │ Messages [📊] [🔄] │ │ 📡 Live • 3 unread │ │ [🔥 Hot] [⏰ Waiting on Me] [✈️ Waiting 4] [💰 Buying] [🚨] [📬]│ ├─────────────────────────────────────────────────────────────┤ │ (No search) │ │ (No new message button) │ │ (Cards have Call/Reply but no Done) │ └─────────────────────────────────────────────────────────────┘ ``` ### After (With This Plan) ``` ┌─────────────────────────────────────────────────────────────┐ │ Messages [🔍 Search...] [+] [📊] [🔄] │ │ 📡 Live • 3 unread │ │ [🔥 Hot 3] [⏰ Waiting on Me 4] [✈️ Waiting] [💰 Buying] [🚨] [📬]│ ├─────────────────────────────────────────────────────────────┤ │ 🔥 Michael McLoughlin 2 min ago│ │ "Yeah I'm interested, what's..." │ │ Contractor • 85 • stripe_ready │ │ [📞 Call Now] [💬 Quick Reply] [✓ Done] │ ├─────────────────────────────────────────────────────────────┤ │ ⏰ Dave Thompson 15 min ago│ │ "Can you call me tomorrow at 2?" │ │ Worker • 62 • profile_incomplete │ │ [📅 Schedule] [⏰ Other Time] [✓ Done] │ ├─────────────────────────────────────────────────────────────┤ │ ❓ Unknown (0412 345 678) 1 hr ago │ │ "Is this RateRight?" │ │ Not linked to lead • [+ Add as Lead] │ │ [💬 Reply] [🚫 Spam] [✓ Done] │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Notes for CC2 - **No database schema changes needed** - uses existing tables with metadata - The current Messages.jsx is 1313 lines - keep changes focused - All 8 inbox components are well-structured - minimal changes needed - API endpoints already return most needed data - Test on mobile viewport (390px) - this is the primary use case - The "handled" state uses metadata column (JSON) - no migration required - Lead search uses existing leads table with ilike queries --- ## Related Plans After this plan, consider: - `docs/messages-mobile-fix-plan.md` - Mobile input visibility (already exists) - Vertical filter sidebar for desktop (Phase 5, Step 11) - Bulk actions (Phase 5, Step 12) --- **Plan saved:** `docs/messages-ui-plan.md` **Ready for CC2:** Yes