Bring Your Own Channel (BYOC) is a new way for Fin customers to enable Fin Messenger as their live-chat AI Agent. Connecting via BYOC rather than Enhanced Chat brings improvements in the way that the messenger handles certain user behaviours, such as concurrent conversations across multiple tabs, so that you can continue to enjoy Fin's best-in-class service. Migration is simple, making use of test environments before rolling out to production without causing any downtime. Follow the guide below to implement on your workspace.

Use this article to upgrade your existing Fin for Salesforce connection to use the new External Client App (ECA). This guide is for Salesforce admins migrating an existing Fin for Salesforce deployment — you'll need Salesforce admin access and an active Fin for Salesforce subscription. By the end, you'll have installed the required managed packages, connected via the new ECA, configured permissions, and — if you use Fin Messenger — established a live-chat connection between Fin and Salesforce via Bring Your Own Channel (BYOC), Salesforce's standard channel integration framework for connecting third-party messaging providers.

There are 6 steps involved:

Connect to Salesforce via the External Client App
Set up permissions
Switch to using External Client App credentials
Run the Apex migration script
Uninstall the deprecated package and disconnect the Connected App
Update your Fin Messenger deployment [optional]

Note: If you're setting up Fin to handle Salesforce cases only (no messaging), you can skip the Updates to Fin Messenger section below.

Step 1: Connect to Salesforce via the External Client App

Go to Connect in your Fin workspace, then click on the Bring Your Own Channel tab.

This serves as the migration tab for moving to the new External Client App (ECA) — an OAuth 2.0 client credentials-based authentication method that replaces the legacy Connected App (an older OAuth-based integration that required storing user credentials).

You will see your existing connections listed as Not Connected in this tab. The connection status is with respect to the External Client App.

The Bring Your Own Channel tab in the Fin Connect page, showing existing Salesforce connections listed with a status of 'Not Connected' under the External Client App column.

Follow the steps below to install a managed package in Salesforce. The managed package installs the External Client App, plus all the permissions and fields Fin needs to run.

Click the Connect button, on any existing connection you want to connect (test or live), then click Install Package.
Select Install for all users. This means the permission set can be assigned to any user in your Salesforce org if you choose.
Wait for the installation to finish. No errors should be shown.
Once installation is complete, return to the Connect page and click the Connect to Salesforce button in Step 2, then allow the connection to establish.

The Install Package dialog in Fin with 'Install for all users' selected, and the 'Connect to Salesforce' button visible in Step 2 of the connection setup.

Step 2: Set up permissions

Go to Connect > Bring Your Own Channel (Tab) > Assign permissions in Salesforce from your Fin workspace and follow the steps there to create a new permission set and assign all the permissions Fin needs to run.

Create a new permission set

In Salesforce, create a new permission set. The label and API name can be anything — this permission set will only be assigned to the integration user.
When selecting a license, make sure to choose one that includes the Set Audit Fields upon Record Creation permission, for example, the Salesforce license. Some licenses don't include this permission.
Save the new permission set.

The Salesforce New Permission Set screen, showing the License dropdown set to 'Salesforce' — the license type that includes the required 'Set Audit Fields upon Record Creation' permission.

Note: Not all Salesforce license types include the Set Audit Fields upon Record Creation permission. If this option isn't available for a license you're considering, select a different license type (such as the standard Salesforce license) that does include it.

Assign permission sets to the integration user

Both the existing Fin for Salesforce permissions permission set and the newly created permission set must be assigned to the integration user.

In Salesforce, navigate to the integration user's profile.
Go to Permission Set Assignments and click Edit Assignments.
Add both the Fin for Salesforce permissions permission set and the newly created permission set to the Enabled Permission Sets column, then click Save.

The Salesforce Permission Set Assignments screen for the integration user, showing both 'Fin for Salesforce permissions' and the newly created permission set moved into the Enabled Permission Sets column.

Step 3: Switch to using External Client App credentials

You can switch to using the External Client App credentials for a Salesforce connection by toggling the Use External Client App credentials when managing a connection under Connect > Bring Your Own Channel (Tab).

