Salesforce Integration

Relevant source files

The following files were used as context for generating this wiki page:

• agent-packages/packages/salesforce/src/tools.ts
• agent-packages/packages/salesforce/src/account-tools.ts
• src/database/models/salesforce-config.model.ts
• src/integrations/integrations-install.service.ts
• agent-packages/packages/salesforce/src/index.ts
• agent-packages/packages/salesforce/src/task-tools.ts
• agent-packages/packages/salesforce/src/opportunity-tools.ts
• src/lib/constants.ts
• src/slack/views/modals.ts

The Salesforce integration for Quix enables the AI agent to connect with a Salesforce CRM, allowing users to query and manage Salesforce data directly from Slack. It provides a set of tools for interacting with standard Salesforce objects like Accounts, Opportunities, Tasks, and Users. The integration uses OAuth 2.0 for secure authentication and stores connection details in the application's database.

This integration is defined as a supported integration within the Quix ecosystem, allowing users to view and update opportunities, contacts, and accounts. It is designed to be modular, residing in its own package (@clearfeed-ai/quix-salesforce-agent) and exposing a standardized set of tools for the LLM agent to use.

Sources: src/lib/constants.ts:145-156, agent-packages/packages/salesforce/package.json:2

Architecture Overview

The Salesforce integration follows the standard Quix agent architecture. A user's request from Slack is processed by the main application, which leverages the LLM to select and execute the appropriate Salesforce tool. The SalesforceService acts as a bridge, using the jsforce library to communicate with the Salesforce API.

The following diagram illustrates the high-level data flow for a typical Salesforce-related query.

Installation and Configuration

The Salesforce integration is connected via an OAuth 2.0 authorization code grant flow. The configuration details, including access tokens and instance URL, are stored securely in the salesforce_configs table in the database.

Sources: src/integrations/integrations-install.service.ts:92-95, [src/database/models/salesforce-config.model.ts]

OAuth 2.0 Connection Flow

When a user initiates the connection from the Slack UI, they are redirected to Salesforce to authorize the application. After authorization, Salesforce redirects back to the Quix application with an authorization code, which is then exchanged for an access token and refresh token.

This sequence diagram shows the installation and authentication process.

Database Schema

The connection details are persisted in the salesforce_configs table, which is defined by the SalesforceConfig model.

This ER diagram shows the schema for the salesforce_configs table.

The fields of the SalesforceConfig model are detailed below:

Field	Type	Description
organization_id	string	The unique ID of the Salesforce organization. Primary Key.
team_id	string	The ID of the Slack workspace this configuration belongs to. Foreign Key.
access_token	string	The OAuth access token for API requests.
refresh_token	string	The OAuth refresh token to obtain new access tokens.
instance_url	string	The base URL for the Salesforce instance.
token_type	string	The type of token (e.g., 'Bearer').
scopes	string[]	An array of granted OAuth scopes.
authed_user_email	string	The email of the user who authorized the integration.
expires_at	Date	The timestamp when the access token expires.
default_prompt	string	An optional custom prompt to guide the LLM for Salesforce interactions.

Sources: src/database/models/salesforce-config.model.ts:11-53

Slack Configuration Modal

Admins can configure a default_prompt for the Salesforce integration via a Slack modal. This prompt provides custom instructions to the LLM when it interacts with Salesforce.

Sources: src/slack/views/modals.ts:687-718

Core Components

SalesforceService

The SalesforceService class is the primary service for interacting with the Salesforce API. It is initialized with a SalesforceConfig object and uses the jsforce library to handle API connections and requests.

Key responsibilities include:

• Establishing a connection to the correct Salesforce instance.
• Providing methods to find users, describe SObjects, and retrieve object details.
• Generating URLs for Salesforce records.

Sources: agent-packages/packages/salesforce/src/index.ts:12-25

LLM Prompts

The integration provides specific prompts to guide the LLM's behavior:

• SALESFORCE_TOOL_SELECTION_PROMPT: Helps the LLM decide when to use Salesforce tools based on the user's query. It describes the types of data managed by Salesforce (Leads, Accounts, Opportunities, etc.) and common user intents.
• SALESFORCE_RESPONSE_GENERATION_PROMPT: Instructs the LLM on how to format the data returned from Salesforce tools into a clear, human-readable response. It suggests including record IDs, bolding important details, and formatting dates.

Sources: agent-packages/packages/salesforce/src/tools.ts:8-29

Agent Tools

The integration exposes a collection of tools that the AI agent can use to perform actions in Salesforce. These tools are organized by the Salesforce object they interact with.

Sources: agent-packages/packages/salesforce/src/tools.ts:68-71

General Tools

These tools provide fundamental capabilities for interacting with Salesforce objects and users.

Tool Name	Description	Key Parameters
find_user	Find a user in Salesforce based on a name or email.	userIdentifier (name or email)
describe_object	Describe Salesforce objects such as accounts, contacts, opportunities.	objectName (e.g., Account, Contact)
get_object_details	Get details of a specific object in Salesforce.	objectId, objectType

Sources: agent-packages/packages/salesforce/src/tools.ts:38-67

Account Tools

These tools are for managing Account objects.

Tool Name	Description	Key Parameters
salesforce_search_accounts	Search for accounts by keyword.	keyword
salesforce_add_note_to_account	Add a note to a Salesforce account.	accountId, note, title (optional)

Sources: agent-packages/packages/salesforce/src/account-tools.ts:25-45

Opportunity Tools

These tools are for managing Opportunity objects.

Tool Name	Description	Key Parameters
salesforce_search_opportunities	Search for opportunities by keyword, stage, or owner.	keyword, stage, ownerId
salesforce_add_note_to_opportunity	Add a note to a Salesforce opportunity.	opportunityId, note, title (optional)
salesforce_get_opportunity_url	Get the URL to view an opportunity in Salesforce.	opportunityId
salesforce_get_opportunity_stages	Get all available opportunity stages.	(none)
salesforce_get_opportunity_count	Get the count of opportunities matching search criteria.	keyword, stage, ownerId

Sources: agent-packages/packages/salesforce/src/opportunity-tools.ts:31-76

Task Tools

These tools are for managing Task objects.

Tool Name	Description	Key Parameters
salesforce_create_task	Create a task in Salesforce.	subject, whatId, description, status, priority, ownerId, dueDate
salesforce_update_task	Update an existing task in Salesforce.	taskId, subject, description, status, priority, ownerId, dueDate
salesforce_delete_task	Delete a task in Salesforce (requires confirmation).	taskId
salesforce_get_tasks	Get tasks based on various filter criteria.	ownerId, subject, status, priority, type, dueDate, limit

Sources: agent-packages/packages/salesforce/src/task-tools.ts:116-155