# Salesforce Agent

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Overview</strong></td><td><ul><li>Search and retrieve Salesforce records — leads, contacts, accounts, and opportunities — through Blockbrain</li><li>Create, update, and manage records across any standard or custom Salesforce object</li><li>Resolve ambiguous or custom object names automatically using Salesforce's describe API</li><li>Read and analyze CRM data, extract key details, and get record summaries directly within conversations</li><li>Automate sales workflows and reporting using live Salesforce data</li></ul></td><td><a href="/files/ikR2AL5octrVSvEocI7Z">/files/ikR2AL5octrVSvEocI7Z</a></td></tr><tr><td><strong>Prerequisites</strong></td><td><ul><li>Complete the general setup steps from the main AI Agents page</li><li>Ensure users have active Salesforce accounts with appropriate object and field permissions</li><li>Verify your Salesforce edition supports API access (API access is available on Enterprise, Unlimited, Developer, and Performance editions)</li></ul></td><td><a href="/files/X7MpGP1nVARHAWPFype1">/files/X7MpGP1nVARHAWPFype1</a></td></tr></tbody></table>

### Overview

* Search and browse Salesforce objects, records, and fields through Blockbrain
* Create and update records across any queryable or writable Salesforce object
* Automatically resolve standard and custom object API names from plain-language descriptions
* List, filter, and analyze CRM records by status, owner, date, or any available field
* Support for both standard Salesforce objects and custom org-specific objects

### Prerequisites

* Complete the general setup steps from the main AI Agents page
* Ensure users have active Salesforce accounts with API access and the relevant object permissions
* Verify your Salesforce edition includes API access (Enterprise, Unlimited, Developer, or Performance editions)

### Salesforce Connected App Registration

#### Required OAuth Scopes

Add the following OAuth scopes when creating your Salesforce Connected App or External Client App:

| Permission       | Type      | Description                                                                                                                                                        |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `offline_access` | Delegated | Perform requests at any time - required to maintain persistent access without re-authentication                                                                    |
| `api`            | Delegated | Manage user data via Salesforce APIs - required for all record read and write operations                                                                           |
| `id`             | Delegated | Access the identity URL service - required for user authentication and identity verification                                                                       |
| `refresh_token`  | Delegated | Perform requests at any time - enables token refresh to maintain sessions without requiring repeated logins                                                        |
| `openid`         | Delegated | Access unique user identifiers - required for OpenID Connect authentication                                                                                        |
| `full`           | Delegated | Full access to all data accessible by the authenticated user - includes read and write access to all objects and fields permitted by the user's Salesforce profile |

> **Scope clarification:** The `api` scope provides comprehensive access to all Salesforce objects and records the authenticated user can access. Read-only fields are automatically excluded from write operations — Blockbrain's Salesforce Agent validates field permissions against each object's describe metadata before any create or update call. **Important:** These scopes are configured on the Blockbrain side during the activation step. Confirm the exact scope list with your Blockbrain Technical Project Manager before deployment.

#### Creating the **Salesforce Connected App**

1. Log in to **Salesforce**
2. Click the **gear icon** in the top right corner (next to your username) and select **Setup**
3. In the left sidebar, navigate to **Platform Tools** > **Apps** > **App Manager**
4. Click **New External Client App** in the top right corner

> **Note on App Types:** This guide uses Salesforce's newer **"External Client App"** framework. If this button is not visible in your instance, click **New Connected App** instead. All parameters — Callback URL, Scopes, and Keys — are identical for both options.

5. Fill in the basic information:
   * **App Name:** `Blockbrain`
   * **Contact Email:** Your email address (for system notifications)
6. Enable the **Enable OAuth Settings** checkbox
7. In the **Callback URL** field, enter:

   ```
   https://nango.theblockbrain.ai/oauth/callback  
   ```
8. Under **Selected OAuth Scopes**, add the following permissions (select each on the left and click **Add**):
   * Access the identity URL service *(id, profile, email, address, phone)*
   * Manage user data via APIs *(api)*
   * Perform requests at any time *(refresh\_token, offline\_access)*
   * Access unique user identifiers *(openid)*
   * Access the Salesforce API Platform *(sfap\_api)*
