Custom Channel Setup (BYOC) 45 min

Outcome

A working Bring Your Own Channel (BYOC) pipeline where customers on any external messaging platform can reach your Agentforce Service Agent through a partner-managed integration.

When complete, you will have:

• A BYOC Messaging Channel connected to your Salesforce org via a managed package and the Interaction Service API
• Omni-Channel routing configured to deliver inbound messages to your Agentforce agent
• Verified end-to-end message flow from the external messaging provider through to your agent and back
• Escalation routing to a human agent queue when the agent hands off

Architecture

When a customer sends a message through the external messaging platform, the message flows through the following chain:

Key metadata relationships:

• MessagingChannel.MessageType = Custom
• MessagingChannel.SessionHandlerId = BotDefinition.Id
• sessionHandlerType = AgentforceServiceAgent
• sessionHandlerAsa = BotDefinition DeveloperName
• ServiceChannel.DeveloperName = sfdc_livemessage
• Queue.SobjectType = MessagingSession

The managed package from your messaging provider handles webhook ingestion, message format translation, and delivery status callbacks. Salesforce receives normalized messages through the Interaction Service API, creates MessagingSession records, and routes them to your Agentforce agent via Omni-Channel.

Configure Your Variables

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:

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:

Verify Digital Engagement license

BYOC 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:

2. Enable Messaging and Omni-Channel

Enable the org-level settings required for BYOC messaging.

Enable Messaging in Setup

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

# Deploy Omni-Channel 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:

Verify the service channel exists

The sfdc_livemessage service channel is automatically created when Digital Engagement is enabled.

sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, MasterLabel FROM ServiceChannel WHERE DeveloperName='sfdc_livemessage' LIMIT 1"

Verify the Live Message channel:

3. Install the Provider Managed Package

Install the managed package from your external messaging or CCaaS provider. This package provides the webhook handlers, message translation logic, and Interaction Service API integration that bridges your external platform to Salesforce.

Install the managed package

# Install the managed package using the installation URL from your provider
# Replace the URL with your provider's package installation link
sf package install \
  --target-org <your-org-alias> \
  --package "{{PROVIDER_PACKAGE_ID}}" \
  --wait 10

# Verify installed packages
sf package installed list --target-org <your-org-alias>

Verify the managed package installation:

Configure the managed package

Follow your provider's configuration guide to connect the managed package to your external messaging platform. This typically involves:

# Provider configuration is typically UI-driven.
# After configuration, verify the Named Credential exists:
sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, MasterLabel, DeveloperName FROM NamedCredential WHERE DeveloperName LIKE '%{{PROVIDER_NAME}}%'"

Verify provider configuration:

4. Create the BYOC Messaging Channel

Create a Bring Your Own Channel in Salesforce Messaging Settings. This registers the channel and enables message routing through the Interaction Service API.

Create the channel via Setup

# The BYOC 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 FROM MessagingChannel WHERE MessageType='Custom'"

Verify channel was created:

Verify channel details

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

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 is active:

5. Configure Routing to Your Agent

Set up the routing so inbound BYOC messages are handled by your Agentforce Service Agent, with a fallback queue for escalation.

Create a messaging queue for fallback routing

The queue handles messages when the agent is unavailable or escalates to a human. 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:

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 BYOC 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:

Set up Omni-Channel flows for agent integration (optional)

For advanced routing, create inbound and outbound Omni-Channel flows. Your provider's managed package may include sample flows you can customize.

# Check if the provider included sample flows
sf data query \
  --target-org <your-org-alias> \
  --query "SELECT Id, MasterLabel, ProcessType FROM FlowDefinition WHERE ProcessType='Flow' AND MasterLabel LIKE '%{{PROVIDER_NAME}}%'"

6. Test and Verify

Send a test message through your external messaging platform and confirm the full pipeline works end-to-end.

Send a test message

Use the external messaging platform to send a message and verify the agent responds.

# After sending a test message from the external platform, 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:

Verify agent routing and session records

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

# Check recent MessagingSessions for the BYOC channel
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, AgentType, OwnerId, CreatedDate FROM MessagingSession WHERE MessagingChannel.MessageType='Custom' 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:

Test escalation to human agent

Verify that when the agent escalates, the conversation routes to your fallback queue.

# Send a message that triggers escalation (e.g., "I want to speak to a human")
# Then verify the session was transferred:
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, OwnerId, Owner.Name, AgentType FROM MessagingSession WHERE MessagingChannel.DeveloperName='AgentforceChannel' ORDER BY CreatedDate DESC LIMIT 1"

Verify escalation routing:

BYOC-Specific Considerations

Troubleshooting

Messages not reaching Salesforce

1. Verify the managed package is installed and configured correctly
2. Check the external provider's webhook status. The webhook must be active and pointing to your Salesforce instance
3. Confirm the MessagingChannel is Active: query IsActive field
4. Review the managed package logs (if available) for message delivery errors
5. Verify the Interaction Service API endpoint is accessible from the provider

Channel creation fails in Setup

1. Verify the Digital Engagement license is provisioned and active
2. Confirm the managed package from your provider is installed
3. Check that the managed package version is compatible with your org's API version
4. Clear browser cache and retry if the Setup wizard stalls

Agent not responding but session is created

1. Verify SessionHandlerId is set and points to the correct BotDefinition.Id
2. Check the agent is Active (not Draft) in Agent Builder
3. Verify the agent's default_agent_user has proper permissions (Einstein Agent User profile, AgentforceServiceAgentUser permission set)
4. Check for errors in the agent's trace logs via Agent Builder preview
5. Verify the BotVersion is published and active:

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"

Messages arriving but responses not reaching the external platform

1. The managed package outbound webhook may be misconfigured. Check the provider's delivery status dashboard
2. Verify the Named Credential for the external provider is valid and not expired
3. Check for API rate limits on the external provider side
4. Review Salesforce debug logs for errors in the managed package's outbound message handling

Interaction Service API errors

1. Check the API version. The Interaction Service API requires a minimum Salesforce API version
2. Verify the Connected App used by the managed package has the correct OAuth scopes
3. Review the provider's developer documentation for known issues and required API permissions
4. Test the Interaction Service API endpoint directly using the BYOC for Messaging Developer Guide

Provider managed package not appearing in channel creation

1. Confirm the package installation completed successfully (Setup > Installed Packages)
2. Some packages require post-installation configuration steps before they register as a channel provider
3. Check for package version updates that may be required for BYOC compatibility
4. Contact the provider's support for channel registration issues

Developer Resources

For custom BYOC implementations:

• BYOC for Messaging Developer Guide -- Building custom integrations using the Interaction Service API
• BYOC for CCaaS Developer Guide -- Connecting external contact centers with unified routing
• Interaction Service API Developer Guide -- API reference for message ingestion and delivery

Definition of Done

Definition of Done: