Deal Coach
Relevant source files
The following files were used as context for generating this wiki page:The Deal Coach is a feature within TalkCRM designed to help sales representatives practice and improve their sales conversations. It provides an interactive role-playing experience where a user can engage with an AI-powered avatar representing a specific buyer persona. The coaching sessions are contextualized with real data from a Salesforce opportunity, allowing for realistic and targeted practice.
The system integrates with Anam.ai for the conversational avatar interface and uses Anthropic's Claude model as the AI brain to drive the conversation. All session data, interactions, and feedback are stored in the Convex database, providing analytics on user performance and improvement over time.
Sources: convex/dealCoach.ts, convex/anam.ts
Architecture and Data Flow
The Deal Coach feature orchestrates several services: the TalkCRM frontend, the Convex backend, the Anam.ai avatar platform, and the Anthropic (Claude) LLM. The flow begins when a user initiates a session from the frontend for a specific Salesforce opportunity.
Sources: convex/anam.ts:13-89, convex/http.ts
Session Initiation Flow
The following diagram illustrates the sequence of events when a new coaching session is created.
Live Conversation Flow
Once the session is active, Anam.ai handles the voice and avatar, while the Convex backend serves as the custom LLM endpoint to generate responses.
Coaching Session Management
The convex/dealCoach.ts file contains the core logic for managing the lifecycle of a coaching session, from creation to completion and analysis.
Sources: convex/dealCoach.ts
Data Model
Coaching sessions are stored in the coachingSessions table. The schema is defined by the fields used in the various mutations and queries.
This diagram shows the structure of the coachingSessions table.
Key Functions
The system uses a set of mutations and queries to manage sessions. Functions are designated as internal (callable only by other Convex functions) or public (query, mutation).
| Function | Type | File | Description |
|---|---|---|---|
createCoachingSession | internalMutation | dealCoach.ts | Creates a new record in the coachingSessions table. Called by anam.createSession. |
getSession / getCoachingSession | query / internalQuery | dealCoach.ts | Retrieves a session by its ID. getSession is for frontend use. |
logCoachingInteraction | internalMutation | dealCoach.ts | Appends a user/assistant message pair to the interactions array for a session. |
endSession | mutation | dealCoach.ts | Marks a session as "completed" and sets the endedAt timestamp. |
saveSessionFeedback | internalMutation | dealCoach.ts | Saves the score, feedback, strengths, and areas for improvement for a session. |
getUserSessions | query | dealCoach.ts | Retrieves all coaching sessions for a given user. |
getOpportunitySessions | query | dealCoach.ts | Retrieves all coaching sessions for a specific opportunity. |
getUserCoachingStats | query | dealCoach.ts | Calculates aggregate statistics for a user's coaching history. |
Sources: convex/dealCoach.ts:11-224
AI Persona Integration
The realism of the Deal Coach comes from its dynamic persona generation, which combines a predefined persona type with live Salesforce data. This is managed primarily in convex/anam.ts.
Sources: convex/anam.ts
Persona Creation
When a session is initiated via anam.createSession, the system performs these steps:
- Fetches the specified
Opportunityand its relatedAccountfrom Salesforce. - Calls
getCoachingPersonawith thepersonaTypeand the fetched Salesforce data. - This function selects a persona template and injects the deal-specific context (deal amount, company name, industry, etc.) into the system prompt.
- The resulting configuration, including the dynamic system prompt, is sent to Anam.ai to create the session.
Sources: convex/anam.ts:25-50, convex/anam.ts:192-300
Available Personas
The system defines several buyer personas that a user can practice with. Each persona has a unique personality, set of concerns, and system prompt.
| ID | Name | Title | Description | Difficulty | Focus Areas |
|---|---|---|---|---|---|
skeptical_cfo | Skeptical CFO | Margaret Chen - CFO | Challenges on ROI, budget, and business justification | hard | pricing, ROI, risk |
technical_evaluator | Technical Evaluator | David Park - VP Engineering | Deep dives on integration, security, and scalability | medium | integration, security, technical |
friendly_champion | Internal Champion | Sarah Martinez - Director of Ops | Wants to help you win but needs ammunition for internal selling | easy | internal selling, stakeholder management |
procurement_gatekeeper | Procurement Gatekeeper | Robert Thompson - Procurement Director | Focused on terms, compliance, and competitive positioning | medium | negotiation, terms, compliance |
Sources: convex/anam.ts:306-340
Custom LLM Logic
The Deal Coach uses a custom logic layer for its LLM instead of relying on Anam.ai's built-in LLM. This is configured by setting llmId: "CUSTOMER_CLIENT_V1" in the Anam session request.
Anam.ai then calls the anam.handleChatMessage action for each turn in the conversation. This action:
- Retrieves the full session context from the database.
- Constructs a detailed system prompt using
buildCoachingSystemPrompt, which combines the persona's base prompt with current deal information. - Calls the Anthropic Claude API (
claude-opus-4-5-20251101) with the system prompt and conversation history. - Logs the interaction to the database.
- Returns the generated text response to Anam.ai to be spoken by the avatar.
Sources: convex/anam.ts:56-58, convex/anam.ts:95-139, [convex/anam.ts:302-304]
Deal-Specific Coaching Aids
To make the coaching more relevant, the system provides contextual recommendations and tips based on the characteristics of the selected deal.
Sources: convex/dealCoach.ts:229-305
Recommended Personas
The getRecommendedPersonas query suggests which personas a user should practice with based on the deal's stage and amount. This helps focus the user's practice on the most relevant challenges for their current deal cycle.
| Deal Stage | Recommended Personas | Reason |
|---|---|---|
| Prospecting, Qualification, Needs Analysis | friendly_champion, technical_evaluator | Build internal support and handle early technical blockers. |
| Value Proposition, Id. Decision Makers, Proposal | skeptical_cfo, technical_evaluator | Prepare for ROI discussions and address technical concerns. |
| Negotiation/Review, Closed | procurement_gatekeeper, skeptical_cfo | Prepare for negotiations and final executive sign-off. |
| Any stage (Amount > $100,000) | skeptical_cfo | High-value deals almost always require CFO approval. |
Sources: convex/dealCoach.ts:234-273
Dynamic Coaching Tips
The getDealCoachingTips query provides a list of actionable tips based on the deal's stage, amount, and time to close.
- For "Negotiation/Review" stage: "Practice handling discount requests without giving away value. Focus on trading, not conceding."
- For deals > $50,000: "For deals this size, expect multi-threaded evaluation. Practice your CFO pitch."
- For deals closing in < 14 days: "With close date approaching, practice handling last-minute objections and procurement delays."
Sources: convex/dealCoach.ts:280-305
User Analytics
The system provides analytics to help users track their progress and practice habits. The getUserCoachingStats query aggregates data from a user's completed sessions to compute several key metrics.
The following metrics are calculated:
- Total Sessions: The total number of coaching sessions started.
- Completed Sessions: The number of sessions marked as "completed".
- Total Practice Time: The sum of durations for all completed sessions.
- Average Score: The average of scores from all completed and scored sessions.
- Sessions by Persona: A breakdown of how many times each persona type has been practiced.
- Recent Sessions: A list of the 5 most recent sessions for quick access.
Sources: convex/dealCoach.ts:175-224