Upgrading Your Salesforce Integration to Comm Widget 2.0

Requirements:

Comm Widget 2.0 requires BPCC 5.36.0 or higher

Comm Widget 2.0 is supported only in Salesforce Lightning (Sales Cloud and Service Cloud); Salesforce Classic is not supported.

Migration from Universal Repeater

Install the New Package from AppExchange

Log in to the target SFDC org in the browser before opening the install page, to signal to AppExchange where to install the package.
Open the package listing link from the AgentExchange store.
Click Get It Now. If your org doesn't show up in the list, refresh the tab with the org and try again.
Choose Install in Production.

Note: This is the generic SFDC label for any non-sandbox org, including Developer Edition orgs.
If a warning appears reading "This app does not list support for your edition of Salesforce", disregard it. This is a standard message for Developer Edition orgs.
Check the I have read and agree to the terms and conditions box, then click Confirm and Install.
To limit access during testing, choose the access level Install for Admins Only.
Click Install, then wait for the package to finish installing.

Troubleshooting Entity Id issues

At this point, you may see an error message reading "A service provider with this Entity Id already exists." This indicates that your org already has a Connected App, usually from the old integration, using the same Entity Id as the Connected App from the new package .


	Do not delete or modify the existing Connected App if it's used by an active integration — doing so can break the current widget.

To solve this, the safest option is to test the install in a separate, clean org (e.g., a new free Developer Edition) where there's no Entity Id conflict.

If testing must occur in the same org and the old configuration isn't live or in production, you can manually change the Entity Id of the existing Connected App (Setup > App Manager > the Connected App > View/Edit) to free up the identifier for the new package.

After a successful install, check Setup > Installed Packages: the old and new package should appear as separate entries with different Namespace Prefixes (e.g., BrightPattern and BrightPatternV2), confirming they run independently without conflicting.

Set Up the Call Center for the New Widget

Setup > Quick Find > Call Centers. The new package usually creates a Call Center record automatically with the Comm Widget 2.0 URL (in the form https://tenant.brightpattern.com/agent/crmembedded/adapters/lightning.html).
Open the created Call Center and verify the following:
1. The URL points to the real domain of the correct Bright Pattern instance.
2. Salesforce Compatibility Mode is set to Lightning.
In the Manage Call Center Users tab, click Add More Users and add the test user or role.


	A user can be assigned to only one Call Center at a time. As soon as a user is added to the new Call Center using Comm Widget 2.0, they are automatically removed from the previous Call Center using Universal Repeater. This is the standard mechanism for switching between widget versions.

Ensure that the Widget Appears in the Utility Bar

If the target Lightning app already has the standard Salesforce component Open CTI Softphone configured, it is not necessary to manually add a new Utility Item. As it is not tied to a specific package version, the Utility Bar automatically displays whichever Call Center is currently assigned to the logged-in user.

If you do need to add the widget manually, make sure to open the specific Lightning app where this Utility Item is configured (Setup > App Manager > the app > Edit > Utility Items), not the default app (e.g., the standard Sales app). Otherwise, the widget panel won't be visible.

Troubleshooting User Access Issues

If the app won't open, or a test user's App Launcher shows "No results", likely causes are the user's License/Profile combination and the app's list of allowed profiles.

Navigate to Setup > Users > open the user's record > Edit.
Change the User License to Salesforce Platform (or whichever license the already-working test user has), then select the matching Profile (e.g., Standard Platform User) and press Save.

Note: The User License field limits which profiles are selectable. Restricted licenses (e.g., "Force.com - App Subscription") only grant a limited profile with no visibility into custom apps.
Even with the correct profile, the app may still be invisible unless that profile is explicitly added to the app's own access list: Setup > App Manager > the app > Edit > User Profiles > add the profile > Save.
Refresh the page and try opening the app via App Launcher again as the test user.

Final Verification

As the test user, open the new Lightning app for your call center, then expand the Phone panel in the Utility Bar. If the "Agent Desktop — Powered by Bright Pattern" login screen loads, the new Comm Widget 2.0 is connected and working correctly.

Using Multiple Widget Versions Concurrently

Because the Universal Repeater and Comm Widget 2.0 widgets are installed as separate packages, they can run side by side in the same Salesforce org, which may be useful for gradual migration and testing. As a user can be assigned to only one Call Center at a time, switching between widget versions is done simply by reassigning the user/role to the desired Call Center record, with no other configuration required.

To run different widget versions in the same SFDC environment:

Download the Comm Widget 2.0 application package as described above.
Set up a new SFDC Call Center with the Agent Desktop URL in the format https://example.brightpattern.com/agent/crmembedded/adapters/lightning.html
Assign it to the required user role (either existing or newly created, e.g. “NewWidgetUser”).
If an existing role was used in the above step, open the original Call Center object with the Universal Repeater widget and remove that user role assignment.< Previous | Next >