9. Click **Save**

#### Redirect URL

Add `https://nango.theblockbrain.ai/oauth/callback` as the **Callback URL** in your Salesforce Connected App or External Client App registration.

#### Retrieving your Credentials

Depending on which app type you created, credentials are located in different places. *(A new window or pop-up will open in each case.)*

**For "External Client Apps":**

1. Click **External Client App Manager** in the left navigation bar
2. Select the **Blockbrain** app from the table
3. Click the **Settings** tab
4. Open the **OAuth Settings** dropdown
5. Click **Consumer Key and Secret**

**For "Connected Apps":**

1. On the App Manager page, click **View** next to the Blockbrain app
2. Click **Manage Consumer Details** at the top

Then:

1. Enter the **verification code** sent to your email address
2. Copy the **Consumer Key** and **Consumer Secret** — store them securely for the next step

> **Important:** After creating a new app in Salesforce, it may take **2 to 10 minutes** for the changes to propagate across Salesforce servers. If the connection fails during activation, wait a moment and try again.

### Salesforce Agent Configuration in Blockbrain

<div align="center" data-full-width="false" data-with-frame="true"><figure><img src="/files/kG3aO1s9jUmrRCb6YMAS" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/F3iFjDUzyQKlLzj4Nk3U" alt=""><figcaption></figcaption></figure></div>

#### App Registration Details

* **Redirect URL:** `https://nango.theblockbrain.ai/oauth/callback`
* **Scopes:**
  * `offline_access`
  * `api`
  * `id`
  * `refresh_token`
  * `openid`
  * `full`

#### Configuration Steps

1. **Access Agent Settings:**
   * Navigate to your Blockbrain admin panel
   * Go to **Admin** > **Agents** > **Tools**
   * Find **Salesforce Tools** and enable the toggle switch
   * Click **Install** (or the gear icon for configuration)
2. **Enter Salesforce OAuth Credentials:**
   * **Client ID:** Paste the Consumer Key from Salesforce
   * **Client Secret:** Paste the Consumer Secret from Salesforce (use the eye icon to toggle visibility)
