Messenger Setup 30 min

Outcome

By the end of this guide, your Salesforce org has:

• A Facebook Messenger channel connected to your Facebook Page.
• Omni-Channel routing delivering Messenger conversations to your Agentforce Service Agent.
• A verified end-to-end flow: customer messages your Page, agent responds automatically in Messenger.
• SOQL evidence confirming MessagingSession creation and agent assignment.

Architecture

Key metadata relationships:

• MessagingChannel.MessageType = Facebook
• MessagingChannel.MessagingPlatformKey = Facebook Page ID
• ServiceChannel.DeveloperName = sfdc_livemessage
• Queue.SobjectType = MessagingSession
• ConsentType = ImplicitOptIn (user initiates by messaging your Page)

Configure Your Variables

Prerequisites

• Salesforce CLI (sf) installed.
• Admin-level access in the target Salesforce org.
• Digital Engagement license provisioned on the org.
• A published, active Agentforce Service Agent (example: {{AGENT_NAME}}).
• A Facebook Page where you are a Page admin.
• A Meta Business Manager account (business.facebook.com).

Step 1: Set Environment Variables and Authenticate

Set org alias, agent name, channel details, and queue name; then authenticate with the CLI.

Use these defaults or replace with your own values.

export ORG_ALIAS="MY_ORG"
export API_VERSION="65.0"

export AGENT_NAME="Support_Agent"

export CHANNEL_DEV_NAME="Facebook_Messenger_Channel"
export CHANNEL_LABEL="Facebook Messenger Channel"

export QUEUE_DEV_NAME="Messenger_Queue"
export QUEUE_LABEL="Messenger Queue"

# Authenticate and verify
sf org login web --alias "$ORG_ALIAS" --instance-url https://login.salesforce.com
sf org display --target-org "$ORG_ALIAS" --verbose --json

Step 2: Enable Messaging and Omni-Channel

Confirm that Messaging and Omni-Channel are enabled in your org's Setup.

Both Messaging and Omni-Channel must be enabled before you can create a Facebook Messenger channel.

A. Enable Messaging

1. Navigate to Setup > Messaging Settings.
2. Toggle Messaging to On if not already enabled.

B. Enable Omni-Channel

1. Navigate to Setup > Omni-Channel Settings.
2. Toggle Enable Omni-Channel to On if not already enabled.

C. Verify the service channel exists

sf data query \
  --target-org "$ORG_ALIAS" \
  --query "SELECT Id,DeveloperName,MasterLabel FROM ServiceChannel WHERE DeveloperName='sfdc_livemessage' LIMIT 1"

Verify the Live Message channel is set up:

Step 3: Set Up Meta Business and Facebook Page

Prepare your Meta Business Manager account, Facebook Page, and Meta App for the Messenger integration.

This step is performed entirely in Meta's platforms. Salesforce handles webhook registration automatically when you connect the channel in Step 4.

A. Verify Meta Business Manager

1. Go to business.facebook.com.
2. Confirm you have an active Meta Business Manager account.
3. If not, create one and complete business verification.

B. Confirm Your Facebook Page

1. In Meta Business Manager, go to Business Settings > Accounts > Pages.
2. Confirm you have a Facebook Page and that you are a Page admin.
3. Note the Page ID (visible in Page Settings > Page transparency, or in the URL).

C. Create a Meta App (if not already done)

1. Go to developers.facebook.com.
2. Click Create App and select a Business type.
3. Add the Messenger product to your app.
4. Link your Facebook Page to the app under Messenger > Settings.

Step 4: Create the Messenger Channel

Connect your Facebook Page to Salesforce via Setup and configure routing to your agent.

A. Create the Channel via Setup UI

1. Navigate to Setup > Messaging Settings.
2. Click New Channel.
3. Select Facebook Messenger as the channel type.
4. Salesforce initiates an OAuth flow to Meta. Log in with your Facebook credentials and authorize access to your Page.
5. Select the Facebook Page you want to connect.
6. Complete the wizard. Salesforce automatically registers the webhook with Meta.

B. Configure Agent Routing on the Channel

1. In Setup > Messaging Settings, click into your new Messenger channel.
2. Under Routing, set:
   • Session Handler Type: AgentforceServiceAgent
   • Session Handler: Select your agent ({{AGENT_NAME}})
3. Set a Fallback Queue (for escalation when the agent hands off to a human).
4. Save and activate the channel.

C. Verify the Channel via CLI

sf data query \
  --target-org "$ORG_ALIAS" \
  --query "SELECT Id,DeveloperName,IsActive,MessageType,MessagingPlatformKey,SessionHandlerId,FallbackQueueId FROM MessagingChannel WHERE DeveloperName='$CHANNEL_DEV_NAME' LIMIT 1"

