Call & Command Data Flow

Relevant source files

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

• convex/ai.ts
• convex/http.ts
• convex/salesforce.ts
• convex/slackCommands.ts
• convex/slackBlocks.ts
• agent_configs/TalkCRM.json
• README.md
• PROJECT_DESCRIPTION.md

The Call & Command Data Flow system is the core of TalkCRM, enabling users to interact with Salesforce through natural language commands from multiple channels, including voice calls and Slack. The system is designed around a central AI assistant that interprets user intent and orchestrates actions against the Salesforce API. This document outlines the architecture and data flow for processing these commands.

The architecture is built on a serverless backend using Convex, which handles HTTP actions, real-time database operations, and external API orchestration. It integrates with third-party services like Twilio for telephony, ElevenLabs for conversational voice AI, and Anthropic's Claude for natural language understanding.

High-Level Architecture

The system processes user input from different channels (Voice, Slack) and funnels them into a unified AI processing layer within the Convex backend. This layer interprets the command, interacts with Salesforce, and sends a formatted response back to the originating channel.

The following diagram illustrates the major components and their interactions.

Voice Call Flow

The voice interaction is the primary hands-free method for using TalkCRM. It begins when a user calls the dedicated Twilio number.

Sources: README.md, agent_configs/TalkCRM.json

1. A sales representative calls the Twilio phone number.
2. Twilio establishes a WebSocket connection to the ElevenLabs Conversational AI agent.
3. The ElevenLabs agent, configured via agent_configs/TalkCRM.json, engages the user in conversation.
4. When the user makes a request (e.g., "Update the Acme deal"), the agent uses a configured webhook tool to send the user's natural language message to a Convex HTTP endpoint.
5. The Convex backend processes the request, interacts with Salesforce, and returns a JSON response.
6. The ElevenLabs agent receives the response, synthesizes it into speech using the configured voice, and speaks the result back to the user.

The sequence diagram below details this interaction.

ElevenLabs Agent Configuration

The voice agent's behavior is defined in agent_configs/TalkCRM.json. This configuration specifies the agent's personality, the tools it can use, and its voice characteristics.

Parameter	Value	Description
name	TalkCRM	The name of the agent.
first_message	"Hey! I'm TalkCRM..."	The initial greeting spoken to the user.
tts.voice_id	mHV5m7DLaQM0bIAP6BTK	The ElevenLabs voice ID used for speech synthesis.
prompt	"You are TalkCRM, a high-energy voice assistant..."	The system prompt defining the AI's personality and instructions.
prompt.tool_ids	["tool_3601kc84mz3rehct87bkqyb4x4b4"]	The ID of the tool that calls the Convex backend.

Sources: agent_configs/TalkCRM.json

Slack Command Flow

TalkCRM can also be controlled via Slack using slash commands (/crm) and app mentions (@TalkCRM).

Sources: convex/slackCommands.ts, convex/slackBlocks.ts

1. A user types a command in Slack, such as /crm search Acme or @TalkCRM what are my open tasks?.
2. Slack sends a payload to a Convex HTTP endpoint, which triggers the handleSlashCommand or handleAppMention internal action.
3. The command text is parsed. Known subcommands like search, pipeline, and tasks are routed to specific handlers (handleSearch, handlePipeline, etc.).
4. Unknown commands or general queries from mentions are routed to the central handleAIQuery action.
5. This action invokes the same core api.ai.askSalesforce function used by the voice flow to interpret the user's query.
6. The result from Salesforce is formatted into Slack Block Kit UI elements using builders from convex/slackBlocks.ts.
7. A formatted message is posted back to the Slack channel or as an ephemeral response.

The following diagram shows the flow for a Slack command.

Core Backend Processing: The AI Assistant

At the heart of both voice and Slack interactions is the askSalesforce Convex action, which uses a large language model (Claude) to interpret user intent and execute the correct Salesforce operation.

Sources: convex/ai.ts, PROJECT_DESCRIPTION.md

Intent Interpretation Flow

Sources: convex/ai.ts:184-353

Key Components

1. Dynamic Schema Context

Before calling the AI, the askSalesforce action fetches the user's available custom Salesforce objects and fields via internal.orgMetadata.getAvailableObjects. This metadata is dynamically injected into the system prompt, allowing the AI to understand and operate on custom schemas specific to the user's Salesforce organization.

Sources: convex/ai.ts:193-279

2. AI System Prompt

A detailed system prompt (SALESFORCE_SCHEMA_CONTEXT) instructs the AI on its role, available tools, object schemas (including standard objects, custom objects, and picklist values), and the expected JSON output format. This prompt is critical for ensuring the AI generates valid and executable Salesforce commands.

Sources: convex/ai.ts:10-181

3. Intent Parsing

The AI is instructed to return a JSON object that conforms to the ParsedIntent structure. This structured output allows the system to reliably execute the correct function with the right parameters.

interface ParsedIntent {
  action: "search" | "query" | "create" | "update" | "log_call" | "clarify";
  objectType?: string;
  recordId?: string;
  searchTerm?: string;
  soql?: string;
  fields?: Record<string, any>;
  clarificationQuestion?: string;
  response: string;
  followUp?: string;
}

Sources: convex/ai.ts:186-196

4. Salesforce Actions

Based on the parsed intent, askSalesforce calls other Convex actions that wrap the Salesforce REST API. These actions handle authentication and the specifics of each API call.

Function (in convex/salesforce.ts)	Description	AI Action Trigger
searchRecords	Finds records using SOSL or runs a raw SOQL query.	search, query
createRecord	Creates a new Salesforce record.	create
updateRecord	Updates fields on an existing record.	update
logCall	Creates a Task record to log a call.	log_call
getMyOpportunities	Retrieves open opportunities for the current user.	query (special case)
getMyTasks	Retrieves open tasks for the current user.	query (special case)

Sources: convex/salesforce.ts, convex/ai.ts:285-353

Conclusion

The TalkCRM Call & Command Data Flow is a robust, multi-channel system that abstracts the complexity of Salesforce interactions behind a natural language interface. By centralizing intent processing in the askSalesforce AI action, the system can easily support new input channels and complex user queries. The dynamic injection of Salesforce schema context makes the assistant highly adaptable to different customer environments, providing a personalized and powerful user experience.