Call Logging and Analytics

The Call Logging and Analytics system is a core component of TalkCRM, responsible for tracking user interactions, auditing AI tool usage, and generating insightful metrics about system performance and Salesforce data manipulation. This system provides the data backbone for user-facing dashboards, administrative monitoring, and real-time notifications.

All data is stored and processed within the Convex backend. The system is designed to provide both high-level summaries for administrators and granular usage statistics for individual users, enabling a comprehensive understanding of how TalkCRM is being utilized.

Data Model

The logging and analytics capabilities are built upon a set of interconnected tables within the Convex database schema. The primary tables are conversations, toolCalls, and agentActivities.

Sources: PROJECT_DESCRIPTION.md:100-123

Database Schema

The following diagram illustrates the relationships between the key tables used for logging and analytics.

This ER diagram shows that each conversation can have multiple toolCalls and can generate multiple agentActivities.

Sources: PROJECT_DECRIPTION.md:100-123

Key Data Tables

Sources: PROJECT_DESCRIPTION.md:100-123

Call Logging Flow

When a user initiates a call, a series of events are logged to capture the entire lifecycle of the interaction. This ensures a complete audit trail and provides the raw data for the analytics engine.

The following sequence diagram shows the typical flow for logging a call where the user requests to update a Salesforce record.

Analytics Queries

The convex/analytics.ts file contains a suite of queries for aggregating and summarizing the logged data. These queries power the analytics dashboards for both users and administrators.

Sources: convex/analytics.ts

getUserUsage

This query provides a comprehensive summary of an individual user's activity over a specified period (default 30 days).

Logic Flow:

Key Metrics Returned:

• calls: total, completed, avgDurationSeconds, totalDurationMinutes.
• tools: totalCalls, byType (a record of tool names to their counts), successRate.
• salesforce: recordsAccessed, recordsModified.

Sources: convex/analytics.ts:9-85

getDailyUsage

This query is designed for charting, providing a day-by-day breakdown of call volume and duration for a user or for the entire platform.

Functionality:

1. Fetches all conversations within the specified date range (default 7 days).
2. Initializes a data structure with an entry for each day in the range, with calls and duration set to zero.
3. Iterates through the conversations, summing the number of calls and total duration for each day.
4. Returns an array of daily stat objects, sorted by date.

Sources: convex/analytics.ts:91-131

getToolUsage

This query aggregates data from the toolCalls table to provide insights into which AI tools are being used, their performance, and success rates.

Key Metrics Returned per Tool:

• name: The name of the tool (e.g., search_salesforce, update_record).
• count: Total number of times the tool was called.
• successCount: Number of successful executions.
• avgDurationMs: Average execution time in milliseconds.
• successRate: Percentage of successful calls.

Sources: convex/analytics.ts:137-193

getTopRecords

Identifies the Salesforce records that are most frequently interacted with through TalkCRM. It counts the number of times each record ID appears in the salesforceRecordsAccessed and salesforceRecordsModified arrays within the conversations table.

Sources: convex/analytics.ts:199-233

getAdminDashboard

A high-level query for platform administrators, providing key performance indicators (KPIs) for the entire system.

Key Metrics Returned:

• users: total, active, activeInLast30Days.
• calls: today, thisWeek, thisMonth, total.
• engagement: avgCallsPerActiveUser in the last 30 days.

Sources: convex/analytics.ts:239-278

Analytics Presentation in Slack

The system can push analytics and activity summaries to Slack, providing real-time visibility for the team. This is handled by functions in convex/slackBlocks.ts and triggered by commands or events processed in convex/slackCommands.ts.

Call Summary Notifications

After a call is completed, a summary can be generated and posted to a Slack channel using the buildCallSummaryBlocks function.

Data Presented in Summary:

• Caller information (callerPhone)
• Call duration (durationMinutes)
• A summary of the conversation
• Call outcome (e.g., Successful, Needs Follow-up)
• Salesforce records accessed and modified
• Action buttons to view call details or the record in Salesforce

Sources: convex/slackBlocks.ts:289-363

Deal Alert Notifications

The system can also generate event-driven alerts, such as when a deal's stage changes. The buildDealAlertBlocks function formats these messages.

Data Presented in Alert:

• Alert type (e.g., "Deal Won!", "Deal Stage Changed")
• Deal Name, Account Name, Amount, and Owner
• Stage change details (e.g., Prospecting → Qualification)
• A button to view the deal directly in Salesforce

Sources: convex/slackBlocks.ts:369-417

Conclusion

The Call Logging and Analytics system is fundamental to TalkCRM's operation and value proposition. By meticulously logging every user interaction and AI tool execution in Convex, the platform provides powerful, real-time insights into sales activities and system usage. These analytics not only empower users and managers with data-driven dashboards but also enable administrators to monitor platform health and drive engagement. The integration with Slack further enhances visibility by pushing key events and summaries directly into team workflows.