For AI agents and developers: machine-readable getting-started guide and automated Salesforce org setup (/llms.txt).

Agentforce Labs

SMS Setup

SMS Setup 30 min

Outcome

A working SMS channel where customers can text a phone number and interact with your Agentforce Service Agent in real-time.

When complete, you'll have:

  • A provisioned phone number (long code, toll-free, or short code)
  • A Messaging Channel with MessageType = Text routed to your agent
  • Omni-Channel routing configured with fallback queue
  • Verified end-to-end text message flow from phone to agent

SMS channels require the Digital Engagement add-on license. Phone numbers are provisioned through Salesforce's built-in setup wizard. Available number types: long codes (10-digit), toll-free (US/Canada), and short codes (5-6 digit, US/Canada).

Architecture

When a customer sends a text message to your provisioned phone number, the message flows through the following chain:

Click a node to jump to its configuration step.

The key routing link is SessionHandlerId on the MessagingChannel, which points directly to your agent's BotDefinition.Id. Unlike Enhanced Chat, SMS does not require an Experience Cloud site or an EmbeddedServiceConfig deployment. The MessagingChannel itself is the entry point.

The ServiceChannel for SMS messaging is sfdc_livemessage, and the queue SObject type is MessagingSession.

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 CLI access is ready.

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.

1
2
3
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.

1
2
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

SMS messaging requires the Digital Engagement add-on. Confirm it is active in your org.

1
2
sf data query --target-org <your-org-alias> \
  --query "SELECT Name, Status, ExpirationDate FROM PackageLicense WHERE NamespacePrefix='sfdc_messaging'"

Verify Digital Engagement license:

Expected result: License record returned with Status = 'Active'.

2. Enable Messaging and Omni-Channel

Turn on the org-level settings that SMS depends on.

Enable Messaging in Setup

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

1
2
3
4
5
6
# Verify Messaging is enabled
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName, IsActive FROM MessagingChannel LIMIT 1"

# If this returns an error about the object not existing,
# Messaging needs to be enabled via Setup UI (see Browser method)

Verify messaging is enabled:

Expected result: Messaging Settings page shows messaging is enabled, or MessagingChannel object is queryable.

Enable Omni-Channel

Omni-Channel handles the routing of messaging sessions to agents and queues.

1
2
3
# Check if Omni-Channel is enabled by querying ServiceChannel
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, DeveloperName FROM ServiceChannel WHERE DeveloperName='sfdc_livemessage'"

Verify service channel:

Expected result: ServiceChannel record for sfdc_livemessage exists.

3. Provision Your Phone Number

Salesforce handles the carrier relationship and number provisioning through its built-in setup wizard. No external telephony provider is needed.

Long codes are standard 10-digit phone numbers, good for low-volume conversational messaging. Toll-free numbers support higher throughput for US/Canada. Short codes (5-6 digits) are best for high-volume, mass messaging but require a longer carrier approval process (weeks to months).

Request a phone number through Salesforce Setup

1
2
3
4
# Phone number provisioning must be done through Setup UI
# After provisioning, verify the number is available:
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, MasterLabel, MessageType, MessagingPlatformKey, IsActive FROM MessagingChannel WHERE MessageType='Text'"

Short code provisioning requires carrier approval and can take 2-12 weeks. Long codes and toll-free numbers are typically provisioned within minutes. Plan accordingly if you need a short code for production.

Verify phone number provisioning:

Expected result: A phone number has been provisioned and is visible in Messaging Settings.

4. Create the SMS Messaging Channel

Configure the Messaging Channel to route incoming text messages to your 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 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
cat > queue-metadata.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'.

Configure the SMS channel to route to your agent

The Messaging Channel is the key routing component. Setting SessionHandlerId to your agent's BotDefinition.Id enables direct routing of incoming text messages to your Agentforce agent.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 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')

# If the channel was created during provisioning, update it to route to your agent
CHANNEL_ID=$(sf data query --target-org <your-org-alias> --json \
  --query "SELECT Id FROM MessagingChannel WHERE MessageType='Text' AND DeveloperName='AgentforceChannel'" \
  | jq -r '.result.records[0].Id')

sf apex run --target-org <your-org-alias> << EOF
MessagingChannel channel = [SELECT Id FROM MessagingChannel WHERE Id = '$CHANNEL_ID'];
channel.SessionHandlerId = '$BOT_ID';
channel.FallbackQueueId = '$QUEUE_ID';
channel.IsActive = true;
update channel;
System.debug('Updated MessagingChannel: ' + channel.Id);
EOF

Verify channel creation:

Expected result: MessagingChannel record returned with IsActive = true, MessageType = 'Text', and SessionHandlerId matching your BotDefinition.Id.

Verify the complete channel configuration

Confirm all routing fields are correctly set on the MessagingChannel.

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

Verify channel configuration:

