Set up Salesforce BYOC CCaaS with Twilio SMS and WhatsApp Channels

This guide walks you through configuring Salesforce Bring Your Own Channel for Contact Center as a Service (BYOC CCaaS) with Twilio SMS and WhatsApp channels. BYOC CCaaS allows you to surface Twilio-powered messaging channels directly in Salesforce Messaging, so agents can handle SMS and WhatsApp conversations from within the Salesforce interface.

Prerequisites

Before starting, make sure you have the following:

A Flex account.
A Salesforce org with Service Cloud and Messaging enabled.
A Twilio SMS number or WhatsApp sender configured in your Twilio account.

Configure SSO for Salesforce and Flex

You need single sign-on (SSO) for both your Flex account and your Salesforce account. You can use Salesforce, Okta, or another identity provider (IdP) that supports SAML 2.0.

Follow Configure SSO for Salesforce and Flex in the Salesforce Service Cloud Voice (SCV) guide, then return to this guide.

Create credentials

For Salesforce to integrate with Twilio, you need your Twilio Account SID and Auth Token, and matching credentials in your Salesforce org.

Follow Create credentials in the SCV guide, then return to this guide. That section covers finding your Account SID and Auth Token, creating external credentials, and creating named credentials.

Install the Twilio package

Before you can create Twilio messaging channels, you must install the Twilio BYOC CCaaS managed package in your Salesforce org.

While logged in to your Salesforce org, open the Twilio BYOC CCaaS listing on Salesforce AppExchange.
Click Get It Now and select the Salesforce org where you want to install the package.
Select Install for All Users.
Expand Advanced Options and select Compile only the Apex in the package.
Click Install and wait for the installation to complete.

(warning)

Warning

When installing in a Production or Sandbox environment that already contains Apex classes, always select Compile only the Apex in the package. Using the default compilation option may cause conflicts and fail the installation.

Create and configure your Salesforce contact center

You link your Twilio messaging channels to a Partner Telephony contact center, so create the contact center before you create the channels.

Follow Create and configure your Salesforce contact center in the SCV guide, then return to this guide.

Add users to the contact center

Add the users who need to handle Twilio conversations to the contact center you created. Note that Salesforce users can only belong to one call center or contact center at a time, so you may need to remove a user from an existing call center first.

Follow Configure contact center settings in the SCV guide, then return to this guide.

Assign the Twilio Config Admin permission set

The Twilio Config tab only appears for users who have the Twilio Config Admin permission set assigned. Assign it to any user who needs to access the Twilio Config page, such as the admin completing this setup.

From the Salesforce Setup Home page, search for and select Permission Sets.
Select Twilio Config Admin.
Click Manage Assignments, then click Add Assignments.
Select the user(s) who need access to the Twilio Config page and click Assign.

Enable Messaging in Salesforce

From the Salesforce Setup Home page, search for and select Messaging Settings.
Toggle Messaging to On.

Create Twilio messaging channels

In Messaging Settings, click New Channel.
Select Bring Your Own Channel.
Because the Twilio package is installed, you will see two Twilio channel options: SMS and WhatsApp.
Select the channels you want to configure (you can select both).
Link the selected channels to the contact center you created in Create and configure your Salesforce contact center.

Create an integration user

From the Salesforce Setup Home page, search for and select Users.
Create a new user with the Salesforce API Only System Integrations profile.

Configure integration user permissions

The integration user must have the correct permissions to read and publish platform events.

Ensure the integration user created in Create an integration user has the Salesforce API Only System Integrations profile.
Edit the profile to grant it access to the platform events:
1. From the Salesforce Setup Home page, search for and select Profiles.
2. Select the Salesforce API Only System Integrations profile, then click Edit.
3. Under Platform Event Permissions, grant Read and Create access to all platform events.
4. Click Save.
From the Salesforce Setup Home page, search for and select Permission Sets.
Select the SCRT2 Integration User permission set.
Click Object Settings, then grant Read and Create access to the platform events for the channels you configured:
- Sms Events (Twilio_Scv__Sms_Event__e) — required for the SMS channel.
- Whatsapp Events (Twilio_Scv__Whatsapp_Event__e) — required for the WhatsApp channel.
If you configured both channels, grant access to both platform events. For more information, see Task 3: Assign permissions to the platform event in the Salesforce documentation.

Create an External Client App

From the Salesforce Setup Home page, search for and select App Manager.
Click New External Client App.

Fill in the Basic Information fields:

Field	Value
External Client App Name	For example, `Twilio Byoccaas`
API Name	For example, `Twilio_Byoccaas`
Contact Email	Your contact email
Distribution State	`Local`

Under App Settings, configure OAuth:
- Set Callback URL to https://login.salesforce.com.
- In Selected OAuth Scopes, add:
  - Perform requests at any time (refresh_token, offline_access)
  - Access Interaction API resources (interaction_api)
