Home

Relevant source files

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

• README.md
• PROJECT_DESCRIPTION.md
• src/App.tsx
• src/LandingPage.tsx
• convex/ai.ts
• agent_configs/SIMPLE-Co-Sales-Agent.json
• index.html
• GTM_STRATEGY.md

TalkCRM is a voice-first AI assistant designed to let sales representatives interact with their Salesforce CRM hands-free. The core problem it solves is the significant amount of time (estimated at 5.5 hours per week) that sales reps spend on manual CRM data entry, which detracts from selling activities and leads to poor data quality. TalkCRM allows reps to update their pipeline, manage tasks, and log calls using natural language voice commands, typically from their phone.

The system is built on a modern tech stack that combines conversational AI, a serverless backend, and direct integration with the Salesforce API. The goal is to make CRM updates faster (30 seconds by voice vs. 5+ minutes typing) and more convenient, thereby increasing rep productivity and improving pipeline data accuracy.

Sources: PROJECT_DESCRIPTION.md:3-9, GTM_STRATEGY.md:10-15, src/LandingPage.tsx:132-135

System Architecture

TalkCRM's architecture is designed to process voice commands from a sales rep, interpret their intent using an AI model, perform actions against the Salesforce API, and return a spoken response. The system is composed of several key services that work in concert.

Sources: README.md:11-46, PROJECT_DESCRIPTION.md:17-25

This diagram illustrates the high-level data flow from the user to Salesforce and back.

Technology Stack

The project utilizes a combination of specialized services for voice, AI, backend, and frontend development.

Component	Technology	Purpose
Voice AI	ElevenLabs Conversational AI	Provides the natural language voice agent, including ASR and TTS.
Backend	Convex	Handles serverless functions (HTTP actions), real-time database, and subscriptions.
CRM	Salesforce	The source of truth for all customer data.
Telephony	Twilio	Provides the phone number and voice connectivity.
Frontend	React + Vite	Powers the user-facing dashboard and landing page.
Styling	Tailwind CSS	Used for UI components and styling.
Authentication	WorkOS	Manages user sign-in and authentication.

Sources: README.md:53-61, src/App.tsx:2, src/App.tsx:458-464

User Flow and Application Entry

The application handles different user states (unauthenticated, authenticating, authenticated) through a simple routing and state management mechanism in the root App.tsx component.

*Sources: src/App.tsx *

Authentication Flow

The user journey from landing on the page to accessing the authenticated application is as follows:

1. An unauthenticated user visits the site and is shown the LandingPage.
2. The user clicks "Log in" or "Get started", which triggers the onLogin or onSignup callbacks, setting state to show the LoginPage component.
3. Authentication is handled by the @workos-inc/authkit-react hook.
4. Upon successful authentication, the user is redirected to the /callback path.
5. The App component detects the /callback path and the presence of a user object, then redirects to the home route (/).
6. The authenticated user is then shown the InstallationPage component, which displays their user information and instructions for setting up TalkCRM.

This diagram shows the conditional rendering and navigation flow for a user.

Frontend

The frontend is a React application built with Vite. It serves both the public-facing marketing content and the private, authenticated user dashboard.

Landing Page

The LandingPage.tsx component is the main entry point for new visitors. Its purpose is to explain the value proposition of TalkCRM and encourage sign-ups.

Key sections include:

• Hero Section: A headline emphasizing the ability to "Update Salesforce with your voice" and a subheadline targeting the pain point of CRM data entry.
• Demo Video: An embedded video (/talkcrm-demo.mp4) that shows the product in action.
• Features: A grid of FeatureCard components highlighting key benefits.
• How It Works: A 3-step guide to setting up and using the service.
• Call-to-Action (CTA): Buttons to "Start for free" or "Watch demo".

Sources: src/LandingPage.tsx:98-235

The features highlighted on the landing page are:

Feature	Description
10x faster updates	Updates take 30 seconds by voice versus 5 minutes of typing.
Real-time accuracy	The pipeline is always current because updates happen in the moment.
Works from anywhere	No app is needed; users call in from their phone.
Natural language	The AI understands conversational commands.
Tasks & follow-ups	Users can create reminders and tasks by voice.
Permissions respected	The system uses the user's existing Salesforce roles and permissions.

Sources: src/LandingPage.tsx:238-285

Installation Page

Once a user is authenticated, the InstallationPage (defined within App.tsx) is displayed. This page guides the user through the final setup steps.

It includes:

