Salesforce × WhatsApp Integration via Meta Cloud API

1. Overview & Architecture

This guide walks through building a complete, production-ready WhatsApp integration inside Salesforce using the Meta WhatsApp Cloud API. The integration enables agents to send and receive WhatsApp messages directly from Lead and Contact records and also provides a standalone inbox with real-time updates via Salesforce Platform Events.

1.1 What This Integration Does

• Receive incoming WhatsApp messages via a Meta webhook into Salesforce.
• Store all incoming and outgoing messages in the WAMessage__c custom object.
• Automatically link messages to Lead or Contact records by phone number.
• Send WhatsApp messages from Salesforce using the Meta Graph API.
• Display a WhatsApp-style chat UI on Lead and Contact record pages.
• Provide a standalone WhatsApp Inbox application.
• Push real-time updates using Salesforce Platform Events and EMP API.

1.2 Architecture Diagram

Key Insight: Every incoming message follows this flow: WhatsApp User → Meta → Salesforce Webhook (Apex) → WAMessage__c → Platform Event → LWC UI. Outgoing messages follow: LWC → Apex Callout → Meta Graph API → WhatsApp User.

2. Step 1 — Meta Developer Setup

Before writing any Salesforce code, configure a Meta Developer App with WhatsApp enabled.

2.1 Create a Meta Developer Account

1. Go to developers.facebook.com.
2. Sign in using a Facebook account.
3. Complete developer registration.
4. Verify your account.

2.2 Create a Meta App

1. Open Developer Dashboard.
2. Click My Apps → Create App.
3. Select Business.
4. Enter App Name and Contact Email.
5. Create the application.

2.3 Add WhatsApp Product

1. Click Add Products.
2. Select WhatsApp.
3. Click Set Up.

2.4 Get API Credentials

2.5 Add Test Phone Number

Add a real phone number, verify it using OTP, and use it for sandbox testing.

2.6 Configure Webhook

Configure the Callback URL and Verify Token in the Meta App, verify successfully, and subscribe to the messages webhook field.

3. Step 2 — Salesforce Configuration

3.1 Create WAMessage__c Custom Object

Create a custom object to store every incoming and outgoing WhatsApp message.

3.2 Create Custom Labels

• WA_ACCESS_TOKEN
• WA_PHONE_NUMBER_ID
• WHATSAPPSECRET

3.3 Create Public Site

Create a Salesforce Site or Experience Cloud Site, activate it, and grant Guest User access to the WhatsAppWebhook Apex class.

3.4 Remote Site Settings

Add https://graph.facebook.com as a Remote Site.

3.5 Platform Event

Create WA_Message_Event__e with Message_Id__c and Customer_Phone__c fields.

4. Step 3 — WhatsAppWebhook Apex Class

This REST class handles webhook verification (GET) and incoming WhatsApp message processing (POST).

4.1 Class Annotation

@RestResource(urlMapping='/whatsapp/webhooks/v1/*')
global without sharing class WhatsAppWebhook {
}

4.2 doGet() — Webhook Verification

Meta sends a GET request during webhook configuration. Your Apex class must validate the verify token and return the hub.challenge value.

@HttpGet
global static void doGet() {
    RestRequest req = RestContext.request;
    RestResponse res = RestContext.response;
    if(req.params.get('hub.verify_token')=='mysecret2024'){
        res.responseBody = Blob.valueOf(req.params.get('hub.challenge'));
        res.statusCode = 200;
    }else{
        res.statusCode = 403;
    }
}

Note: Replace mysecret2024 with your own verification token and configure the same token in the Meta Developer Console.

4.3 doPost() — Incoming Message Processing

4.4 Helper Method — findLeadOrContact()

Create a helper method inside WhatsAppUtils that searches Contact and Lead records using the last 10 digits of the customer's phone number.

public static Id findLeadOrContact(String phone){
    // Normalize phone number
    // Search Contact
    // Search Lead
    // Return matching record Id
}

5. Step 4 — Sending Messages via Meta Graph API

5.1 WhatsAppUtils.sendTextMessage()

This method performs an HTTP POST request to the Meta Graph API and stores the outgoing message inside Salesforce.

public static WAMessage__c sendTextMessage(String content,String toPhone){
    HttpRequest req = new HttpRequest();
    req.setEndpoint('https://graph.facebook.com/v19.0/{PhoneNumberId}/messages');
    req.setMethod('POST');
    req.setHeader('Authorization','Bearer '+System.Label.WA_ACCESS_TOKEN);
    req.setHeader('Content-Type','application/json');
    // Build request body
    // Send HTTP request
    // Save WAMessage__c
}

5.2 WhatsAppLWCService

