WhatsApp Integration in Salesforce

1. Abstract

This document covers the standalone WhatsApp Inbox component and its service layer. Where Part 1 focused on the inbound webhook and the record-page chat widget, this document covers the two-panel WhatsAppInbox LWC that shows all conversations in one place, the WhatsAppInboxService Apex controller that powers it, and the shared WhatsAppUtils utility class used across the integration.

Components Covered

• WhatsAppInbox LWC — two-panel inbox showing all conversations and message threads
• WhatsAppInboxService — Apex controller with 5-step conversation aggregation
• WhatsAppUtils — shared send and phone-lookup methods used by all classes
• Known limitations — security gaps, SOQL governor risks, performance notes

2. Solution

2.1 WhatsAppInbox — Two-Panel Layout

WhatsAppInbox is a standalone LWC placed on any App Builder page. It has two panels side by side: a fixed 360px left panel listing all conversations, and a flex-grow right panel showing the selected message thread. The design mirrors WhatsApp Web.

2.2 Tracked State

2.3 Client-Side Search

handleSearch() filters filteredConversations in memory — no additional Apex call. Checks both name and phone, case-insensitively. Clearing the input restores the full list.

2.4 Date Separators in the Thread

When messages load, _groupByDate() injects synthetic separator objects between groups from different calendar days. These carry isDateSeparator: true and a human-readable dateLabel: 'Today', 'Yesterday', or DD Month YYYY in en-IN locale. Incoming message bubbles are wrapped in a template if:false={msg.isDateSeparator} guard to prevent the component from trying to render fields that don't exist on a separator object.

2.5 Real-Time Updates via Platform Events

_subscribeEvents() subscribes to /event/WA_Message_Event__e from position -1 on load. On every inbound event:

• loadConversations() always runs to refresh the left-panel preview text and timestamp.
• If the event phone's last 10 digits match activeChatPhone, _loadMessages() reloads the full right-panel thread.

2.6 Deep-Link to the CRM Record

When activeChatRecordId is populated, the chat header shows an anchor tag with href = '/' + activeChatRecordId and target='_blank'. This lets agents jump directly to the Lead or Contact without leaving the inbox. The link is hidden when no matching record was found.

2.7 Time Formatting

2.8 WhatsAppInboxService — Apex Controller

Controller for WhatsAppInbox. Three AuraEnabled methods and an inner wrapper class.

getAllConversations() — 5-Step Pipeline

Returns one ConversationWrapper per unique CustomerPhone__c, sorted by most recent message.

getMessagesByPhone(phone)

Returns up to 200 WAMessage__c records using the last-10-digit LIKE pattern, ordered by CreatedDate ASC. The 200-record cap should be revisited for long-lived conversations — cursor-based pagination is the right long-term solution.

sendMessage(phone, content)

Thin wrapper around WhatsAppUtils.sendTextMessage(content, phone). Uses parameter names phone and content rather than toPhone and messageContent as in WhatsAppLWCService, but the behaviour is identical.

ConversationWrapper Inner Class

2.9 WhatsAppUtils — Shared Methods

sendTextMessage(messageContent, toPhone)

Builds and sends an outbound WhatsApp message via the Meta Graph API. Steps in sequence:

1. Read the WhatsApp Phone Number ID and Bearer token from Named Credential or Custom Label.
2. Build JSON: { messaging_product: 'whatsapp', recipient_type: 'individual', to: toPhone, type: 'text', text: { preview_url: false, body: messageContent } }
3. Set Authorization and Content-Type: application/json headers.
4. On HTTP 200 — insert WAMessage__c (Outgoing__c = true) and return the record.
5. On failure — throw exception with HTTP status and response body for the caller to surface.

findLeadOrContact(phone)

Strips non-numeric characters, takes the last 10 digits, and queries Contact (by MobilePhone and Phone) then non-converted Lead (same fields). Returns the Salesforce Id of the first match, or null. The webhook calls this after inserting WAMessage__c to populate Lead__c or Contact__c.

3. Step-by-Step Guide

3.1 Using WhatsAppInbox

6. Open the Lightning App Builder. Drag the whatsAppInbox component onto any App page. Save and Activate.
7. Navigate to the page. The left panel loads all conversations showing name, last message preview, and timestamp.
8. Type in the search box to filter by name or phone. The filter runs in memory — no server call. Clear the field to restore the full list.
9. Click any conversation row. The right panel loads the thread with date separators (Today / Yesterday / DD Mon). A 'View [Lead/Contact]' link appears in the header if a record is linked.
10. Type in the footer textarea and press Enter to send a reply. Shift+Enter inserts a line break. The sent message appears immediately and the conversation list refreshes.
11. New inbound messages arrive automatically via Platform Event. Both the conversation list and the open thread update without a page reload.

3.2 Applying the Recommended Fixes

4. Conclusion

4.1 Summary

WhatsAppInbox provides a familiar two-panel inbox experience directly inside Salesforce, with client-side search, date-grouped threads, and one-click navigation to the linked CRM record. The underlying service layer handles complex name resolution across multiple fallback levels. The items below should be addressed before deploying to large production orgs.

4.2 Strengths

• Two-panel inbox mirrors WhatsApp Web — immediately familiar to agents
• Client-side search is fast with no additional Apex calls
• Date separators make long threads readable
• Deep-link to Lead or Contact from within the inbox
• getAllConversations resolves names at three fallback levels: linked record, message field, direct CRM lookup
• Real-time updates via Platform Events — no page refresh needed

4.3 Areas to Improve

• getAllConversations() Step 4 queries all Contacts and Leads — SOQL governor limit risk at scale
• Full message reload on every Platform Event — not efficient at high volume
• getMessagesByPhone() hard-capped at 200 records — needs cursor-based pagination
• Inbound media stored as placeholder strings — no download from Meta media API
• No pagination in the current implementation
• Bearer token in Custom Label should move to Named Credential

5. Screenshots & Visual Reference

5.1 WhatsAppInbox — Two-Panel Layout Description

5.2 Platform Event Flow — Text Diagram

Inbound message arrives
  → WhatsAppWebhook.doPost()
  → upsert WAMessage__c
  → WhatsAppUtils.findLeadOrContact() → update Lead__c / Contact__c
  → insert WA_Message_Event__e
  → empApi subscription (LWC)
      → WhatsAppChat._handleEvent()
          → getSingleMessage() → append to messages[]
      → WhatsAppInbox._handleEvent()
          → loadConversations() (always — refreshes left panel)
          → _loadMessages() (only if active phone matches)

5.3 Full Component Quick Reference