WhatsApp Setup 30 min

Outcome

A working WhatsApp-to-Agentforce pipeline where customers can message your business number and receive automated responses from your Service Agent.

When complete, you'll have:

A WhatsApp Messaging Channel connected to your Salesforce org via Meta Cloud API
Omni-Channel routing configured to send inbound messages to your Agentforce agent
Verified end-to-end message flow from WhatsApp to agent and back

WhatsApp channels require the Digital Engagement add-on license and a Meta Business Manager account with a verified WhatsApp Business phone number. Unlike Enhanced Chat, no Experience Cloud site or EmbeddedServiceConfig is needed.

Architecture

When a customer sends a WhatsApp message to your business number, the message flows through the following chain:

Click a node to jump to its configuration step.

The key routing field is sessionHandlerType = AgentforceServiceAgent on the MessagingChannel, with sessionHandlerAsa pointing to the BotDefinition DeveloperName. The sessionHandlerQueue field specifies the fallback queue when the agent is unavailable.

Unlike Enhanced Chat, WhatsApp does not require an EmbeddedServiceConfig or an Experience Cloud site. The channel is a direct integration between Meta's Cloud API and Salesforce's Messaging infrastructure.

Configure Your Variables

Update these variables with your values and they will be substituted in the code blocks below.

Salesforce org alias or username{{ORG_ALIAS}}

Service Agent developer name{{AGENT_NAME}}

Messaging Channel developer name{{CHANNEL_NAME}}

Salesforce instance URL{{INSTANCE_URL}}

OAuth access token{{ACCESS_TOKEN}}

Implementation Steps

1. Verify Your Starting Point

Confirm your agent exists, your org has the required licenses, and you have admin access.

Confirm your Service Agent exists and is active

Before building the routing chain, verify your Agentforce Service Agent is deployed and active in the target org.

sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, MasterLabel, AgentType FROM BotDefinition WHERE DeveloperName='Reservation_Agent' AND IsActive=true"

Verify the agent is active:

Expected result: One record returned with a valid Id.

If no record is returned, activate your agent in Agent Builder before proceeding.

Authenticate and verify org access

Ensure you have admin access to the target org and the CLI is connected.

sf org login web --alias <your-org-alias> --instance-url https://login.salesforce.com
sf org display --target-org <your-org-alias> --verbose

Verify org access:

Expected result: Org display shows your username and instance URL without errors.

Verify Digital Engagement license

WhatsApp channels require the Digital Engagement add-on. Confirm it is provisioned in your org.

sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, Name, Status, IsProvisioned FROM PackageLicense WHERE NamespacePrefix='sfdc_livemessage'"

Verify Digital Engagement license:

Expected result: One record returned with IsProvisioned = true.

If not found, contact your Salesforce account executive to provision Digital Engagement.

2. Enable Messaging and Omni-Channel

Enable the org-level settings required for WhatsApp messaging.

Enable Messaging in Setup

Messaging must be enabled at the org level before any messaging channels can be created.

# Deploy Messaging settings via metadata
mkdir -p force-app/main/default/settings

cat > force-app/main/default/settings/OmniChannel.settings-meta.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<OmniChannelSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableOmniChannel>true</enableOmniChannel>
</OmniChannelSettings>
EOF

sf project deploy start \
  --target-org <your-org-alias> \
  --source-dir force-app/main/default/settings/OmniChannel.settings-meta.xml

Verify messaging is enabled:

Expected result: Messaging Settings page loads without errors and shows channel management options. Omni-Channel Settings shows "Omni-Channel is enabled."

3. Set Up Meta Business and WhatsApp

Connect your Meta Business account to Salesforce and register a WhatsApp Business phone number.

The phone number you use must NOT already be registered with WhatsApp or WhatsApp Business App. It will be migrated to the WhatsApp Business Platform during setup. If the number is currently in use with WhatsApp, you must deregister it first by deleting the WhatsApp app from that phone.

Prepare your Meta Business Manager account

Before creating the WhatsApp channel in Salesforce, ensure your Meta Business environment is ready.

# Meta Business setup is UI-driven (OAuth flow between Salesforce and Meta)
# No CLI equivalent. See Browser method for complete steps.

