Prerequisites & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Setting up TalkCRM involves configuring both the developer environment and the end-user-facing Salesforce package. The core backend is built on Convex, which orchestrates interactions between the voice AI provider (ElevenLabs), telephony (Twilio), and the CRM (Salesforce). Authentication is handled via WorkOS for the web dashboard and a multi-tenant OAuth 2.0 flow for Salesforce integration.
This guide covers the necessary prerequisites, environment variable setup, Salesforce package installation, and AI agent configuration required to get the TalkCRM application fully operational.
Developer Environment Setup
To run the TalkCRM project locally, a developer must set up several services and configure the local environment to connect them.
Sources: README.md:104-107
Prerequisites
The following accounts and tools are required for development:
- Node.js v18+
- A Convex account
- An ElevenLabs account with Conversational AI access
- A Twilio account with a phone number
- A Salesforce org (Developer Edition is sufficient)
Sources: README.md:104-107
Convex Environment Variables
The Convex backend requires several environment variables to be set in the Convex project dashboard. These variables handle authentication and integration with third-party services.
Sources: README.md:113-126
| Variable | Description | Example | Source File |
|---|---|---|---|
GOOGLE_CLIENT_ID | Google OAuth Client ID for user authentication. | your_google_client_id | README.md:114 |
GOOGLE_CLIENT_SECRET | Google OAuth Client Secret. | your_google_client_secret | README.md:115 |
AUTH_SECRET | A random secret key for signing authentication tokens. | Generated via openssl rand -base64 32 | README.md:116 |
CONVEX_SITE_URL | The public URL of your Convex deployment. | https://your-deployment.convex.site | README.md:117 |
SALESFORCE_ACCESS_TOKEN | Salesforce access token for API calls. | your_token | README.md:120 |
SALESFORCE_INSTANCE_URL | The instance URL of your Salesforce org. | https://yourorg.my.salesforce.com | README.md:121 |
ANTHROPIC_API_KEY | API key for Claude AI. | your_key | README.md:124 |
For Google OAuth, the authorized redirect URI must be configured in the Google Cloud Console to https://your-deployment.convex.site/api/auth/callback/google.
Sources: README.md:128-130
External Service Configuration
The following diagram illustrates the dependency and configuration flow between the external services.
This diagram shows that Twilio phone numbers are configured to connect to an ElevenLabs agent. The agent is configured with tools that make calls to Convex HTTP endpoints. The Convex backend, in turn, is configured with environment variables to connect to Salesforce, Anthropic, and Google for authentication.
Sources: README.md:132-141, README.md:25-56
- ElevenLabs: The agent configuration and tool definitions must be pushed to ElevenLabs using the
elevenlabs tools pushandelevenlabs agents pushcommands. - Twilio: The Twilio phone number's webhook must be set to point to the ElevenLabs Conversational AI WebSocket endpoint, specifying the correct agent ID.
Sources: README.md:132-141
Salesforce Package Installation
A Salesforce administrator is required to install and configure the TalkCRM package. The process involves installing the package from a URL and completing a setup wizard within Salesforce.
Sources: src/App.tsx:142-145, salesforce-package/POST_DEPLOY_GUIDE.md:10-12
Installation Steps
The installation UI provides separate links for Production and Sandbox environments.
| Step | Action | Description | Source File |
|---|---|---|---|
| 1 | Install Package | Use the appropriate link to install in either a Production or Sandbox org. | src/App.tsx:151-174 |
| 2 | Select Users | Choose "Install for All Users" to grant necessary access. | src/App.tsx:179-185 |
| 3 | Approve Access | Grant third-party access to allow API permissions for TalkCRM. | src/App.tsx:188-194 |
| 4 | Assign Permissions | Assign the TalkCRM User permission set to all users who need access. | salesforce-package/POST_DEPLOY_GUIDE.md:14-20 |
Sources: src/App.tsx:147-194, salesforce-package/POST_DEPLOY_GUIDE.md:14-20
Post-Deployment Setup Wizard
After installation, users are guided through a setup wizard within the TalkCRM Lightning Web Component.
The following diagram shows the flow of the setup wizard.
- Configure Connected App: The user must enter the
Consumer KeyandConsumer Secretfrom the TalkCRM Connected App in their Salesforce org. - Connect Salesforce: The user initiates an OAuth flow to authorize TalkCRM to access their Salesforce data.
- Verify Phone: The user enters their phone number and verifies it with a code sent via SMS.
- Ready: The setup is complete, and the user is shown the TalkCRM phone numbers for voice and text.
Sources: salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:22-130, salesforce-package/POST_DEPLOY_GUIDE.md:25-36
Authentication Configuration
TalkCRM uses two primary authentication mechanisms: WorkOS for the web dashboard and a multi-tenant Salesforce OAuth flow for CRM integration.
Web App Authentication
The frontend application uses @workos-inc/authkit-react for user authentication. The main App.tsx component handles the routing and authentication state, showing a login page or the main installation page based on whether a user is authenticated.
Sources: src/App.tsx:2-4, src/App.tsx:21-22
Salesforce OAuth Flow
TalkCRM supports a multi-tenant OAuth flow, allowing different Salesforce orgs to connect securely using their own Connected App credentials.
The flow is initiated from the LWC setup wizard and handled by Convex HTTP endpoints.
This sequence diagram illustrates the Salesforce OAuth 2.0 authorization code grant flow, managed by the Convex backend.
Sources: convex/http.ts:1011-1188
Key endpoints involved:
/auth/salesforce/initiate: Builds the Salesforce authorization URL using the org-specificconsumerKeyand redirects the user./auth/salesforce/callback: Receives the authorization code from Salesforce, exchanges it for access/refresh tokens, fetches user info, and stores the credentials securely in the Convex database.
Sources: convex/http.ts:1011-1077, convex/http.ts:1086-1188
AI Agent Configuration
The AI agents used by ElevenLabs are defined in JSON configuration files. These files specify the agent's personality, tools, and behavior for voice conversations.
Sources: agent_configs/SIMPLE-Co-Sales-Agent.json
Configuration Structure
The agent configuration is a JSON object with two main keys: conversation_config and platform_settings.
This diagram shows the high-level structure of an agent configuration file.
Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:2-3
Key Configuration Sections
conversation_config
This object defines the core behavior of the voice conversation.
| Key | Description | Example Value | Source |
|---|---|---|---|
asr | Automatic Speech Recognition settings. | { "provider": "elevenlabs", "quality": "high" } | agent_configs/SIMPLE-Co-Sales-Agent.json:4-8 |
tts | Text-To-Speech settings, including voice ID, model, and speech parameters. | { "voice_id": "mHV5m7DLaQM0bIAP6BTK", "speed": 1.07 } | agent_configs/SIMPLE-Co-Sales-Agent.json:18-28 |
turn | Turn-taking behavior, including timeouts and eagerness. | { "turn_timeout": 5, "turn_eagerness": "eager" } | agent_configs/SIMPLE-Co-Sales-Agent.json:9-17 |
agent | Defines the AI agent's core logic, including its prompt and available tools. | See below. | agent_configs/SIMPLE-Co-Sales-Agent.json:49-142 |
agent.prompt
This is the system prompt that defines the agent's personality, goals, and rules. It includes detailed instructions on how to interact with users, what qualification questions to ask, and how to use its tools.
Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:54-141
agent.tools
This array defines the external tools the agent can call. Each tool is an api_integration_webhook that corresponds to a Convex HTTP endpoint. The agent uses these tools to interact with external systems like Cal.com for scheduling.
Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:141-204
platform_settings
This object configures how the agent is presented on different platforms, such as the web widget. It includes settings for UI, privacy (data retention, recording), and authentication.
Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:206-337
Conclusion
The configuration of TalkCRM is multifaceted, involving developer environment setup, Salesforce package deployment, robust authentication flows, and detailed AI agent definitions. The system is designed for multi-tenancy, with Convex acting as the central hub that securely manages credentials and orchestrates communication between all integrated services. A successful setup requires careful configuration of environment variables, Salesforce connected apps, and the various webhooks that tie the components together.