Once switched on, Fin uses the External Client App credentials for all its requests to Salesforce, including:

Queries to get the status of the connection.
Creating a Salesforce case via the workflow step.
Creating a Salesforce case on Fin resolution or user inactivity.
Responding to case created via the Salesforce cases channel
Importing Knowledge articles
Importing historical Salesforce cases

The Fin Connect page showing the 'Use External Client App credentials' toggle in the enabled position for a Salesforce connection, with a confirmation banner indicating the switch was successful.

Once switched on, you can switch it back off if you believe something is amiss. This lets you test in each environment — sandbox, UAT (user acceptance testing), and production — and gain confidence with the new ECA credentials, without disrupting the legacy Connected App credentials.

Once all connections have Use External Client App credentials switched on, the migration is complete. The connection status for each entry updates to Connected in the Bring Your Own Channel tab. Follow the steps below to migrate your data and clean up the deprecated package once you're satisfied that all systems are working as intended.

Step 4: Run the Apex migration script

When you install the Fin for Salesforce base managed package, it installs new Fin Case fields that are namespaced with finai. Namespacing means each field name is prefixed with finai__ (for example, finai__FinConversationId__c) to prevent naming conflicts with other packages or custom fields in your org.

As part of the migration, use the Apex migration script to move your existing case data from the older unnamespaced fields to the new namespaced fields. The Fin for Salesforce package includes a pre-built Apex class called FinCaseFieldMigrator.cls that handles the migration logic.

Apex inside a managed package resolves unqualified custom field names against its own namespace. A query for FinConversationId__c executed inside the finai package returns finai__FinConversationId__c instead, so packaged code cannot read the legacy fields at all, and naming both in one query fails outright with a duplicate field selected error. The migration fetch must therefore be executed from outside the package — that is why the class below must be created manually in your org. The class itself holds no migration logic; it calls the migration class installed by the managed package and runs it in batches of 200 records at a time.

public without sharing class FinCaseFieldMigration implements Database.Batchable<SObject>, Database.Stateful {

    private final finai.FinCaseFieldMigrator migrator;

    public FinCaseFieldMigration() {
        this.migrator = new finai.FinCaseFieldMigrator();
    }

    public static Id run() {
        return run(200);
    }

    public static Id run(Integer scopeSize) {
        if (scopeSize == null || scopeSize < 1 || scopeSize > 2000) {
            throw new IllegalArgumentException('scopeSize must be between 1 and 2000, got: ' + scopeSize);
        }
        return Database.executeBatch(new FinCaseFieldMigration(), scopeSize);
    }

    public Database.QueryLocator start(Database.BatchableContext bc) {
        return Database.getQueryLocator(migrator.queryString());
    }

    public void execute(Database.BatchableContext bc, List<SObject> scope) {
        migrator.migrate(scope);
    }

    public void finish(Database.BatchableContext bc) {
        migrator.report(bc.getJobId());
    }
}

Setup the FinCaseFieldMigration Apex class

Go to Salesforce setup > Apex Classes.
Click on New, Paste in the class declared above.
Click Save. The class appears in your Apex Classes list as FinCaseFieldMigration. If any errors are shown, check that the class was pasted in full and that your org has Apex enabled.

Run the FinCaseFieldMigration Apex class

Go to Salesforce setup > Developer Console
Click on Debug > Open Execute Anonymous Window

Paste in the code below

Id jobId = FinCaseFieldMigration.run();
System.debug('Fin Case field migration job: ' + jobId);

Click Execute
Once complete the Salesforce User that triggered the job via the Developer console should receive an email titled Fin for Salesforce — Case field migration finished and it should have details around the number of Salesforce cases affected from the migration.

Step 5: Uninstall the deprecated package and disconnect the Connected App

Once the new managed package is installed, all connections are switched to the ECA credentials, and the Fin Case field data has been migrated to the new namespaced fields, uninstall the previous unlocked or unmanaged package and revoke the legacy Connected App connection.

Unassign legacy PermissionSet

The legacy PermissionSet (a Salesforce object that grants users access to specific features and fields) must be unassigned before the package can be uninstalled.

