Salesforce

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

Sonora currently connects through a Salesforce External Client App that you create in your org. During setup, you enter the External Client App’s Consumer Key, Consumer Secret, and Salesforce instance URL in Sonora. A Sonora-managed authorization flow is planned, but is not available in the product UI yet.

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
Opportunities	Stage, amount, close date, owner
Cases	Subject, status, priority, comments
Tasks and activities	Used as touchpoint and engagement signals
Custom fields on Account and Contact	Mapped during setup; queryable in chat and Canvas

Sonora syncs read-only by default. If you opt into write-back, health scores, eCSAT, and selected enrichments push to fields you choose on the Account record.

Prerequisites

• Salesforce admin access
• Ability to create, edit, and delete External Client Apps
• A Salesforce integration user with API Enabled permission
• The integration user’s profile or permission set granting read access to Accounts, Contacts, Opportunities, Cases, and any custom objects you want to include

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

Connect

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 manual Sonora connection uses the client credentials flow, so this redirect URL is not used by Sonora.
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. Connect in Sonora

1. In Sonora, go to Settings → Integrations.
2. Open the Salesforce card.
3. Enter:
   • Consumer Key
   • Consumer Secret
   • Instance URL (for example, https://yourcompany.salesforce.com)
4. Click Test Connection.
5. Save the integration configuration.

The first import covers a configurable lookback window (default: open opportunities and active accounts plus their related records). After that, syncs are incremental — new and changed records are picked up continuously.

Field and account mapping

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

• Account inclusion filters — restrict imports to a subset (e.g., only customer accounts, only specific record types)
• Custom field mapping — pull in custom Account and Contact fields, with optional renaming for chat and Canvas
• Active contract criteria — tell Sonora how you mark a customer as currently paying, so renewal-related actions fire on the right accounts

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

Sandbox

To connect a sandbox, use the sandbox instance URL when configuring the connection.

Sonora-managed OAuth coming soon

A Sonora-managed OAuth authorization flow is planned. When available, you will be able to connect Salesforce from Sonora without creating your own Salesforce app or managing Consumer Keys and secrets.

Disconnect

From Settings → Integrations, open the Salesforce card and disconnect or disable the integration. You can also revoke access from inside Salesforce by disabling the External Client App, changing its Run As user, or rotating the External Client App’s Consumer Secret.

Troubleshooting

“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.

Authentication errors. Verify that the Consumer Key and Consumer Secret are correct, the instance URL matches the Salesforce org, Client Credentials Flow is enabled, and the External Client App has a Run As integration user.

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.