Apple Messages Setup 30 min

Outcome

A working Apple Messages for Business pipeline where customers on iPhone, iPad, or Mac can message your business and receive automated responses from your Agentforce Service Agent.

When complete, you will have:

An Apple Messages for Business channel connected to your Salesforce org
Omni-Channel routing configured to send inbound iMessage conversations to your Agentforce agent
Verified end-to-end message flow from Apple Messages to agent and back

Apple Messages for Business channels require the Digital Engagement add-on license and an approved Apple Business Register account (register.apple.com/business). Unlike Enhanced Chat, no Experience Cloud site or EmbeddedServiceConfig is needed. Apple Messages only works on Apple devices (iPhone, iPad, Mac) via the iMessage protocol.

Architecture

When a customer sends a message to your business through Apple Maps, Safari, Spotlight, or Siri, 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, Apple Messages does not require an EmbeddedServiceConfig or an Experience Cloud site. The channel is a direct integration between Apple's Business Chat infrastructure and Salesforce's Messaging platform. Salesforce handles the webhook registration during channel setup.

Key metadata relationships:

MessagingChannel.MessageType = AppleBusinessChat
ServiceChannel.DeveloperName = sfdc_livemessage
Queue.SobjectType = MessagingSession
No 24-hour messaging window (unlike WhatsApp/Messenger) -- Apple allows ongoing conversations

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

Apple Messages for Business 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 Apple Messages for Business.

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. Register with Apple Business Register

Before creating the channel in Salesforce, you must register your business with Apple and get your account approved.

Apple reviews and approves every business account. The approval process can take days to weeks depending on your business type and verification requirements. Start this step early. You cannot create the Salesforce channel until Apple approves your account.

Create your Apple Business Register account

# Apple Business Register setup is browser-based.
# No CLI equivalent. See Browser method for complete steps.

Apple provides test capabilities during the review process. You can use the Apple Business Chat sandbox to test your integration before going live. Ask your Apple Business representative about sandbox access.

Verify Apple Business Register access:

Expected result: You have an approved Apple Business Register account with Salesforce selected as your Messaging Service Provider.

Configure entry points for your business

Entry points determine how customers discover and start conversations with your business on Apple devices.

# Entry point configuration is managed in Apple Business Register.
# See Browser method.

Verify entry point configuration:

Expected result: You have identified and configured at least one entry point for customers to reach your business via Apple Messages.

4. Create the Apple Messages Channel in Salesforce

Use the Salesforce Setup wizard to create the Apple Messages for Business channel. Salesforce handles the webhook connection to Apple automatically during setup.

Create the channel via Setup wizard

# The Apple Messages channel must be created via the Setup wizard.
# After creation, verify with:
sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, MasterLabel, MessageType, IsActive, MessagingPlatformKey FROM MessagingChannel WHERE MessageType='AppleBusinessChat'"

Verify channel was created:

Expected result: Query returns one record with MessageType = 'AppleBusinessChat' 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 = 'AppleBusinessChat', IsActive = true, and MessagingPlatformKey matching your Apple Business Chat Account ID.

5. Configure Routing to Your Agent

Set up the routing so inbound Apple Messages conversations 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 Apple Messages conversations.

# 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 message via Apple Messages

Use an Apple device (iPhone, iPad, or Mac) to send a message to your business and verify the agent responds.

# After sending a test message from your Apple device, 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"

Apple Messages for Business only works on Apple devices. You cannot test from Android phones or non-Apple computers. Ensure your test device is running a recent version of iOS, iPadOS, or macOS.

Verify the agent responds:

Expected result: Agent responds to Apple Messages conversation. 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 Apple Messages
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, AgentType, OwnerId, CreatedDate FROM MessagingSession WHERE MessagingChannel.MessageType='AppleBusinessChat' 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.

Apple Messages-Specific Capabilities

Apple Messages for Business supports rich interactive content beyond plain text:

Capability	Description
List Pickers	Present a scrollable list of options for the customer to select from
Time Pickers	Let customers choose an available appointment time slot
Apple Pay	Request payments directly within the conversation
Authentication	Verify customer identity using Apple's authentication framework
Custom Interactive Messages	Build custom iMessage app extensions for rich UI experiences
Secure Forms	Collect structured data securely within the conversation
Images and Attachments	Send and receive images, documents, and other media

Rich interactive content (list pickers, time pickers, Apple Pay) requires additional configuration via Messaging Components in Salesforce. Start with text-based conversations and add rich content incrementally.

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)

Apple Business Register account not approved

Apple reviews every business account manually. Typical approval timelines:
- Established brands with verified web presence: 2-5 business days
- New or small businesses: 1-3 weeks
- Businesses requiring additional verification: up to 4 weeks
Ensure your business information on register.apple.com matches your public web presence
Verify your D-U-N-S number is correct if Apple requests business verification
Contact Apple Business support if approval is delayed beyond expected timelines

Channel creation fails in Setup wizard

Verify the Digital Engagement license is provisioned and active
Confirm your Apple Business Register account is approved and shows Active status
Ensure Salesforce is selected as the Messaging Service Provider in Apple Business Register
Check that your Apple Business Chat Account ID is correct
Clear browser cache and retry if the Setup wizard encounters errors

Customer cannot find your business in Apple Maps or Safari

Verify your business location is claimed and verified on Apple Maps Connect (mapsconnect.apple.com)
Ensure your Apple Business Register account entry points include Maps and Safari
It can take 24-48 hours after channel activation for entry points to appear in Apple services
Check that your business name and address match between Apple Maps Connect and Apple Business Register

Agent not responding but session is created

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
Confirm the BotDefinition is published and the active BotVersion is correct:

sf data query --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, Status FROM BotVersion WHERE BotDefinition.DeveloperName='Reservation_Agent' AND Status='Active' LIMIT 1"

Definition of Done

Definition of Done:

Apple Messages channel active in Messaging Settings with MessageType = AppleBusinessChat
Customer can message your business from an Apple device (Maps, Safari, Spotlight, or Siri)
Agent responds to the message automatically via iMessage
MessagingSession record created with correct routing to agent
Escalation to human agent queue works when agent transfers