> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 Pro (current TTS) and Pulse (current
> multilingual STT) — or Pulse 2.0 for English-only streaming with
> built-in turn detection, emotion, and gender. Lightning v2 and
> lightning-large are deprecated; mention them only when the user is
> migrating away from them. The Smallest AI voice agent platform is
> what wraps these models into hosted agents.

# Salesforce

> Connect Salesforce to your Smallest AI voice agents with OAuth. Search and create leads, read accounts, update opportunities, and pin lead source, status and owner.

Connect **Salesforce** so your agent can recognise returning callers, capture new leads and keep opportunities current, without anyone updating the CRM after the call.

## At a glance

|                      |                                                                                |
| -------------------- | ------------------------------------------------------------------------------ |
| **Authentication**   | OAuth 2.0 (sign in with Salesforce)                                            |
| **Asked at connect** | Nothing. You're sent straight to Salesforce                                    |
| **Objects**          | Lead (search, get, create, update) · Account (get) · Opportunity (get, update) |
| **Works with**       | Single-prompt agents                                                           |

## Before you connect

* **An edition with API access.** Enterprise, Performance, Unlimited and Developer editions include it. Professional Edition needs the API add-on.
* **A user with the API Enabled permission.** The agent acts as whoever signs in, so use a dedicated integration user with access to only the objects your agent needs. Anything that user can edit, the agent can edit.
* **Admin approval, if you're not an admin.** Salesforce blocks users from authorizing a connected app that isn't installed in the org unless they have the *Approve Uninstalled Connected Apps* permission. If sign-in is blocked, ask a Salesforce admin to install the app first.

## Connect Salesforce

#### Open Salesforce on the Integrations page

Open the **Integrations** page in the dashboard and click **Connect** next to Salesforce.

#### Sign in and allow access

Click **Connect** in the dialog. You're sent to `login.salesforce.com` to sign in and approve access, then returned to the dashboard.

The connection acts as the Salesforce user who approves it, so the agent can only see and change the records that user can.

#### Add the tools to your agent

When you see **Salesforce connected successfully**, click **Go to Tools**. Click **Add tool → Integration tool**, choose **Salesforce**, tick the tools this agent needs, and click **Add tools**. From inside an agent, use **Add tool → New tool → Integration tool** instead.

## Tools

| Tool                   | Function name                   | What it does                                       |
| ---------------------- | ------------------------------- | -------------------------------------------------- |
| **Search leads**       | `salesforce_search_leads`       | Finds leads by phone number, email or name         |
| **Get lead**           | `salesforce_get_lead`           | Reads a lead's full record                         |
| **Create lead**        | `salesforce_create_lead`        | Creates a new lead                                 |
| **Update lead**        | `salesforce_update_lead`        | Changes fields on an existing lead                 |
| **Get account**        | `salesforce_get_account`        | Reads an account by its record ID                  |
| **Get opportunity**    | `salesforce_get_opportunity`    | Reads an opportunity by its record ID              |
| **Update opportunity** | `salesforce_update_opportunity` | Changes stage, amount, close date and other fields |

The function name is what the agent calls. Reference it in your prompt, for example *"Call `salesforce_search_leads` with the caller's phone number before asking for their name."*

### Fields

#### Search leads

| Field   | Required | What the agent sends                        |
| ------- | -------- | ------------------------------------------- |
| `query` | Yes      | A phone number, email or name to search for |

Returns each matching lead's **Id, Name, Email and Phone**. Use **Get lead** with the `Id` for the full record.

#### Get lead · Get account · Get opportunity

| Field       | Required | What the agent sends                                       |
| ----------- | -------- | ---------------------------------------------------------- |
| `record_id` | Yes      | The Salesforce record ID, for example `00Q5f000006abcdEAA` |

The agent is told never to use a name as an ID. For leads, it should search first. Accounts and opportunities have no search tool, so the ID has to come from earlier in the call, such as a field on the lead.

#### Create lead · Update lead