Expected result: MessageType = 'Text', IsActive = true, SessionHandlerId is populated, FallbackQueueId is populated.

5. Configure Consent and Compliance

SMS messaging requires opt-in consent tracking and compliance with telecommunications regulations.

Configure consent keywords

Salesforce automatically handles standard consent keywords, but you should verify the configuration.

1
2
3
# Verify consent keywords are configured for the channel
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, MessagingChannelId, ConsentType, DoubleOptInRequired FROM MessagingChannelConsent WHERE MessagingChannel.DeveloperName='AgentforceChannel'"

TCPA Compliance is your responsibility. Salesforce auto-configures STOP/HELP keyword handling, but you must ensure your SMS usage complies with the Telephone Consumer Protection Act (TCPA) and carrier requirements. This includes maintaining proper consent records, honoring opt-out requests immediately, and only messaging customers who have given consent.

Verify consent configuration:

Expected result: Consent configuration exists for the channel with appropriate ConsentType.

6. Test and Verify

Send a test SMS and confirm the full routing chain works.

Send a test text message

Use a real phone to send a text message to your provisioned number and verify the agent responds.

1
2
3
# After sending a text message from your phone, verify the session was created
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, AgentType, OwnerId, CreatedDate, MessageType FROM MessagingSession WHERE MessageType='Text' ORDER BY CreatedDate DESC LIMIT 5"

Verify the agent responds:

Expected result: You receive a text response from the agent, and a MessagingSession record is created with MessageType = 'Text'.

Verify agent routing records

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

1
2
3
4
5
6
7
8
9
10
11
# Check recent MessagingSessions for SMS
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, Status, AgentType, OwnerId, CreatedDate, MessageType FROM MessagingSession WHERE MessageType='Text' 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"

# Verify individual messages in the session
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, MessageText, SenderType, SentDate FROM MessagingMessage ORDER BY SentDate DESC LIMIT 10"

Verify messaging session records:

Expected result: Recent MessagingSession exists with Status = 'Active' or 'Ended', MessageType = 'Text', and AgentWork record shows routing to your agent.

Test opt-out compliance

Verify that consent keywords are properly handled by the platform.

1
2
3
# After sending "STOP" from your test phone, verify opt-out was recorded
sf data query --target-org <your-org-alias> \
  --query "SELECT Id, MessagingChannelId, ConsentStatus, MessagingEndUserId FROM MessagingConsent ORDER BY LastModifiedDate DESC LIMIT 5"

Verify opt-out handling:

Expected result: Sending "STOP" triggers an automatic opt-out response, and a MessagingConsent record reflects the opt-out status.

Troubleshooting

Messages not reaching agent

  1. Verify the MessagingChannel is Active (IsActive = true)
  2. Confirm SessionHandlerId is set and points to the correct BotDefinition
  3. Check that the agent is Active (not Draft) in Agent Builder
  4. Verify the sfdc_livemessage ServiceChannel exists under Omni-Channel
  5. Ensure Digital Engagement license is active

Number provisioning delays

  • Long codes: Provisioned instantly or within minutes
  • Toll-free numbers: Usually available within minutes to hours
  • Short codes: Require carrier approval, which takes 2-12 weeks. Short codes also require a campaign use case submission to carriers. Plan for this lead time in production timelines.

Character limit and message splitting

SMS messages are limited to 160 characters per segment. Longer agent responses are automatically split into multiple segments by the carrier. To keep agent responses clean:

  1. Keep agent instructions concise to encourage shorter responses
  2. Test with longer responses to verify segment splitting is acceptable
  3. MMS (images) is supported on carriers that allow it, but adds cost per message

Opt-out compliance issues

Salesforce auto-configures these consent keywords:

  • Opt-out: STOP, CANCEL, END, QUIT, STOPALL, UNSUBSCRIBE
  • Help: HELP

If customers report they cannot opt out, verify the MessagingChannelConsent configuration and check that the channel's consent type is set appropriately for your use case.

Agent responds but messages are delayed

  1. Check Omni-Channel queue depth in the Omni-Channel Supervisor
  2. Verify the agent's response time is within acceptable bounds
  3. Carrier network latency can add 1-5 seconds to delivery
  4. If using a shared short code, high volume may cause queuing

Cannot send outbound messages to opted-in customers

Unlike channels with a 24-hour messaging window (WhatsApp, Facebook Messenger), SMS has no platform-imposed window. However, you must have valid consent from the customer. Check the MessagingConsent records and ensure ConsentStatus is not OptedOut.

Definition of Done

Definition of Done:

  • SMS channel active in Messaging Settings with MessageType = Text
  • Customer can text the provisioned phone number
  • Agent responds automatically via SMS
  • MessagingSession record created with MessageType = Text
  • Opt-out keywords (STOP) trigger automated opt-out response
  • Escalation to human agent queue works via fallback queue
  • Consent records are properly tracked in MessagingConsent