Meta Business verification is required for production use (sending messages to customers). For development and testing, you can use a test phone number with limited messaging capabilities before completing verification.

Verify Meta Business Manager access:

Expected result: You have a Meta Business Manager account with a WhatsApp Business Account (WABA) and either a verified business or a test phone number ready.

Prepare a phone number for WhatsApp

You need a phone number that can receive SMS or voice calls for verification. This number will become your WhatsApp Business number.

# Phone number preparation is done in Meta Business Manager.
# See Browser method.

Verify phone number availability:

Expected result: You have an available phone number ready for WhatsApp Business registration.

4. Create the WhatsApp Messaging Channel

Use the Salesforce Setup wizard to create the WhatsApp channel. This wizard handles the OAuth connection to Meta and webhook registration automatically.

Create the channel via Setup wizard

The WhatsApp channel creation in Salesforce uses an embedded Meta OAuth flow. It registers webhooks, connects your WABA, and creates the MessagingChannel record.

# The WhatsApp channel must be created via the Setup wizard
# (OAuth flow between Salesforce and Meta cannot be done via CLI)
# After creation, verify with:
sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, MasterLabel, MessageType, IsActive, MessagingPlatformKey FROM MessagingChannel WHERE MessageType='WhatsApp'"

Verify channel was created:

Expected result: Query returns one record with MessageType = 'WhatsApp' and IsActive = true.

Verify channel details and note key fields

After creation, confirm the channel is properly configured with the correct platform key and message type.

sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, MasterLabel, MessageType, IsActive, MessagingPlatformKey, SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='AgentforceChannel'"

Verify channel configuration:

Expected result: Channel record returned with MessageType = 'WhatsApp', IsActive = true, and MessagingPlatformKey matching your WhatsApp Business phone number.

5. Configure Routing to Your Agent

Set up the routing so inbound WhatsApp messages are handled by your Agentforce Service Agent.

Create a messaging queue for fallback routing

The queue handles messages when the agent is unavailable. Even with direct agent routing, a fallback queue is required.

# Check if queue exists
sf data query --target-org <your-org-alias> \
  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='AgentforceChannel_Queue'"

# If not found, create via Metadata API
mkdir -p force-app/main/default/queues

cat > force-app/main/default/queues/AgentforceChannel_Queue.queue-meta.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<Queue xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>AgentforceChannel_Queue</fullName>
    <name>AgentforceChannel Queue</name>
    <queueSobject>
        <sobjectType>MessagingSession</sobjectType>
    </queueSobject>
</Queue>
EOF

sf project deploy start --target-org <your-org-alias> --metadata Queue:AgentforceChannel_Queue

Verify queue creation:

Expected result: One queue record returned with DeveloperName = '{{CHANNEL_NAME}}_Queue'.

Route the channel to your Agentforce agent

Set the SessionHandlerId on the MessagingChannel to point to your agent's BotDefinition. This enables direct agent routing for all inbound WhatsApp messages.

# Get the Bot ID and Queue ID
BOT_ID=$(sf data query --target-org <your-org-alias> --json \
  --query "SELECT Id FROM BotDefinition WHERE DeveloperName='Reservation_Agent'" \
  | jq -r '.result.records[0].Id')