Under Flow Enablement, enable JWT Bearer Flow.
Under Certificate Upload, upload the Twilio certificate. To download the certificate:
1. From the Salesforce Setup Home page, search for and select App Manager.
2. Find Twilio for Service Cloud in the list and launch it.
3. Navigate to the Twilio Config tab. If the tab is not visible, go to App Manager, find Twilio for Service Cloud, click Edit, click Navigation Items, and add both Twilio Config and Messaging Sessions to the app's selected items. Messaging Sessions is needed so that agents can open messaging conversations in the app.
4. In the Certificate Information section, click Download Certificate.
5. Return to your External Client App and upload the downloaded certificate file.
Save the External Client App.

Add the integration profile to the External Client App

Open the External Client App you created.
Go to Policies.
Set Permitted Users to Admin approved users are pre-authorized. This is required before the profile and permission set options become available.
Under Select Profiles, add Salesforce API Only System Integrations to the Selected Profiles list.
Under Select Permission Sets, add:
- SCRT2 Integration User
- Partner Telephony Permission Set
Click Save.

Note the Consumer Key

Open the External Client App you created.
Navigate to Settings > Consumer Key and Secret.
Copy the Consumer Key. You will need it when configuring the Twilio Config page.

Activate your messaging channels

Each channel must be set to Active and linked to your External Client App. Conversations won't reach your agents until you complete this step.

From the Salesforce Setup Home page, go to Messaging Settings > Channels.
Open your Twilio SMS or WhatsApp channel.
Click Modify Conversation Channel Definition and link the channel to the External Client App you created in Create an External Client App.
Confirm that the channel's status is Active.
Repeat for each Twilio channel you created in Create Twilio messaging channels.

Get the channel identifier

From the Salesforce Setup Home page, go to Messaging Settings > Channels.
Find your Twilio SMS or WhatsApp channel.
Note down the Channel Identifier (also called the Messaging Platform Key). You will need this in the next step.

Configure the Twilio Config page

(warning)

Warning

Complete every preceding step in this guide before you configure the Twilio Config page. This page ties the whole integration together, so any step that was skipped or misconfigured earlier — such as integration user permissions, the External Client App policies and certificate, or channel activation — surfaces here as a broken integration. In that case, agent messages may never reach the customer, even though the configuration appears to save successfully.

In your Salesforce org, open the Twilio for Service Cloud app.
Navigate to the Twilio Config tab.

Complete the configuration form:

Field	Value
Consumer Key	The Consumer Key from Note the Consumer Key
Username	The integration user created in Create an integration user
Connected App API Name	The API Name of your External Client App (for example, `Twilio_Byoccaas`)

Under Select Channels, check SMS, WhatsApp, or both.
For each selected channel, enter the Channel Address Identifier you noted in Get the channel identifier.
Under Outbound Config, select the Workflow and Queue to use for outbound messages, then enter the Phone Number to send from. Copy this number from the Twilio Console (Phone Numbers > Manage > Active Numbers) and enter it in E.164 format (for example, +15017122661).
Click Save Configuration.

Enable agent-initiated outbound messaging in Salesforce

By default, agents can only reply to inbound conversations. To let agents start a new SMS or WhatsApp conversation with a customer, enable agent-initiated outbound messaging. For more information, see Send a Message to a Customer in the Salesforce documentation.

From the Salesforce Setup Home page, search for and select Permission Sets (or edit the relevant profile).
Assign the following user permissions to your agents:
- Messaging Agent
- Initiate Messaging Sessions (required for enhanced channels, which BYOC CCaaS uses)
- Access Conversation Entries
- End Messaging Session
Add the Send a Message action so it's available to reps. The Send a Message button is automatically available when messaging from the Omni-Channel widget in the Salesforce mobile app, but you must add the action to the desktop UI yourself. You can add it to the global action menu, to certain record detail pages, and to the activity timeline. Choose the location or locations that best fit your outreach process.
- Add the Send a Message action to the global action layout. This lets reps send a message from any Salesforce page.
  1. From the Salesforce Setup Home page, search for and select Publisher Layouts.
  2. Drag the Send a Message action to the Mobile and Lightning Actions section of the palette. This action is available only if you have an active enhanced Messaging or Messaging for In-App channel.
  3. Save your changes.
- Optionally, add the Send a Message quick action to your lead, contact, person account, or messaging user record page layouts. This lets reps send a message from these types of records.
- Optionally, add the Send a Message quick action to the activity timeline. This lets reps click the timeline action to send a message.

Enable messaging to new Contacts with no existing conversation (optional)

Agents can only send a message to a MessagingEndUser record, and Salesforce creates that record automatically only when a conversation first starts (for example, when the customer sends an inbound message). This means that, out of the box, agents can't send an outbound message to a Contact that has never messaged in on a channel, since no MessagingEndUser exists for them yet.