**Update lead** also needs the lead's `record_id`. Every other field is optional; the agent fills the ones it learns on the call.

| Field         | Label       | Pinnable |
| ------------- | ----------- | -------- |
| `FirstName`   | First name  |          |
| `LastName`    | Last name   |          |
| `Company`     | Company     |          |
| `Email`       | Email       |          |
| `Phone`       | Phone       |          |
| `Title`       | Job title   |          |
| `Industry`    | Industry    |          |
| `Description` | Notes       |          |
| `LeadSource`  | Lead source | Yes      |
| `Status`      | Lead status | Yes      |
| `OwnerId`     | Owner ID    | Yes      |

> **Warning**
>
> By default, Salesforce requires **Last name** and **Company** on a new lead, and your org may require more fields. Tell the agent to collect them before it calls **Create lead**.

#### Update opportunity

Needs the opportunity's `record_id`, plus any of:

| Field         | Label                     | Pinnable |
| ------------- | ------------------------- | -------- |
| `Name`        | Opportunity name          |          |
| `Amount`      | Amount                    |          |
| `CloseDate`   | Close date (`YYYY-MM-DD`) |          |
| `Description` | Description               |          |
| `StageName`   | Stage                     | Yes      |
| `OwnerId`     | Owner ID                  | Yes      |

## Pin the values that never change

Open the tool on your agent and set these fields to **Fixed** (or **Variable**, to set them per campaign). The agent stops asking about them and can't change them.

| Field        | Typical pin            | Why                                                   |
| ------------ | ---------------------- | ----------------------------------------------------- |
| `LeadSource` | `Voice Agent`          | Every lead this agent creates is attributed correctly |
| `Status`     | `Open - Not Contacted` | New leads land in your team's queue                   |
| `OwnerId`    | Your SDR's user ID     | Leads are assigned to the right person                |
| `StageName`  | `Qualification`        | An opportunity only moves to the stage you allow      |

Use values from your org's picklists. `Voice Agent` isn't a default Lead Source value, so add it to the picklist in Salesforce **Setup** first, or pin one you already use.

## How it works on a call

#### Identify the caller

The agent calls **Search leads** with the caller's number or email. A match returns the lead's ID.

#### Personalise the conversation

**Get lead** reads the full record, such as status, company and notes, so the agent doesn't ask for what you already know.

#### Capture or update

For a new caller, the agent collects name and company and calls **Create lead**. For a known one, it calls **Update lead** with what changed.

Example condition prompts:

| Tool             | Condition prompt                                                                      |
| ---------------- | ------------------------------------------------------------------------------------- |
| **Search leads** | *At the start of every call, search with the caller's phone number.*                  |
| **Create lead**  | *Only when the search found nothing and you have the caller's last name and company.* |
| **Update lead**  | *When a known caller gives new contact details or a new job title.*                   |

## Limits

* **Production orgs only.** Sign-in always goes through `login.salesforce.com`; sandboxes aren't supported.
* **Leads are the only searchable object.** Accounts and opportunities are read by ID.
* **One Salesforce org per organization.** To switch to a different one, click **Disconnect**, then **Connect** again.

## Troubleshooting

#### A Salesforce tool shows Reconnect on the Tools page

Access can no longer be renewed. Usually an admin revoked the app, or your org's refresh-token policy expired it. Click **Reconnect** and sign in again. Your tools and pins are kept.

#### Create or update fails with 'Provider rejected the request: HTTP 400: …'

Salesforce refused the record. The text after the colon is Salesforce's reason, such as the missing field. The usual causes are a missing required field, such as **Last name** or **Company** on a new lead, a validation rule, or a pinned value that a restricted picklist doesn't allow. Pinned values are sent exactly as typed, so copy them from the field's picklist in Salesforce **Setup**.

## Related

#### [Integrations overview](/voice-agents/integrate/integrations)

Connecting, pinning fields and disconnecting

#### [HubSpot](/integrations/connected-apps/hubspot)

Contacts, companies and deals