> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Salesforce agent functions
> Salesforce tools for Retell AI agents: identify callers, read opportunities and cases, create contacts, leads, and tasks, run SOQL queries, and update records.
A [connected Salesforce org](/integrations/salesforce) 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](/agent/agent-workflow), and no [contact sync](/integrations/salesforce-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](/integrations/salesforce#step-4-set-the-run-as-user), so its permissions decide what each tool can reach. See [use integration tools in an agent](/integrations/overview#use-integration-tools-in-an-agent) for how to add and configure them.
| Tool | What it does |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Search Contact** | Find a Contact by phone number — typically the caller's number, to identify who's calling |
| **Get Contact** / **Create Contact** / **Update Contact** | Fetch a Contact by record Id, create one for a caller who isn't in the CRM yet, or update fields the caller confirms or corrects |
| **Get Lead** / **Create Lead** / **Update Lead** | Fetch a Lead, create one for a new prospect, or update it |
| **Get Account** / **Update Account** | Fetch an Account by record Id, or update its fields |
| **List Account Opportunities** | List an Account's Opportunities (up to 50), most recent first, when the conversation turns to the account's deals |
| **Get Opportunity** | Fetch an Opportunity, for example the deal the caller is asking about |
| **Get Case** | Fetch a Case, for example a support case the caller references |
| **Get User** | Fetch a User by record Id — a member of your Salesforce org, not the caller, for example the owner of an account from an earlier lookup |
| **Get Custom Object** / **Update Custom Object** | Fetch or update a record of a custom object you pick when configuring the tool |
| **Query Records** | Run a SOQL query you write, with dynamic variables filled in at run time, and return the matching records |
| **Create Task** | Create a Task on a Contact or Lead when a follow-up is agreed |
| **Create Note** | Attach a Note to a Contact or Lead with a summary of what was discussed |
## Required permissions
The [Run As user](/integrations/salesforce#step-4-set-the-run-as-user) always needs **API Enabled**; each tool then needs the matching object permission on the user's profile or permission sets:
| Tool | Run As permission |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Search Contact, Get Contact | **Read** on Contact |
| Create Contact | **Create** on Contact |
| Update Contact | **Edit** on Contact |
| Get Lead | **Read** on Lead |
| Create Lead | **Create** on Lead |
| Update Lead | **Edit** on Lead |
| Get Account | **Read** on Account |
| Update Account | **Edit** on Account |
| List Account Opportunities, Get Opportunity | **Read** on Opportunity |
| Get Case | **Read** on Case |
| Get User | **Read** on User |
| Query Records | **Read** on every object the query selects from or filters on |
| Create Task | **Create** on Task |
| Create Note | **Edit** on the record the Note attaches to (Notes take their access from the parent record) |
| Get Custom Object | **Read** on the custom object you configure the tool for |
| Update Custom Object | **Edit** on the custom object you configure the tool for |
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](/integrations/salesforce#step-4-set-the-run-as-user) has permissions on it, and **Query Records** can query any object by its API name. [Contact sync](/integrations/salesforce-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](/build/dynamic-variables) that Retell resolves when the tool runs:
```sql theme={"dark"}
SELECT Id, CaseNumber, Subject, Status
FROM Case
WHERE ContactId = '{{contact_id}}' AND IsClosed = false
ORDER BY CreatedDate DESC
LIMIT 5
```
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](/agent/agent-workflow#pass-a-response-from-one-function-to-the-next). `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](/integrations/overview#run-a-test-to-get-a-tools-output-fields) 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](/build/dynamic-variables) 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](/integrations/salesforce-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
Add Salesforce tools to a single- or multi-prompt agent and test them with live requests.
Call Salesforce tools from a function node and branch on the result.
Import your Contacts, write analysis results back, and log conversations as Tasks.
Map tool responses to variables your agent can use later in the conversation.