Go to Salesforce setup > Installed Packages
Click on the Fin for Salesforce unlocked package
Click on View Components
Click on the Fin_for_Salesforce_permissions PermissionSet, this should take you to the PermissionSet page.
Click on Manage Assignments
Select all assigned Salesforce Users
Click the Remove Assignment button

Uninstall package and save data

Go to Salesforce setup > Installed Packages
Click on Uninstall beside the Fin for Salesforce unlocked package
Select Save a copy of this package's data for 48 hours after uninstall this will save all the case field data as a csv with a column for the Salesforce Case ID.
Important: Salesforce retains the saved data export for 48 hours only after uninstallation. Download the CSV before that window closes. If you've already run the Apex migration script successfully, you won't need to restore from this file — but it's a useful safety net.
Wait to get notified that the package uninstallation has been complete successfully.
Revisit Salesforce setup > Installed Packages, you should see the uninstalled package listed under Uninstalled Packages.
Click Data, this will download all the Case data as a csv stored within a zip file. Store this zip file safely as you could use it to restore data if required. But if you've run the Apex migration script you should be good to go.

Revoke Connected App connection

Go to Salesforce setup > Connected Apps OAuth Usage
Click on number link listed below the User Count column for the Fin for Salesforce Connected App. It will redirect you to Connected App User's Usage.
Click Revoke next to each user listed. This removes the OAuth access tokens stored as part of the legacy Connected App connection. Once revoked, those users no longer appear in the list.

Step 6: Update your Fin Messenger deployment

Follow these steps only if you intend on using Fin for Salesforce with Messaging.

This section explains how to connect Fin as a Bring Your Own Channel (BYOC) partner in Salesforce, and how to migrate existing Enhanced Chat handoff workflows to use BYOC instead.

Connect Fin to Bring Your Own Channel

To establish the BYOC connection between Fin and Salesforce, follow Step 1 of the Fin Messenger: Setting up with Salesforce article. That step walks you through creating a Messaging Channel, configuring the Event Relay, and activating the channel in Salesforce.

Once complete, you should have an active Messaging Channel with a running Event Relay — a Salesforce feature that streams real-time platform events, used here to pass messages between Fin and Salesforce — between Fin and Salesforce.

Hand-off to Salesforce agent

The Hand-off to Salesforce agent step in Fin Messenger workflows now supports toggling between BYOC and Enhanced Chat. This lets you control which channel the handoff uses while testing, so you can switch gradually without downtime.

You can create multiple workflows with different audience & environment targeting to control what traffic goes through BYOC

Or you could leverage the Branches step in workflows with the Environment variable to direct it to a Hand-off to Salesforce agent step with BYOC turned on vs one with BYOC turned off (i.e Enhanced Chat)

FAQs

How long does the migration take?

The technical steps themselves typically take 1–2 hours. However, if you run the full testing cycle — sandbox first, then UAT (user acceptance testing), then production — allow 1–2 business days end to end. The main variable is how many Salesforce environments you validate in before going live.

Is there any downtime?

Downtime is not expected. The Use External Client App credentials toggle can be switched back off at any time if something looks wrong, and both Enhanced Chat and BYOC can run simultaneously during the transition.

Is there any additional Salesforce licences / add ons required?

For BYOC to work you need the Digital Engagement SKU with the Partner Messaging add-on license. One way to check if you have the relevant license in place is,

Go to Salesforce setup > Company Information
Check if you Partner Messaging User listed under Permission Set Licenses and the total licenses available.

Reach out to your Salesforce Account Executive (AE) if you are missing either the license or add-on to get them enabled for your Salesforce Organization.

Is there any risk of overwriting existing Salesforce data?

There is a risk around loss of data (specifically the Fin custom Case fields) when uninstalling the previous unlocked/unmanaged package.
However, that's mitigated by Running the Apex migration script and/or by downloading the Case data as part of uninstallation.
There's no risk associated with overwriting existing salesforce data with this migration specifically.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Upgrading your Salesforce connection to use the External Client App and support BYOC