Salesforce Agent

This page provides detailed configuration instructions for the Salesforce Agent, which enables integration with Salesforce CRM for lead management, contact tracking, account management and more.

Overview

• Search and retrieve Salesforce records — leads, contacts, accounts, and opportunities — through Blockbrain

• Create, update, and manage records across any standard or custom Salesforce object

• Resolve ambiguous or custom object names automatically using Salesforce's describe API

• Read and analyze CRM data, extract key details, and get record summaries directly within conversations

• Automate sales workflows and reporting using live Salesforce data

Prerequisites

• Complete the general setup steps from the main AI Agents page

• Ensure users have active Salesforce accounts with appropriate object and field permissions

• Verify your Salesforce edition supports API access (API access is available on Enterprise, Unlimited, Developer, and Performance editions)

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.

1. Fill in the basic information:

   • App Name: Blockbrain

   • Contact Email: Your email address (for system notifications)

2. Enable the Enable OAuth Settings checkbox

3. In the Callback URL field, enter:

   https://nango.theblockbrain.ai/oauth/callback  

4. 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)

5. 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

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

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
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 for detailed permission information

• Salesforce Admins: For org-level OAuth app policies and API access, consult your Salesforce Administrator