Salesforce

Salesforce is the most common starting point for a Sonora deployment. Connecting it brings in your accounts, contacts, opportunities, contracts, and custom fields — and gives chat, Canvas, and workflows the structural backbone they need to talk about your customers in your team’s terms.

Choose OAuth under Connection to install the Sonora package, then sign in to Salesforce to authorize access. This is the default connection method. If your org requires its own External Client App, choose Manual and follow the manual connection steps; that method does not need the Sonora package.

What syncs

Object	Notes
Accounts	Account record becomes a Sonora customer; ID maps to the customer’s external ID
Contacts	Contact records map into People Graph. On by default; you can turn contact sync off
Opportunities	Stage, amount, close date, owner
Contracts	Contract dates and terms, used for renewal dates and active-customer rules. Skipped with a warning when unavailable unless your settings require them
Account team members	Optional. Syncs each account’s Salesforce account team as its Sonora account team
Custom fields on Account, Opportunity, and Contract	Mapped during setup; queryable in chat and Canvas

Sonora syncs read-only by default. If you opt into write-back, the enrichment values you choose push to fields you pick on the Account record.

Prerequisites

• A Salesforce admin who can install packages, for the package install step
• A Salesforce user with the API Enabled permission to authorize the connection. Sonora syncs as this user, so it sees exactly the records and fields this user can read. We recommend a dedicated integration user rather than a person’s own login.
• That user’s profile or permission set granting read access to Accounts, Contacts, Opportunities, and any fields you map. Contract access is required for Contract fields or mappings, active-customer rules, and product usage or write-back configured on Contract. To sync account teams, it also needs read access to Account Team Members.
• Permission to manage integrations in Sonora

If your org enforces IP login restrictions, allowlist the addresses on the IP allowlist page for the integration user’s profile.

Connect

1. Install the Sonora package

1. In Sonora, go to Settings → Integrations and open the Salesforce card.
2. Under Connection, select OAuth, choose Production or Sandbox, then click Install Sonora package. The Salesforce install page opens in a new tab.
3. Sign in to Salesforce as an admin.
4. Choose who to install for, then click Install.

The package adds the Sonora External Client App to your org. Sonora signs in through this app, so you don’t need to create your own.

2. Authorize Sonora

1. Back in Sonora, click Connect Salesforce.
2. Sign in to Salesforce as the integration user.
3. Review the requested access and click Allow. Sonora requests two scopes:
   • api — manage user data via APIs
   • refresh_token — perform requests at any time, so syncs keep running after you sign out
4. Salesforce returns you to the Salesforce card in Sonora, which shows Salesforce connection active with the instance URL, connected user, and org ID.

The Salesforce authorization page expires after 10 minutes. If it does, click Connect Salesforce again.

The first import pulls every record that passes your filters. After that, each scheduled sync picks up only the accounts, contacts, opportunities, and contracts changed since the last one. Two parts of the sync still read their full set on every run, so they use more of your org’s API quota: account team sync takes a complete snapshot of account teams, and account filters re-check every matching account and opportunity.

Changing the connected user

To sync as a different Salesforce user, click Reconnect Salesforce and sign in as that user. Your field mappings, filters, and import rules are kept.

Field and account mapping

After the initial connection, open the Salesforce card to configure:

• Data mapping — map Salesforce fields to the attributes Sonora tracks, such as ARR, owner, and stage, and fetch additional custom fields from Account, Opportunity, and Contract
• Account filters — restrict imports to a subset (e.g., only customer accounts, only specific record types)
• Import rules — tell Sonora how you mark a customer as currently paying, so renewal-related actions fire on the right accounts
• Contact sync and account team sync — turn each on or off

Mappings can be edited any time. Changes affect future syncs and re-running a backfill.

Sandbox

OAuth connections authorize against production (login.salesforce.com) by default. To connect a sandbox, select Sandbox under Connection → OAuth → Environment before installing the package or connecting. Install Sonora package and Connect Salesforce then use test.salesforce.com.

The environment selector locks after connecting through OAuth. Contact your Sonora team if you need to change environments afterward.

Manual connection

If your security policy doesn’t allow installing third-party packages, choose Manual to connect through an External Client App that you create and own. Sonora then signs in with the client credentials flow instead of a user authorization. Skip the Sonora package installation for this method.

1. Create an External Client App