If you need to reach brand-new Contacts that have no prior conversation (for example, for proactive outreach or broadcast messaging), you must create the MessagingEndUser record yourself ahead of time. This requires custom Apex in your org, generally structured as:

A trigger on Contact (after insert) that hands off the new Contact records to a service class.
A service class that looks up your org's active MessagingChannel records and inserts a MessagingEndUser for each Contact/channel combination, using the Contact's phone number as the messaging platform key (formatted per channel, for example prefixed with whatsapp: for WhatsApp).
Logic to skip Contacts that already have a matching MessagingEndUser, so the trigger doesn't create duplicates on subsequent updates.

The following illustrates the general shape of this pattern; treat it as a starting point rather than production-ready code:

ContactAfterInsert.trigger

1trigger ContactAfterInsert on Contact (after insert) {
2    MessagingUserProvisioner.createForContacts(Trigger.new);
3}

MessagingUserProvisioner.cls

1public with sharing class MessagingUserProvisioner {
2
3    public static void createForContacts(List<Contact> contacts) {
4        List<MessagingChannel> channels = [
5            SELECT Id, DeveloperName
6            FROM MessagingChannel
7            WHERE IsActive = true
8            WITH SECURITY_ENFORCED
9        ];
10
11        List<MessagingEndUser> newEndUsers = new List<MessagingEndUser>();
12
13        for (Contact c : contacts) {
14            if (String.isBlank(c.MobilePhone)) {
15                continue;
16            }
17            for (MessagingChannel channel : channels) {
18                newEndUsers.add(new MessagingEndUser(
19                    ContactId = c.Id,
20                    MessagingChannelId = channel.Id,
21                    MessagingPlatformKey = formatKey(c.MobilePhone, channel),
22                    Name = c.Name + ' - ' + channel.DeveloperName
23                ));
24            }
25        }
26
27        if (!newEndUsers.isEmpty()) {
28            insert newEndUsers;
29        }
30    }
31
32    // Prefix with "whatsapp:" for WhatsApp channels; adjust per channel type as needed
33    private static String formatKey(String phone, MessagingChannel channel) {
34        Boolean isWhatsApp = channel.DeveloperName.containsIgnoreCase('WhatsApp');
35        return isWhatsApp ? 'whatsapp:' + phone : phone;
36    }
37}

(information)

Info

This sample omits production concerns such as phone number normalization and de-duplication against existing MessagingEndUser records — add those before using this in a live org.

(information)

Info

This is a customization built on top of the Twilio managed package, not something it provides out of the box. Have your Salesforce development team implement and test this trigger/service pattern against the MessagingEndUser and MessagingChannel objects before relying on it for proactive outreach.

Alternative: build this with a Flow instead of Apex

If you'd rather avoid custom code, you can implement the same logic with a Record-Triggered Flow instead of an Apex trigger:

Create a Record-Triggered Flow that runs After Save when a Contact is created.
Add a Get Records element to retrieve active MessagingChannel records (IsActive equals True).
Add a Loop over the retrieved MessagingChannel records.
Inside the loop, use a Formula resource to build the messaging platform key from the Contact's phone number, adding the whatsapp: prefix when the channel's DeveloperName contains WhatsApp.
Add a Create Records element inside the loop to insert a MessagingEndUser using the current Contact, the loop's MessagingChannel, and the formula value from Step 4.

Turn on messaging transfers in Twilio Console

For agents to transfer an SMS or WhatsApp conversation to another agent or to a queue, you must turn on messaging transfers in Twilio Console. Transfers are off by default.

In Twilio Console, go to Flex > Channel management > Transfers, and then click the Messaging tab.
Turn on Enable messaging transfers.
Optionally, turn on Enable messaging transfer notes to let agents send a note along with a transfer.

For more information, see Turn on messaging transfers for Conversations.

Enable After Conversation Work (ACW) for messaging

We recommend that you enable ACW for your messaging conversations.

Without ACW, an agent's capacity stays consumed until they close the conversation. The agent has to close the conversation to complete the work item and become available for the next conversation. When you enable ACW, the agent gets a defined wrap-up period after the conversation ends, and their capacity is released when the ACW timer ends.

To enable ACW, and to add the After Conversation Work component to the Messaging Session page so agents can see the ACW countdown, follow the Salesforce documentation Configure After Conversation Work Time.

Verify agent and org prerequisites

Before going live, confirm the following:

Agents have the Contact Center Bring Your Own Channel user permission set assigned.
Presence statuses (for example, Available) are added to the new channels.
Each channel is set to Active in Messaging Settings, as described in Activate your messaging channels.

Verify the setup

Once configuration is saved, log in as an agent, set your status to Available, and send a test SMS or WhatsApp message to your Twilio number. The conversation should appear in the agent's Salesforce Omni-Channel widget.

If the conversation does not appear, verify that the Enhanced Conversation component has been added to the relevant Lightning page. Open the page in the Lightning App Builder, add the Enhanced Conversation component, and save.