QUEUE_ID=$(sf data query --target-org <your-org-alias> --json \
  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='AgentforceChannel_Queue'" \
  | jq -r '.result.records[0].Id')

CHANNEL_ID=$(sf data query --target-org <your-org-alias> --json \
  --query "SELECT Id FROM MessagingChannel WHERE DeveloperName='AgentforceChannel'" \
  | jq -r '.result.records[0].Id')

# Update the channel with agent routing
sf apex run --target-org <your-org-alias> << EOF
MessagingChannel channel = [SELECT Id FROM MessagingChannel WHERE DeveloperName = 'AgentforceChannel' LIMIT 1];
channel.SessionHandlerId = '$BOT_ID';
channel.FallbackQueueId = '$QUEUE_ID';
update channel;
System.debug('Updated MessagingChannel: ' + channel.Id + ' with SessionHandlerId: $BOT_ID');
EOF

Verify agent routing:

Expected result: Query the channel and confirm SessionHandlerId matches your BotDefinition.Id.

If SessionHandlerId is not available in your org's API version, configure routing through an Omni-Channel inbound flow instead. Create a flow with the Route Work action: Service Channel = sfdc_livemessage, Route To = your Agentforce Service Agent.

6. Test and Verify

Send a test message and confirm the full pipeline works end-to-end.

Send a test WhatsApp message

Use your personal phone to send a message to the WhatsApp Business number and verify the agent responds.

# After sending a test message from your phone, query for the session:
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, AgentType, OwnerId, CreatedDate, MessagingChannelId FROM MessagingSession WHERE MessagingChannel.DeveloperName='AgentforceChannel' ORDER BY CreatedDate DESC LIMIT 5"

Verify the agent responds:

Expected result: Agent responds to WhatsApp message. MessagingSession record created with Status = 'Active' or 'Ended'.

Verify agent routing and session records

Confirm messages are being routed to your agent by checking MessagingSession and AgentWork records.

# Check recent MessagingSessions for WhatsApp
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, AgentType, OwnerId, CreatedDate FROM MessagingSession WHERE MessagingChannel.MessageType='WhatsApp' ORDER BY CreatedDate DESC LIMIT 5"

# Check AgentWork records
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, WorkItemId, BotId, RoutingType, CreatedDate FROM AgentWork ORDER BY CreatedDate DESC LIMIT 5"

# Check individual messages in the session
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, MessageText, SenderType, CreatedDate FROM MessagingEvent WHERE MessagingSession.MessagingChannel.DeveloperName='AgentforceChannel' ORDER BY CreatedDate DESC LIMIT 10"

Verify messaging session records:

Expected result: Recent MessagingSession exists with AgentType populated and messages visible in MessagingEvent records.

WhatsApp enforces a 24-hour messaging window. After the customer's last inbound message, you have 24 hours to respond with free-form text. After that window closes, only pre-approved Message Templates (submitted and approved via Meta Business Manager) can be sent. This applies to both agent and human responses.

Troubleshooting

Messages not reaching agent

Verify the MessagingChannel is Active: query IsActive field
Confirm SessionHandlerId is set and points to the correct BotDefinition.Id
Check the agent is Active (not Draft) in Agent Builder
Verify Omni-Channel is enabled in Setup
Check that the sfdc_livemessage Service Channel exists (auto-created with Digital Engagement)

Phone number verification fails during channel creation

The number is already registered with WhatsApp. Deregister it first by deleting the WhatsApp account from the phone
The number cannot receive SMS or voice calls. Use a number that can
The verification code expired. Retry the verification step in the Setup wizard

Channel creation fails in Setup wizard

Verify the Digital Engagement license is provisioned and active
Check your Meta Business verification status at business.facebook.com
Ensure your Meta Business account has a WhatsApp Business Account (WABA) created
Clear browser cache and try in incognito mode if the OAuth popup fails
Check for browser popup blockers interfering with the Meta OAuth flow

24-hour window expired and outbound messages fail

Submit Message Templates for approval in Meta Business Manager
Use approved templates for outbound messages after the 24-hour window
Templates typically take 24-48 hours for Meta to review and approve
Customer must send a new inbound message to reopen the free-form window

WhatsApp messages arriving but agent not responding

Check SessionHandlerId versus FallbackQueueId routing. If SessionHandlerId is empty, messages route to the queue instead of the agent
Verify the agent's default_agent_user has proper permissions (Einstein Agent User profile, AgentforceServiceAgentUser permission set)
Check for errors in the agent's trace logs via Agent Builder preview

Supported message types

WhatsApp supports: text (up to 4,096 characters per message), images, documents, location sharing, and interactive messages (buttons, lists). The Agentforce agent can receive all types but responds with text by default. Rich message responses require additional configuration via Messaging Components.

Definition of Done

Definition of Done:

WhatsApp channel active in Messaging Settings with MessageType = WhatsApp
Customer can send a WhatsApp message to the business number
Agent responds to the message automatically
MessagingSession record created with correct routing to agent
Escalation to human agent queue works when agent transfers