Salesforce Integration Overview

Relevant source files

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

• convex/salesforce.ts
• salesforce-package/sfdx-project.json
• convex/ai.ts
• convex/http.ts
• convex/orgMetadata.ts
• salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html
• README.md
• salesforce-package/POST_DEPLOY_GUIDE.md

The Salesforce integration is the core component of TalkCRM, enabling users to interact with their Salesforce data using natural language through voice, text, or Slack. It acts as a bridge between the user-facing interfaces (like ElevenLabs Voice AI and Twilio) and the Salesforce REST API, orchestrated by a Convex backend. The system uses AI to interpret user intent and perform corresponding CRUD (Create, Read, Update, Delete) operations, search, and queries within Salesforce.

This integration is designed to be multi-tenant, supporting different Salesforce orgs through a combination of a managed package and a dynamic OAuth 2.0 authentication system. A key feature is the ability to sync an organization's custom object schema, allowing the AI to understand and interact with bespoke Salesforce configurations.

Sources: README.md, convex/ai.ts, convex/salesforce.ts

Architecture

The integration connects various services to translate a user's voice or text command into a Salesforce API call. The primary components are the user interface (phone/web), the AI layer, the Convex backend, and the Salesforce REST API.

The diagram below illustrates the high-level data flow from a sales representative to Salesforce and back.

Sources: README.md, convex/http.ts

Components

Component	Technology	Purpose
Voice/Text Interface	Twilio, ElevenLabs	Provides the phone number and conversational AI agent for voice and text interactions.
Backend	Convex	Hosts serverless functions (HTTP actions, mutations, queries) that orchestrate API calls and manage data.
AI Brain	Anthropic Claude	Interprets natural language requests and determines the appropriate Salesforce operation to perform.
CRM	Salesforce	The source of truth for all customer data, accessed via its REST API.

Sources: README.md, convex/ai.ts, convex/http.ts

Authentication and Setup

The system supports a multi-tenant architecture, allowing different users from different Salesforce orgs to connect securely. Authentication is handled via OAuth 2.0. There are two primary setup flows: one initiated from the TalkCRM web app and another initiated from within Salesforce via a Lightning Web Component (LWC).

Sources: convex/http.ts:1000-1196

Salesforce LWC Setup Flow

The Salesforce package includes a setup LWC that guides users through connecting their org. This flow uses per-org Connected App credentials for enhanced security.

1. Admin Configures Credentials: An admin enters the org's Connected App Consumer Key and Consumer Secret into the LWC. These are saved in the Convex backend.
2. User Initiates OAuth: The user clicks "Connect Salesforce" in the LWC.
3. Redirection to Salesforce: The browser is redirected to the org's specific OAuth authorization endpoint.
4. User Grants Access: The user approves the access request.
5. Callback to Convex: Salesforce redirects to a Convex HTTP endpoint (/auth/salesforce/callback) with an authorization code.
6. Token Exchange: The Convex backend exchanges the code for an access token and refresh token.
7. User Creation & Token Storage: A TalkCRM user is created (if one doesn't exist), and the Salesforce tokens are securely stored, linked to the user.
8. Redirection to LWC: The user is redirected back to the LWC with a success status.

Sources: salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html, convex/http.ts:1052-1196

The following sequence diagram details the LWC OAuth flow.

Sources: convex/http.ts:1052-1196, salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:103-112

AI-Powered Operations

The core of the integration is the askSalesforce action in convex/ai.ts, which uses the Anthropic Claude AI model to interpret natural language and convert it into Salesforce operations.

Sources: convex/ai.ts:153-214

AI Context and Prompting

To enable the AI to generate valid SOQL queries and API payloads, it is provided with a detailed system prompt containing the Salesforce schema. This includes:

• A list of key standard objects and their fields (Account, Contact, Lead, etc.).
• Picklist values for important fields like Opportunity.StageName and Lead.Status.
• Instructions on using SOQL date literals (TODAY, THIS_WEEK, LAST_N_DAYS:7).
• Crucially, it includes metadata for custom objects synced from the user's org.

Sources: convex/ai.ts:9-149

Intent Parsing and Execution Flow

When a user message is received, the askSalesforce action orchestrates the following steps:

1. Load Org Context: Fetches custom object metadata for the user's org to enrich the AI's knowledge.
2. Interpret with Claude: Calls the interpretWithClaude function, which sends the user's message and conversation history to the Claude API.
3. Receive Parsed Intent: Claude returns a JSON object (ParsedIntent) containing the determined action, object type, fields, and a user-facing response.
4. Execute Action: A switch statement routes the parsed intent to the appropriate Convex action that interacts with the Salesforce API (e.g., api.salesforce.searchRecords, api.salesforce.createRecord).
5. Return Response: The result from the Salesforce action is formatted and returned to the user.

Sources: convex/ai.ts:153-300

Supported AI Actions

The AI can decide to perform one of the following actions based on the user's request.

Action	Description	Example User Request
search	Finds records by name or keyword.	"Find Acme"
query	Runs a specific SOQL query for data retrieval.	"Show me my open opportunities closing this quarter"
create	Creates a new record (e.g., Task, Lead, Case).	"Create a task to call John tomorrow"
update	Updates fields on an existing record.	"Update the Acme deal to Negotiation"
log_call	Logs a call activity against a record.	"Log this call"
clarify	Asks the user a question if the intent is ambiguous.	"Should I create a support case or a task?"

Sources: convex/ai.ts:684-716

Org Metadata Sync

To support custom Salesforce configurations, TalkCRM automatically syncs schema information from connected orgs. This process discovers custom objects and their fields, making them available to the AI assistant.

The syncFromSalesforce action in convex/orgMetadata.ts is responsible for this. It performs the following steps:

1. Fetches the latest Salesforce API version.
2. Performs a "Describe Global" API call to get a list of all sObjects.
3. Filters for queryable custom objects (__c) and a predefined list of important standard objects.
4. For each custom object, it performs another describe call to get detailed field metadata, including field names, types, labels, and picklist values.
5. It attempts to query for a sample record and record count to identify commonly used fields.
6. The collected metadata is stored in the orgMetadata table in Convex, linked to the org's instanceUrl.

This sync is triggered automatically by a weekly cron job (syncAllOrgs) and can also be triggered manually.

Sources: convex/orgMetadata.ts:213-404

Salesforce Package

TalkCRM provides a Salesforce package to facilitate setup and integration directly within the user's org.

• Package Name: TalkCRM
• Package Version: 0.2.0.0 (as of the files)

The package includes:

• talkCrmSetup LWC: A Lightning Web Component that guides users through the multi-step setup process, including credential configuration and OAuth connection.
• TalkCRM User Permission Set: A permission set to grant users access to the TalkCRM application components within Salesforce.
• TalkCRM App: An app definition that provides a dedicated tab for the setup wizard in the Salesforce App Launcher.

Sources: salesforce-package/sfdx-project.json:2-4, salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html, salesforce-package/POST_DEPLOY_GUIDE.md:15-21

Summary

The Salesforce integration is the foundational pillar of TalkCRM. It leverages a sophisticated, AI-driven architecture on the Convex platform to provide a seamless, voice-first user experience for interacting with Salesforce. By combining a managed package for easy setup, a robust multi-tenant OAuth system for security, and an intelligent metadata sync for customizability, the integration allows sales reps to manage their CRM data efficiently from anywhere, simply by talking.

Sources: README.md, PROJECT_DESCRIPTION.md