Verify the Messenger channel is configured:

D. Create or Verify the Queue (if not done via UI)

If the wizard did not create a fallback queue, create one manually:

# Check if queue exists
sf data query \
  --target-org "$ORG_ALIAS" \
  --query "SELECT Id,Name,DeveloperName FROM Group WHERE Type='Queue' AND DeveloperName='$QUEUE_DEV_NAME' LIMIT 1"

Step 5: Configure Routing to Your Agent

Ensure Omni-Channel routes Messenger conversations to your Agentforce agent with a fallback queue for escalation.

If you already set the Session Handler in Step 4B, this step confirms the routing path. If your org requires flow-based routing instead of direct SessionHandlerId, configure it here.

Direct Routing (Preferred)

Direct routing uses SessionHandlerId on the MessagingChannel to point to your BotDefinition. This was configured in Step 4B.

Verify the agent identity:

sf data query \
  --target-org "$ORG_ALIAS" \
  --query "SELECT Id,DeveloperName,MasterLabel,AgentType FROM BotDefinition WHERE DeveloperName='$AGENT_NAME' LIMIT 1"

Flow-Based Routing (Fallback)

If your org does not support SessionHandlerId on MessagingChannel, use an Omni-Channel inbound flow:

1. Navigate to Setup > Flows.
2. Create a new Record-Triggered Flow or Omni-Channel Flow that:
   • Triggers on MessagingSession creation.
   • Evaluates channel type = Facebook.
   • Routes to your agent queue.
3. Assign the flow to the Messaging Channel routing configuration.

Step 6: Test and Verify

Send a test message to your Facebook Page and confirm the agent responds.

A. Send a Test Message

1. Open Facebook Messenger (web or mobile app).
2. Search for your Facebook Page name.
3. Send a message such as: "Hi, I need help with my order."

B. Verify MessagingSession Creation

sf data query \
  --target-org "$ORG_ALIAS" \
  --query "SELECT Id,Status,AgentType,OwnerId,CreatedDate,MessageType FROM MessagingSession ORDER BY CreatedDate DESC LIMIT 5"

C. Verify AgentWork Assignment

sf data query \
  --target-org "$ORG_ALIAS" \
  --query "SELECT Id,WorkItemId,BotId,RoutingType,CreatedDate FROM AgentWork ORDER BY CreatedDate DESC LIMIT 5"

D. Verify Agent Response in Messenger

Return to the Messenger conversation. Confirm that your Agentforce agent responded to the test message.

Verify the agent responds in Messenger:

Messenger-Specific Constraints

Troubleshooting

Messages not reaching Salesforce

Check the following:

1. In the Meta App dashboard (developers.facebook.com), navigate to Messenger > Settings > Webhooks. Confirm a webhook is registered and pointing to your Salesforce instance.
2. In Salesforce, verify the Messenger channel is Active in Setup > Messaging Settings.
3. Confirm the Facebook Page is linked to the Meta App and that the pages_messaging permission is authorized.
4. Test with a user who is a Page admin or listed as a tester in the Meta App.

Cannot connect Facebook Page during channel creation

Verify:

1. You are logged into Facebook as a Page admin (not just a Page editor).
2. Your Meta Business Manager account has completed business verification.
3. The Facebook Page is claimed by your Meta Business Manager account (Business Settings > Accounts > Pages).
4. Your browser is not blocking the OAuth popup from Meta.

App Review pending - limited testing

Until your Meta App passes App Review for pages_messaging:

1. Only Page admins, developers, and testers can interact with the agent via Messenger.
2. Add test users in the Meta App dashboard: App Roles > Testers.
3. Each tester must accept the invitation before they can message.
4. Submit for App Review early as it can take days to weeks. Include screenshots of your Messenger integration and describe the use case clearly.

24-hour messaging window expired

After 24 hours from the customer's last message:

1. Standard replies are blocked by Meta.
2. Use message tags for permitted follow-up categories only: CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE.
3. Design your agent's escalation flow to resolve conversations within the 24-hour window.
4. Consider sending a proactive "Is there anything else?" message before the window closes.

Agent not responding but session is created

1. Verify the BotDefinition is published and the active BotVersion is correct:

sf data query --target-org "$ORG_ALIAS" --query "SELECT Id,DeveloperName,Status FROM BotVersion WHERE BotDefinition.DeveloperName='$AGENT_NAME' AND Status='Active' LIMIT 1"

2. Check that the SessionHandlerId on the MessagingChannel matches the BotDefinition Id.
3. Review agent debug logs in Setup > Agentforce > Agents > [Your Agent] > Logs.

Definition of Done

Definition of Done: