Connect Salesforce to Retell AI with an External Client App: OAuth client credentials, the Run As user setup, and how to verify the connection works.
Connecting Salesforce takes an External Client App with the client credentials flow enabled and a Run As user. One connection covers both contact sync and agent functions: your agents work your Contacts, opportunities, and cases live, and Retell keeps the Contact records current. This page covers the Salesforce-side setup and the credentials Retell needs.
Retell authenticates with the OAuth 2.0 client credentials flow.
Connect Salesforce when Salesforce is your system of record and you want your agents to work from it without anyone copying data between tools. It’s the right choice when you want to:
Call or text people who already exist in Salesforce. Contacts sync into Retell automatically, so your agent greets callers by name and knows their account details instead of asking for them.
Keep Salesforce current without manual data entry. Analysis results from each conversation (qualification status, stated preferences, a corrected email address) write back to the Contact record.
Give your sales team call history where they already work. Each call and chat lands on the Contact’s activity timeline as a Task, with the summary and duration.
Let the agent act on Salesforce directly.Integration tools identify the caller by number, read their opportunities and cases, create a Lead when a new prospect calls in, and update records the caller corrects.
For example, an insurance agency’s outbound agent works renewal lists from Salesforce: it greets each Contact by name, answers policy questions from the Account record, creates a Lead when a referral comes up, and every conversation lands on the timeline as a Task.
A Salesforce edition with API access: Enterprise, Unlimited, Developer, or Performance. Professional needs Salesforce’s paid API add-on; Essentials has no API access at all.
System Administrator permissions in Salesforce, or a role that can create External Client Apps.
A Salesforce user to run the integration as. Use a dedicated integration user rather than a person’s account, so the connection doesn’t break when someone changes roles or leaves.
Video walkthrough: connecting Salesforce and setting up contact sync end to end.
Log in to Salesforce as an administrator. Click the gear icon in the top-right corner, then select Setup.In the left sidebar under Platform Tools, go to Apps > External Client Apps > External Client App Manager. Click New External Client App in the top-right corner.
The External Client App Manager in Setup.
External Client Apps replace the older Connected Apps for new integrations. If your org still creates apps under App Manager > New Connected App, the field names are the same but the screens are laid out differently, and the client credentials setting lives under Manage > Edit Policies instead of the Policies tab.
2
Fill in the basic information
Under Basic Information, enter:
External Client App Name — a descriptive name, for example Retell AI.
API Name — auto-filled from the name; leave it as is.
Contact Email — your admin email address.
Leave Distribution State set to Local. The app only needs to work inside your own org.
The client credentials flow never redirects a browser, so this value is never used. Salesforce requires the field regardless, and any valid HTTPS URL is accepted.
3
Select OAuth scopes
Move these from Available OAuth Scopes to Selected OAuth Scopes:
Manage user data via APIs (api) — the only scope Retell requires. It covers every REST and SOQL call Retell makes.
Perform requests at any time (refresh_token, offline_access) — optional. The client credentials flow doesn’t issue refresh tokens, so this changes nothing for Retell, but it’s harmless if your org adds it by default.
Don’t select Full access (full) alone. The client credentials flow filters full out of the tokens it issues, and since Salesforce’s Winter ‘26 release, a token request whose selected scopes are all unsupported is rejected with invalid_grant: no valid scopes defined.
4
Enable the client credentials flow
Under Flow Enablement, check Enable Client Credentials Flow. This is the setting that lets Retell authenticate without an interactive login. Leave the other flows unchecked.
The Flow Enablement section on the creation screen. This capture predates the scope guidance above: select Manage user data via APIs (api), not Full access.
5
Create the app
Click Create.
A new External Client App can take up to 30 minutes to become available (Salesforce cites 2 to 10 minutes for most apps). If connecting in Retell fails right after you create the app, wait and try again before assuming the credentials are wrong.
From the External Client App Manager, open the app you just created and select the Settings tab. Expand OAuth Settings, then under App Settings click Consumer Key and Secret.Salesforce may ask you to verify your identity with a code sent to your email before showing the credentials.
The Consumer Key and Secret link on the app's Settings tab.
2
Store both values
Copy and securely store:
Consumer Key — Retell’s Client ID.
Consumer Secret — Retell’s Client Secret.
Treat the consumer secret like a password. Don’t share it in plaintext or commit it to source control. Retell encrypts it at rest and never returns it once saved.
The client credentials flow has no logged-in user, so Salesforce needs to know whose permissions to apply. Every read and write Retell makes runs as this user.
1
Open the Policies tab
On the app’s detail page, select the Policies tab and click Edit.
2
Enable the flow and pick the user
Expand OAuth Policies and find OAuth Flows and External Client App Enhancements. Check Enable Client Credentials Flow, then enter your integration user’s username in Run As (Username).
Enter the user’s Username, not their email address. They’re separate fields, and because a username has to be unique across every Salesforce org, they often differ. A sandbox, for example, appends the sandbox name, so you@acme.com becomes you@acme.com.dev. Copy the exact value from the Username column under Setup > Users > Users.
The app's Policies tab with the client credentials flow bound to a Run As user.
You check Enable Client Credentials Flow in two places, and both are required. The checkbox at creation time turns the flow on for the app; this one binds it to a running user. Without a Run As user, token requests fail even though the flow looks enabled.
3
Confirm the user's permissions
Every read and write Retell makes is checked against the Run As user’s profile and permission sets, so grant only what you’ll use:
API Enabled on the user’s profile or a permission set. Without it, every API call is refused.
Read on Contact and on every field you plan to import.
Edit on Contact and on every field you plan to write back, if you enable outbound sync.
Create on Task, if you enable activity logging or the Create Task tool.
For the integration tools you plan to use: Read on Lead, Account, Opportunity, Case, and User; Edit on Contact, Lead, and Account for the update tools; Create on Lead; and the same permissions on any custom object you configure a tool for. Creating a Note needs Edit on the record it attaches to, since Notes take their access from the parent record.
A missing object or field permission doesn’t break the connection. It makes that field silently fail to sync, or that one tool fail, which is harder to spot, so check the profile or permission set before you rely on a mapping.
In the Retell Dashboard, open Integrations, select the Available tab, find Salesforce, and click Connect (Add Account if a connection already exists).
2
Enter your credentials
Fill in the fields:
Field
Value
Connection name
Alias for this connection; prefilled with Salesforce - OAuth.
Instance URL
Your My Domain URL, for example https://acme.my.salesforce.com.
Client ID
The Consumer Key from Step 3.
Client Secret
The Consumer Secret from Step 3.
The instance URL has to be your My Domain URL in the form https://<domain>.my.salesforce.com, lowercase and with no path; a trailing slash is trimmed for you. A Lightning URL like https://acme.lightning.force.com is rejected with Instance URL must be in the format https://<domain>.my.salesforce.com. Sandbox domains such as https://acme--dev.sandbox.my.salesforce.com are accepted.
The Salesforce connection dialog: instance URL plus the External Client App's credentials.
3
Connect and confirm
Click Connect (Add Account if a connection already exists). Retell creates the connection and immediately tests it against the Salesforce API.On success the dialog reports the connection as verified and offers Set up contact sync. On failure it shows Salesforce’s own error and re-enables the fields so you can correct them.
4
Verify it worked
On the Connected tab, the Salesforce connection shows as connected. See Salesforce contact sync to import your Contacts and log conversations as Tasks, or start using agent functions right away.
Give a newly created External Client App up to 30 minutes to become available, then retry. If it still fails, confirm Enable Client Credentials Flow is checked on both the app’s creation settings and its Policies tab, and that Run As (Username) is set.
Retell rejects my instance URL
Find the correct value in Salesforce under Setup > Company Settings > My Domain, then check it against the format above. Lightning URLs (.lightning.force.com) and bare .salesforce.com URLs are rejected.
The connection shows an error after working for a while
Retell flags a connection as errored when Salesforce rejects the credentials: an HTTP 401, or Salesforce’s INVALID_SESSION_ID. The usual causes are a rotated consumer secret, a deactivated Run As user, or the app being deleted or disabled in Salesforce. Reconnect with current credentials.
Requests are blocked by IP restrictions
If your org enforces login IP ranges on the Run As user’s profile, or the app’s OAuth policies enforce IP restrictions, Salesforce refuses Retell’s calls because they come from cloud IPs. On the app’s Policies tab, set IP Relaxation to Relax IP restrictions, or exempt the integration user’s profile from login IP ranges.
I need to rotate the consumer secret
On the Connected tab, open the connection’s settings. The saved secret shows masked; paste the new one over it (re-enter the Client ID too if it changed) and click Reconnect. Retell verifies the new credentials before saving, and your field mappings and synced contacts are untouched.
You can add multiple connections, but only one CRM connection in your workspace can drive contact sync at a time, across every provider. The Contact sync toggle in a connection’s settings decides which one; turning it on for one connection takes sync over from the previous one.
