Salesforce Development (LWC & Apex)

Relevant source files

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

• salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html
• salesforce-package/POST_DEPLOY_GUIDE.md
• README.md
• src/App.tsx
• convex/http.ts
• convex/ai.ts

The Salesforce integration is a core component of TalkCRM, enabling the voice assistant to interact with a user's CRM data. This is accomplished through a Salesforce package that includes a Lightning Web Component (LWC) for setup and authentication. The backend relies on a predefined schema context to interpret natural language commands and translate them into Salesforce operations via the REST API.

The overall architecture involves the user's phone, a voice AI provider (ElevenLabs), the Convex backend, and the Salesforce REST API. The Salesforce package is the primary entry point for a user to connect their org to the TalkCRM service.

Sources: README.md:10-41

Salesforce Package

TalkCRM is distributed as a Salesforce package that can be installed in both production and sandbox environments. The package contains the necessary components to configure the connection to the TalkCRM service.

Sources: README.md:6-8, src/App.tsx:160-189

Installation

Installation is done via direct links provided in the TalkCRM web application. There are separate links for production and sandbox orgs.

Environment	Package ID
Production	04tHn000000QBNdIAO
Sandbox	04tHn000000QBNdIAO

Sources: src/App.tsx:163-174, src/App.tsx:177-188, README.md:7-8

Post-Deployment Setup

After deploying the package, an administrator must perform the following steps:

1. Assign Permission Set: Users must be assigned the TalkCRM User permission set to access the application's components.
2. Launch TalkCRM App: Users can find and launch the "TalkCRM" app from the App Launcher.
3. Complete Setup Wizard: The user is guided through a multi-step wizard within the talkCrmSetup LWC to connect their account.

Sources: salesforce-package/POST_DEPLOY_GUIDE.md:11-30

talkCrmSetup Lightning Web Component

This LWC provides a step-by-step wizard for users to configure their connection to TalkCRM.

The following diagram illustrates the user flow through the setup wizard.

Setup Steps

Step	Title	Description
1	Configure Connected App	The user must provide the Consumer Key and Consumer Secret from the TalkCRM Voice Assistant Connected App in their Salesforce org. This is required for the multi-tenant OAuth flow.
2	Connect Salesforce	The user initiates an OAuth 2.0 flow to authorize TalkCRM to access their Salesforce data on their behalf.
3	Verify Phone Number	The user enters their phone number, receives a verification code via SMS, and enters the code to link their phone to their account.
4	Ready!	The setup is complete. The component displays the TalkCRM phone numbers for voice and text, along with example commands. It also provides an option to connect to Slack.

Sources: salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:21-177

Example Voice Commands

Once setup is complete, the user is encouraged to try the following commands:

• "What's in my pipeline?"
• "Find the Acme account"
• "Create a task to call John tomorrow"
• "Update the Acme deal to Closed Won"

Sources: salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:145-150

Authentication Flow (OAuth 2.0)

TalkCRM uses a per-org OAuth 2.0 flow initiated from the talkCrmSetup LWC. This allows the application to securely authenticate with each user's Salesforce instance without storing user credentials.

The sequence diagram below shows the authentication process.

This diagram illustrates the OAuth flow for connecting a Salesforce account from the LWC.
Sources: convex/http.ts:1133-1304

Key Endpoints

• GET /auth/salesforce/initiate: Called by the LWC to start the OAuth flow. It looks up the org-specific Consumer Key and redirects the user to the Salesforce authorization endpoint. The state parameter is used to pass the LWC callback URL and instance URL through the flow.
• GET /auth/salesforce/callback: The redirect URI that Salesforce calls after the user grants consent. The backend exchanges the authorization code for an access token and refresh token, retrieves user information, stores the credentials, and finally redirects the user back to the LWC.

Sources: convex/http.ts:1133-1209, convex/http.ts:1216-1304

AI Schema Context

The backend AI assistant (Claude) is provided with a detailed schema of available Salesforce objects and fields to correctly interpret natural language queries and construct valid SOQL.

Standard Objects

The AI is aware of the following key standard Salesforce objects and their fields:

This ER diagram shows the primary Salesforce objects and their relationships as understood by the AI.
Sources: convex/ai.ts:11-23

Custom Objects

The system is designed to dynamically discover and use custom objects within a user's Salesforce org.

1. Metadata Sync: A weekly cron job or manual trigger syncs metadata for all connected orgs.
2. Object Discovery: The sync process fetches all custom objects (__c) that are queryable.
3. Field Discovery: For each custom object, it fetches all queryable fields, their types, labels, and picklist values.
4. AI Context: This rich metadata is passed to the AI model, allowing it to construct queries for custom objects and fields like Invoice__c or sendblue__Message__c.

Sources: convex/orgMetadata.ts:179-340, convex/ai.ts:188-269

SOQL Generation Rules

The AI follows specific rules when generating SOQL queries:

• For user-specific queries ("my leads", "my accounts"), it must use OwnerId = CURRENT_USER.
• It uses SOQL date literals (e.g., TODAY, THIS_WEEK, LAST_N_DAYS:7) for time-based filters.
• It only selects fields that are explicitly listed in the provided schema context to avoid errors.

Sources: convex/ai.ts:80-84, convex/ai.ts:65-79