1. In Salesforce, go to Setup.
2. In Quick Find, search for External Client App Manager.
3. Open External Client App Manager.
4. Click New External Client App.
5. Fill in the basic information:
   • External Client App Name: Sonora Integration
   • API Name: Sonora_Integration
   • Contact Email: your admin email
   • Distribution State: Local

2. Configure OAuth settings

1. Expand API (Enable OAuth Settings).
2. Select Enable OAuth.
3. Enter the OAuth callback value:
   • Callback URL: https://login.salesforce.com/services/oauth2/success
   • The client credentials flow doesn’t redirect, so Sonora never uses this URL. Salesforce requires a value.
4. Select the required OAuth scopes:
   • api — Manage user data via APIs
5. Click Create.

3. Enable client credentials in settings

After you click Create, Salesforce redirects you to the External Client App detail page.

1. Open the Settings tab.
2. Click Edit.
3. Expand OAuth Settings.
4. In Flow Enablement, select Enable Client Credentials Flow.
5. Save the settings.

4. Assign the integration user in policies

Salesforce requires a user for client credentials calls to run as.

1. In External Client App Manager, open the External Client App.
2. Open the Policies tab.
3. Click Edit.
4. Expand OAuth Policies.
5. In OAuth Flows and External Client App Enhancements, select Enable Client Credentials Flow.
6. In Run As (Username), enter the Salesforce username for the integration user.
7. Save the policies.
8. Make sure that user has API access and the object and field permissions Sonora needs.

5. Get credentials

1. In Salesforce, go to Setup → External Client App Manager.
2. Open the Sonora External Client App.
3. Open the Settings tab.
4. Expand OAuth Settings.
5. Click Consumer Key and Secret. Salesforce opens a classic setup page or a new tab with the app credentials.
6. Copy the Consumer Key and Consumer Secret.

6. Enter the credentials in Sonora

1. In Sonora, go to Settings → Integrations and open the Salesforce card.
2. Under Connection, select Manual.
3. Enter:
   • Environment: production, or sandbox for a sandbox org
   • Instance URL: your org’s My Domain URL, for example https://yourcompany.my.salesforce.com
   • Client ID: the Consumer Key
   • Client Secret: the Consumer Secret
4. Click Test Connection.
5. Save the integration configuration.

If you later select OAuth and complete Connect Salesforce on the same connection, Sonora switches to the user authorization and keeps your manual credentials as a backup it uses if the authorization stops working.

Disconnect

From Settings → Integrations, open the Salesforce card and disconnect or disable the integration.

To revoke access from inside Salesforce:

• Package connection: in Setup → Connected Apps OAuth Usage, find Sonora and click Revoke for the integration user, or uninstall the Sonora package.
• Manual connection: disable the External Client App, change its Run As user, or rotate its Consumer Secret.

If you set up a manual connection first and later clicked Connect Salesforce, Sonora keeps the manual credentials as a backup and switches to them when the user authorization stops working. Revoking only the Sonora app leaves syncs running through your own External Client App. To stop all access, disconnect the integration in Sonora, or revoke both apps.

Troubleshooting

“Salesforce authorization was cancelled or denied.” The user clicked Deny on the Salesforce consent page, or an admin policy blocked them from authorizing the Sonora app. Check that the user is allowed to use the Sonora External Client App, then click Connect Salesforce again.

“Salesforce authorization session expired.” More than 10 minutes passed on the Salesforce sign-in page, or the sign-in started in a different browser tab or session. Click Connect Salesforce again and finish within the same browser.

Syncs stop with authentication errors after working. The authorization was revoked, the integration user was deactivated or lost API access, or your org’s refresh token policy expired the token. Click Reconnect Salesforce and sign in again. For a manual connection, check that the Client ID and Client Secret are correct, the instance URL matches the org, Client Credentials Flow is enabled, and the External Client App has a Run As user.

“insufficient access rights” during sync. The connected user’s profile doesn’t have read access to the object that errored. Check field-level security and object permissions in Salesforce — the most common gap is on a custom field added after the integration was set up.

Contracts were skipped. When your settings do not require Contracts, sync can continue without access to them. Existing Contract data is kept. Restore access and run a full resync to refresh Contracts changed while access was unavailable.

Records aren’t showing up that should. Check the inclusion filters in the Salesforce card configuration — the most common cause is a record type or sharing rule that excludes the records you expected.

API limits. Sonora respects the org’s bulk and REST API quotas. During heavy initial imports the sync paces itself; you’ll see throughput drop temporarily and resume when the org’s limit window resets.