Salesforce Phone Integration with Retell AI: Setup Guide

A Salesforce phone integration with Retell AI is a native connection built on a Salesforce External Client App: Retell authenticates with the OAuth 2.0 client credentials flow, acts as a dedicated Run As user, and then syncs Contacts, logs every call as a Salesforce Task, and gives your agents live tools for Contacts, Leads, Accounts, Opportunities, Cases and custom objects. You set it up once in Salesforce Setup and once on the Retell Integrations page.

This guide covers the Salesforce-side setup an admin needs, the connection itself, and the choices that decide what call data lands where.

What you need before connecting Salesforce

Check three things first, because each one blocks the connection if it is missing:

• A Salesforce edition with API access: Enterprise, Unlimited, Developer or Performance
• Professional needs Salesforce's paid API add-on; Essentials has no API access
• System Administrator permissions, or a role that can create External Client Apps
• A dedicated integration user for Retell to run as, not a person's account
• An Admin or Developer role in your Retell workspace

A dedicated integration user matters more than it looks. Every read and write Retell makes is checked against that user's profile and permission sets, so a personal account that changes role or leaves the company quietly breaks syncing.

Create an External Client App with the client credentials flow

In Salesforce, click the gear icon, select Setup, and go to Apps → External Client Apps → External Client App Manager. Click New External Client App and fill in:

• External Client App Name: for example "Retell AI". Leave the auto-filled API Name as is.
• Contact Email: your admin address.
• Distribution State: leave it on Local, since the app only runs inside your org.

Expand API (Enable OAuth Settings) and turn OAuth on. Enter https://api.retellai.com/oauth-callback/salesforce as the Callback URL (the client credentials flow never uses it, but Salesforce requires the field). Move Manage user data via APIs (api) into Selected OAuth Scopes; it is the only scope Retell needs. Do not select Full access (full) on its own, because the client credentials flow filters it out and the token request fails. Under Flow Enablement, check Enable Client Credentials Flow, then click Create.

Open the app's Settings tab, expand OAuth Settings and click Consumer Key and Secret. The Consumer Key becomes Retell's Client ID and the Consumer Secret becomes the Client Secret. Treat the secret like a password.

Set the Run As user and its permissions

The client credentials flow has no logged-in person, so Salesforce needs to know whose permissions apply. On the app's Policies tab, click Edit, expand OAuth Policies, check Enable Client Credentials Flow again, and enter the integration user's username in Run As (Username). Use the exact value from Setup → Users → Users, not the email address; in a sandbox the two usually differ.

Check Enable Client Credentials Flow in two places. The checkbox at creation turns the flow on for the app. The one on the Policies tab binds it to the Run As user. Without both, token requests fail even though the flow looks enabled.

Then grant the Run As user only what you will use: API Enabled; Read on Contact and every field you import; Edit on Contact and every field you write back; Create on Task if you log activities. Each agent tool needs its own object permission on top, for example Read on Opportunity for the opportunity tools. A missing field permission does not break the connection. That field just stops syncing, which is harder to spot.

Connect Salesforce in the Retell dashboard

In Retell, open Integrations, select Available, find Salesforce and click Connect. Fill in four fields: Connection name, Instance URL, Client ID and Client Secret.

The Instance URL must be your My Domain URL in the form https://yourdomain.my.salesforce.com, lowercase and with no path. A Lightning URL ending in lightning.force.com is rejected; sandbox domains ending in sandbox.my.salesforce.com are accepted. Find the right value under Setup → Company Settings → My Domain.

Retell tests the credentials against the Salesforce API on connect. A brand-new External Client App can take up to 30 minutes to become available, so if the first attempt fails right after you created it, wait and retry before assuming the credentials are wrong. The Salesforce connection guide in the Retell docs has screenshots of every screen.

Sync Contacts and log every call as a Salesforce Task

After the connection test passes, click Set up contact sync. Retell maps Salesforce Phone to Retell phone_number and locks it, since phone number is the matching key. Map first and last name next, then any custom fields, including __c fields. The first sync scans every Contact with a phone number; after that Retell polls every 5 minutes (as of August 2026) for changed records.

• Contact fields: Direction: Salesforce to Retell, every 5 minutes. Lands in Salesforce as: Read from Contact.
• Post-call analysis fields: Direction: Retell to Salesforce, after each call. Lands in Salesforce as: Updated Contact fields.
• Each call: Direction: Retell to Salesforce. Lands in Salesforce as: Completed Task, Call subtype.
• Each chat: Direction: Retell to Salesforce. Lands in Salesforce as: Completed Task, Task subtype.
• Agent tool writes: Direction: During or after the call. Lands in Salesforce as: Contact, Lead, Account, Task, Note or custom object.

Turn on Log activities automatically on the Sync to Salesforce tab, and each call becomes a Task on the matched Contact: Status Completed, the Call task subtype, a subject of "Call" plus the call ID, and CallDurationInSeconds set. The description carries the call ID, the from and to numbers, the disconnection reason and the summary, so a rep can read the outcome without opening Retell.

Structured outcomes come from post-call analysis. Define a field such as lead_status, map it to a Retell contact field, and map that field to a Salesforce field such as a custom Lead_Status__c on the outbound tab. After each call the new value is pushed to the Contact. Outbound sync updates existing Contacts only, unless you turn on Create new contacts in CRM.

Look up Opportunities, Cases and custom objects during the call

Contact sync only reads the Contact object. For everything else, the agent uses live tools, which appear in the function menu as soon as Salesforce is connected: Search Contact, Get, Create and Update Contact, Get, Create and Update Lead, Get and Update Account, List Account Opportunities, Get Opportunity, Get Case, Get User, Get and Update Custom Object, Query Records, Create Task and Create Note.

Query Records runs a SOQL query you write, with dynamic variables filled in at run time. For example, a support line can pull the caller's open Cases with a query filtered on {{contact_id}}, where that variable came from an earlier Search Contact call. Use Search Contact, not SOQL, to identify the caller, because Search Contact matches across phone formats and a SOQL filter needs an exact string match. Add a LIMIT to every query: Salesforce returns at most 2,000 rows per call, and integration tool responses are capped at 30,000 characters.

Each tool times out after 3 to 8 seconds depending on the tool (as of September 2026). On a timeout the call continues, so tell the agent in its prompt what to say when a lookup does not come back. To run a lookup before the agent speaks, add Search Contact as a pre-call function on the agent's Workflow page, as described in the agent workflow docs.

Fix the common Salesforce connection errors

• The connection fails right after you created the app: wait up to 30 minutes, then confirm Enable Client Credentials Flow is checked in both places and Run As is set.
• Requests are blocked by IP restrictions: Retell calls from cloud IPs, so on the app's Policies tab set IP Relaxation to Relax IP restrictions, or exempt the integration user's profile from login IP ranges.
• The connection worked, then errored: Salesforce rejected the credentials, usually because the secret was rotated or the Run As user was deactivated. Paste current credentials and click Reconnect; mappings and synced contacts are kept.
• Calls are not appearing as Tasks: the caller's number must match a Contact imported by this connection, and the Run As user needs Create on Task.

If you run HubSpot alongside Salesforce, see how to connect Retell AI to HubSpot; only one CRM connection can drive contact sync at a time, but both can supply tools. Teams in regulated outbound work, such as insurance renewals, often pair this with a SIP connection that keeps their existing numbers. Before rollout, run it through the checks in how to evaluate a voice agent platform before going live.

Start in a sandbox org if you have one, since sandbox My Domain URLs are accepted. Open the Retell dashboard to connect your org and test a call against real Contact data.