6. Step 5 — WhatsApp Chat Lightning Web Component

The WhatsAppChat Lightning Web Component provides a WhatsApp-style interface directly inside Lead and Contact record pages.

6.1 Component Files

• whatsAppChat.html
• whatsAppChat.js
• whatsAppChat.css
• whatsAppChat.js-meta.xml

6.2 JavaScript Controller Responsibilities

6.3 Component Configuration

<LightningComponentBundle>
  <apiVersion>58.0</apiVersion>
  <isExposed>true</isExposed>
  <targets>
    <target>lightning__RecordPage</target>
  </targets>
</LightningComponentBundle>

6.4 Deploy to Salesforce

1. Deploy the component using Salesforce CLI.
2. Open a Lead or Contact record.
3. Click Edit Page.
4. Drag the whatsAppChat component onto the Lightning Page.
5. Save and Activate the page.

7. Step 6 — WhatsAppInbox Standalone Lightning Web Component

The WhatsAppInbox component provides a complete WhatsApp Web-like experience inside Salesforce. It displays a conversation list on the left and the active chat window on the right, allowing agents to manage multiple customer conversations efficiently.

7.1 WhatsAppInboxService Apex Class

This Apex service powers the inbox and exposes methods for retrieving conversations and sending messages.

7.2 ConversationWrapper Class

The service returns a wrapper object containing conversation information.

public class ConversationWrapper {
    @AuraEnabled public String phone;
    @AuraEnabled public String name;
    @AuraEnabled public String initial;
    @AuraEnabled public String lastMessage;
    @AuraEnabled public String objType;
    @AuraEnabled public String recordId;
    @AuraEnabled public Boolean outgoing;
    @AuraEnabled public Integer msgCount;
    @AuraEnabled public Datetime lastDate;
}

7.3 Inbox JavaScript Features

• Loads all conversations during component initialization.
• Displays customer name, phone number and last message.
• Highlights the selected conversation.
• Loads messages dynamically.
• Groups messages by Today, Yesterday and previous dates.
• Supports client-side search.
• Refreshes automatically using Platform Events.
• Shows View Lead and View Contact links when available.

7.4 Add Inbox to Lightning App

1. Open App Manager.
2. Edit or create a Lightning App.
3. Create a new App Page.
4. Drag the whatsAppInbox component onto the page.
5. Save and Activate.
6. Add the page to the navigation menu.

8. Step 7 — Platform Events for Real-Time Updates

Platform Events allow every open Lightning component to receive new WhatsApp messages instantly without refreshing the page.

8.1 Real-Time Flow

8.2 EMP API Subscription

import { subscribe, onError } from 'lightning/empApi';

subscribe('/event/WA_Message_Event__e', -1, response => {
    // Handle incoming Platform Event
});

The replay ID -1 subscribes only to new events published after the subscription is established. Use -2 to replay retained events (available for up to 72 hours).

9. Step 8 — Testing & Deployment

Before deploying the WhatsApp integration to production, verify that every configuration has been completed correctly. This checklist helps ensure that the webhook, API authentication, Salesforce configuration, and Lightning components are functioning as expected.

9.1 Pre-Deployment Checklist

9.2 End-to-End Testing Procedure

1. Open a Lead or Contact record containing the same mobile number registered with your WhatsApp test account.
2. Send a WhatsApp message from the test phone to the business WhatsApp number.
3. Verify that Salesforce Debug Logs record the incoming webhook request.
4. Confirm that a new WAMessage__c record is created with Outgoing__c = false.
5. Verify that the Lightning chat component displays the message immediately.
6. Reply from Salesforce using the embedded chat window.
7. Confirm that the HTTP callout to Meta Graph API succeeds.
8. Verify that the customer receives the reply on WhatsApp.
9. Ensure another WAMessage__c record is created with Outgoing__c = true.

9.3 Common Issues and Solutions

10. Summary

Congratulations! You have successfully built a complete production-ready WhatsApp integration for Salesforce using the Meta WhatsApp Cloud API. The solution supports real-time messaging, automatic Lead and Contact matching, inbound webhook processing, outbound messaging, and Lightning Web Components for an intuitive chat experience.

Components Created

Future Enhancements

• Add support for image, audio, video and document messages.
• Display media previews inside Lightning Web Components.
• Implement WhatsApp Template Messages for conversations outside the 24-hour messaging window.
• Integrate Agentforce or Einstein AI for intelligent automated responses.
• Support conversation assignment to multiple support agents.
• Track delivery status, read receipts and message analytics.
• Create dashboards and reports for WhatsApp conversation metrics.
• Add Omni-Channel integration for customer support teams.