Skip to main content
A connected Salesforce org gives your agents live Salesforce tools: look up the caller, read their opportunities and cases, create Contacts and Leads, run your own SOQL queries, and update records mid-call. Tools run during a conversation or before and after it, and no contact sync is required.

​
Available tools

Once connected, these tools appear in your agent’s function menu. Every tool call runs as the Run As user, so its permissions decide what each tool can reach. See use integration tools in an agent for how to add and configure them.

​
Required permissions

The Run As user always needs API Enabled; each tool then needs the matching object permission on the user’s profile or permission sets: Field-level security applies on top: reads return only fields the user can see, and creates and updates need Edit on each field they set. A missing permission doesn’t flag the connection; that one tool fails.

​
FAQ

No. Tools work as soon as the connection is made, and each tool is bound to the specific connection you pick when configuring it. Contact sync, analysis mapping, and automatic activity logging are separate features you opt into.
Yes. The custom object tools work with any custom object you configure them for, as long as the Run As user has permissions on it, and Query Records can query any object by its API name. Contact sync is separate and reads only Contact.
The tool has one input, soql. It defaults to a fixed value you write when configuring the tool, and it can include dynamic variables that Retell resolves when the tool runs:
Here {{contact_id}} comes from an earlier Search Contact call. If a variable in the query has no value when the tool runs, Retell skips the call rather than sending the placeholder to Salesforce, and the agent sees Skipped: soql is required, so make sure the lookup that sets the variable runs first.You can also switch the input to Description mode and describe what to fetch, and the agent composes the query at call time. A fixed query is the safer default: you can test it before the first call, while a query the agent composes can name a field that doesn’t exist or get the syntax wrong mid-conversation.
Salesforce’s query result as is: totalSize, done, and a records array in which each record carries the fields you selected plus an attributes object with the object type and record URL. Only the first batch comes back: Salesforce returns at most 2,000 rows per query call, and Retell doesn’t fetch further pages, so done is false when more rows exist.Add a LIMIT clause and name the fields you need. A voice agent rarely needs more than a handful of rows, and the whole result counts toward the 30,000-character cap on integration tool responses. SELECT FIELDS(ALL) works, but Salesforce requires it to be bounded with LIMIT 200 or less, and it pulls every field into the agent’s context.The Output tab starts empty because the fields depend on your query. Run a test to see the real result and pick the fields to save as dynamic variables.
The query runs as the Run As user, so it returns only objects and fields that user can read. Salesforce’s error comes back to the agent as the tool result, for example MALFORMED_QUERY for a syntax error, or INVALID_FIELD for a field that doesn’t exist or that the Run As user can’t see. Prompt the agent on what to say when a lookup doesn’t come back.
Search Contact. A SOQL filter like WHERE Phone = '{{user_number}}' finds a Contact only when the stored value matches the caller’s number character for character, while Search Contact uses Salesforce’s search index and matches across phone formats. Use Query Records for what the dedicated tools don’t cover: the caller’s open Cases, Opportunities in a given stage, or a custom object filtered by something other than its record Id.
The Contact fields your org allows on create, read live from Salesforce, with the fields Salesforce itself requires (such as LastName) marked required. Fields default to Description mode, so the agent fills in what the caller gave. The response is the new record’s id and a success flag; map id to a dynamic variable and pass it to Create Task, Create Note, or Update Contact later in the conversation.
Create Contact creates the record the moment the agent calls it, mid-conversation, with the fields the agent collected. Create new contacts in CRM is part of contact sync and runs after the conversation, for a matched Retell contact that isn’t linked to a Salesforce Contact yet. Both create the Contact as the Run As user.
Search Contact uses Salesforce’s search index, which lags writes by a few seconds. Save the id that Create Contact returns as a dynamic variable and pass it to the tools that need it, instead of searching for the record again.
Between 3 and 8 seconds, depending on the tool (as of September 2026): 3 for the get tools, 6 for Search Contact, List Account Opportunities, and Query Records, and 8 for the tools that create or update a record. On a timeout or an error the agent carries on talking, so prompt it on what to say when a lookup doesn’t come back.

​
Next steps

Integration tools for prompt agents

Add Salesforce tools to a single- or multi-prompt agent and test them with live requests.

Integration tools in conversation flow

Call Salesforce tools from a function node and branch on the result.

Salesforce contact sync

Import your Contacts, write analysis results back, and log conversations as Tasks.

Dynamic variables

Map tool responses to variables your agent can use later in the conversation.