3. **Configure OAuth Scopes:**
   * Copy and paste the **Scopes** from the [#required-oauth-scopes](#required-oauth-scopes "mention")
4. **Additional Configuration (Optional):**
   * Configure custom key-value pairs for specific organizational requirements
   * Set up any org-specific restrictions as needed
5. **Save Configuration:**
   * Click **Save** to apply all settings
   * Wait for the confirmation message

### Testing the Salesforce Agent

#### Verification Steps

**Connection Test:**

* Use Blockbrain's built-in connection testing tool
* Verify successful OAuth flow with Salesforce

**Record Access:**

* Have a test user connect their Salesforce account
* Attempt to list records for a known object (e.g., Accounts or Contacts)
* Verify record content retrieval (e.g., reading a specific lead's fields)

**Create Functionality:**

* Test creating a new record in a safe/test object
* Verify that read-only fields are automatically excluded from the payload
* Confirm the new record appears in Salesforce

**Update Functionality:**

* Test updating an existing record field (e.g., lead status or contact phone number)
* Confirm the change is reflected directly in Salesforce

**Object Discovery:**

* Ask Blockbrain to identify an object by a label (e.g., "Member Accounts")
* Verify the agent correctly resolves it to the Salesforce API name
* Confirm the resolved name is used in a subsequent operation

### Common Integration Use Cases

#### **Lead & Contact Management**

* **Lead Search**: Find and filter leads by name, status, company, or creation date
* **Contact Lookup**: Retrieve contact details for any account or individual
* **Record Creation**: Add new leads or contacts directly from a Blockbrain conversation

#### **Account & Opportunity Management**

* **Account Research**: Pull full account details, related contacts, and open opportunities
* **Pipeline Tracking**: List opportunities by stage, close date, or owner
* **Deal Updates**: Update opportunity stages, amounts, or close dates without leaving the chat

#### **CRM Data Analysis**

* **Record Summaries**: Get structured summaries of any Salesforce record
* **Field Extraction**: Extract specific field values across multiple records
* **Custom Object Support**: Query and manage org-specific custom objects using plain-language descriptions

### Troubleshooting

#### Authentication Issues

| Symptom                                            | Cause                         | Solution                                                                           |
| -------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| OAuth authentication failures or "invalid\_client" | Incorrect credentials         | Verify the Consumer Key and Consumer Secret are correctly entered in Blockbrain    |
| OAuth flow doesn't complete                        | Wrong callback URL            | Ensure the Callback URL is exactly `https://nango.theblockbrain.ai/oauth/callback` |
| Token stops working                                | App deleted or secret rotated | Regenerate credentials in Salesforce and update the Blockbrain configuration       |
| Connection fails immediately after app creation    | Propagation delay             | Wait 2–10 minutes after creating the Salesforce app, then try again                |

#### **Record Access** Errors

| Symptom                             | Cause                    | Solution                                                         |
| ----------------------------------- | ------------------------ | ---------------------------------------------------------------- |
| "NOT\_FOUND" when accessing records | User lacks record access | Confirm the user can view the record directly in Salesforce      |
| Object not visible                  | API access not enabled   | Verify the user's Salesforce profile has API Enabled permission  |
| Intermittent access issues          | Account mismatch         | Verify the user is connected with the correct Salesforce account |

#### **Field & Write** Errors

| Symptom                              | Cause                             | Solution                                                                                         |
| ------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
| Record creates with missing fields   | Fields are read-only              | Blockbrain automatically skips read-only fields — check field editability directly in Salesforce |
| "No creatable fields provided" error | All supplied fields are read-only | Supply at least one writable field; check field-level security in Salesforce Setup               |
| Update fails silently                | Field-level security restriction  | Confirm the user's profile has edit access to the target field                                   |

#### Scope Configuration Problems

| Symptom                          | Cause              | Solution                                                                                           |
| -------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| Scopes not being saved           | Input error        | Paste the full scope string exactly as specified in the configuration steps                        |
| Missing capabilities after setup | Incomplete scopes  | Ensure all required scopes are present: [#required-oauth-scopes](#required-oauth-scopes "mention") |
| API calls rejected               | Wrong scope format | Scopes must be comma-separated; verify no typos or extra characters                                |

### Security and Compliance

#### Data Protection

* **Record Security**: All Salesforce data is handled according to Blockbrain's security policies
* **Field Privacy**: Field-level access respects Salesforce profile permissions and field-level security rules
* **Token Security**: OAuth tokens are securely stored and encrypted — credentials are never exposed to end users

#### Compliance Considerations

* **GDPR Compliance**: CRM record access and processing follows GDPR requirements
* **Data Retention**: No Salesforce record content is permanently stored by Blockbrain — data is processed in real-time
* **Audit Logging**: All Salesforce Agent activities are logged for compliance reporting

#### Access Control

* **User Permissions**: The agent inherits the authenticated user's Salesforce permissions — no privilege escalation is possible
* **Object-Level Security**: Respects Salesforce object-level and record-level sharing rules
* **Field-Level Security**: Read-only fields are automatically identified and excluded from write operations

### Next Steps

After successful Salesforce Agent configuration:

1. **User Training**: Share the Salesforce Agent user guide with end users
2. **Permission Review**: Regularly audit user Salesforce profiles to ensure appropriate object and field permissions
3. **Integration Monitoring**: Monitor the OAuth connection for ongoing functionality
4. **Feature Adoption**: Encourage teams to leverage lead management, pipeline tracking, and custom object capabilities

### Support and Resources

For assistance with Salesforce Agent configuration:

* **Blockbrain Support**: Contact your Customer Success Manager for feature-specific help
* **Salesforce Documentation**: Reference [Salesforce Connected Apps documentation](https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm) for detailed permission information
* **Salesforce Admins**: For org-level OAuth app policies and API access, consult your Salesforce Administrator


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockbrain.ai/for-admins/agents/salesforce-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.