1. Salesforce Package Installation: Provides links to install the TalkCRM package in either a Salesforce Production or Sandbox environment.
2. Setup Instructions: A four-step guide on how to install the package, approve access, and start using the service.
3. TalkCRM Hotline: Displays the dedicated phone number (+1 (646) 600-5041) for the user to call.
4. Integrations: A section for configuring other integrations, such as Slack.
5. Technical Details: A collapsible section with an architecture diagram, tech stack summary, and a list of available voice commands and Salesforce tools.

Sources: src/App.tsx:100-410

SEO and Metadata

The index.html file is heavily optimized for search engines, containing multiple application/ld+json script blocks for structured data. This helps search engines understand the product's features, purpose, and pricing.

The following structured data types are defined:

• SoftwareApplication: Describes TalkCRM, its features, and the free beta offer.
• Organization: Provides details about the TalkCRM organization.
• Product: Defines the "TalkCRM Voice Assistant for Salesforce" product.
• FAQPage: Contains common questions and answers about the service for rich snippets.
• HowTo: A step-by-step guide on how to use TalkCRM, also for rich snippets.

Sources: index.html:73-248

Core AI System

The intelligence of TalkCRM resides in its AI agent, which is responsible for understanding user intent and interacting with Salesforce.

AI Agent Configuration

The AI's personality and capabilities are defined in a JSON configuration file. The agent is configured to act as "Adam Anzuoni, founder of The Simple Company," an expert in Salesforce and AI systems.

• Goal: To qualify leads, understand their pain points, and schedule demos.
• Tone: Direct, confident, technically credible, and helpful.
• Channel Awareness: The agent adapts its communication style for voice calls versus WhatsApp messages.
• Tools: The agent has access to a suite of calcom tools for scheduling, such as calcom_get_available_slots and calcom_create_booking.

Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:20-100

AI Logic and Intent Parsing

The core logic is handled by the askSalesforce action in convex/ai.ts. This function orchestrates the process of interpreting a user's natural language message and executing the corresponding Salesforce operation.

The flow is as follows:

1. The askSalesforce action receives the user's message.
2. It fetches the user's specific Salesforce org metadata to provide the AI with context about available custom objects and fields.
3. It calls the interpretWithClaude function, sending the user message, conversation history, and the Salesforce schema context to the Anthropic Claude LLM.
4. Claude interprets the request and returns a structured JSON object (ParsedIntent) containing the action to perform (e.g., search, create), the target object, and any necessary data.
5. The askSalesforce action then executes the requested operation by calling the appropriate Salesforce action (e.g., api.salesforce.searchRecords).
6. The result from Salesforce is formatted into a user-friendly, spoken response.

This sequence diagram shows the interaction between the components.

The interpretWithClaude function is crucial, as it uses a detailed system prompt to instruct the LLM on how to parse requests and what JSON format to return. The prompt includes definitions of standard Salesforce objects, field names, and rules for constructing SOQL queries.

Sources: convex/ai.ts:10-155, convex/ai.ts:476-550

Salesforce Integration

The connection to Salesforce is the most critical part of the system, enabling the AI to perform meaningful actions.

Available Tools

The AI agent has access to a set of predefined tools that map to functions interacting with the Salesforce REST API.

Tool	Description	Corresponding Action
search_salesforce	Find accounts, contacts, opportunities, and leads.	api.salesforce.searchRecords
get_record	Get full details of a specific record.	api.salesforce.searchRecords (with ID)
create_record	Create new accounts, contacts, leads, or tasks.	api.salesforce.createRecord
update_record	Update fields on an existing record.	api.salesforce.updateRecord
log_call	Log a call activity to a Salesforce record.	api.salesforce.logCall
get_my_tasks	View the user's open tasks.	api.salesforce.getMyTasks
get_my_pipeline	View the user's open opportunities.	api.salesforce.getMyOpportunities

Sources: README.md:65-73, convex/ai.ts:119-124

Org Metadata Sync

To enable the AI to understand a user's specific Salesforce configuration, including custom objects and fields, the system automatically syncs schema metadata.

• Discovery: The system discovers all standard and custom objects (e.g., Invoice__c).
• Metadata Capture: It captures field names, labels, types, and picklist values.
• Contextualization: This metadata is compiled into the system prompt for the Claude LLM, allowing it to generate accurate SOQL queries and API payloads for that specific org.
• Refresh: A weekly cron job automatically refreshes the metadata to keep it current.

This diagram shows how user context is used to generate an AI response.