packages/features/calAIPhone/README.md
This package provides a comprehensive, provider-agnostic architecture for AI phone services in Cal.com, offering easy integration with different AI service providers, template management, and self-service UI components.
The architecture implements multiple design patterns to create a maintainable, scalable, and flexible system:
┌─────────────────────────────────────────────┐
│ Frontend (React/Next.js) │
│ - UI Components (Agent/Phone Management) │
├─────────────────────────────────────────────┤
│ TRPC API Layer │
│ - Type-safe RPC endpoints │
│ - Request/Response validation │
├─────────────────────────────────────────────┤
│ Service Layer │
│ - Business logic orchestration │
│ - Provider abstraction │
├─────────────────────────────────────────────┤
│ Repository Layer │
│ - Data access abstraction │
│ - Query optimization │
├─────────────────────────────────────────────┤
│ Prisma ORM / Database │
│ - PostgreSQL with optimized queries │
└─────────────────────────────────────────────┘
interfaces/AIPhoneService.interface.ts)AIPhoneServiceProvider - Main interface that all providers must implementAIPhoneServiceConfiguration - Configuration for setting up AI servicesAIPhoneServiceProviderFactory - Factory interface for creating providersAIPhoneServiceModel, AIPhoneServiceCall, AIPhoneServiceAgent, etc.)AIPhoneServiceRegistry.ts)AIPhoneServiceRegistry - Central registry for managing providerscreateAIPhoneServiceProvider() - Helper function to create providerscreateDefaultAIPhoneServiceProvider() - Convenience function for default providerCHECK_IN_APPOINTMENT and CUSTOM_TEMPLATEpromptTemplates.ts): Pre-defined conversation templates with placeholderstemplate-fields-map.ts): Dynamic field definitions for different template typeszod-utils.ts): Comprehensive validation schemas for all data typesgetTemplateFieldsSchema.ts): Dynamic schema generation based on template typeproviders/)retellAI/ - Complete Retell AI implementation with:
example-future-provider/ - Example showing how to add new providerscomponents/)CreateAgentStep.tsx - Step-by-step agent creation wizardCreateWorkflowAgent.tsx - Workflow-based agent setupAgentsListPage.tsx - Agent management and listingSkeletonLoaderList.tsx - Loading states for better UXpages/)agent.tsx - Agent management pageindex.tsx - Main AI phone service dashboard/packages/lib/server/repository/)
PrismaAgentRepository - Manages agent data accessPrismaPhoneNumberRepository - Handles phone number operationsproviders/retellAI/RetellAIService.ts)
The repository pattern provides an abstraction layer over data access, making the system database-agnostic and testable.
Benefits:
The factory pattern enables dynamic creation of provider instances without exposing instantiation logic.
Benefits:
Service layer orchestrates business operations and coordinates between multiple repositories and external services.
Benefits:
The registry pattern manages provider registration and lookup, acting as a service locator.
Benefits:
Mappers transform data between different representations (database models, DTOs, API responses).
Benefits:
The strategy pattern allows switching between different AI providers seamlessly.
Benefits:
The AI Phone system is designed specifically for Cal.com's workflow automation, enabling AI-powered phone calls as part of scheduling workflows.
┌─────────────────────────────────────────────┐
│ Cal.com Workflow Engine │
├─────────────────────────────────────────────┤
│ Workflow Step: AI Phone Call │
├─────────────────────────────────────────────┤
│ AI Phone Service (via Registry) │
├─────────────────────────────────────────────┤
│ Agent + Phone Number Setup │
└─────────────────────────────────────────────┘
AI Phone calls are configured as workflow steps with specific triggers.
AI Phone calls can be triggered by various workflow events:
1. Workflow Trigger (e.g., 24 hours before event)
↓
2. Workflow Engine schedules AI Phone Call task
↓
3. Task Runner (executeAIPhoneCall) executes
↓
4. AI Phone Service creates call with dynamic data
↓
5. Call connects and AI handles conversation
↓
6. Call results logged back to workflow
To prevent abuse, workflow AI calls are rate-limited.
1. Workflow Trigger Event
↓
2. Workflow Step Configuration Retrieved
↓
3. Booking & Attendee Data Fetched
↓
4. Dynamic Variables Prepared
↓
5. AI Agent & Phone Number Selected
↓
6. Phone Call Initiated
↓
7. Results Logged to Workflow
For complete usage examples, please refer to:
index.tsproviders/packages/features/handleCreatePhoneCall.tsSupported field types include:
text, textarea, number, email, phoneaddress, multiemail, select, multiselectcheckbox, radio, radioInput, booleanTemplates support dynamic variables:
{{scheduler_name}} - Name of the scheduler{{name}} - Guest name{{email}} - Guest email{{company}} - Guest company{{current_time}} - Current timestampFor detailed instructions on adding new providers, see the example provider implementation.
RETELL_AI_KEY - API key for Retell AI (required when using Retell AI provider)STRIPE_PHONE_NUMBER_MONTHLY_PRICE_ID - Stripe price ID for monthly phone number subscriptions (required for billing)NODE_ENV - Controls logging behavior (logging disabled in production)The AI Phone system integrates with Stripe for phone number billing. When users purchase phone numbers through the workflow system, they're redirected to Stripe checkout.
The STRIPE_PHONE_NUMBER_MONTHLY_PRICE_ID should be set to your Stripe price ID that represents the monthly subscription cost for AI phone numbers. This price ID is created in your Stripe dashboard and determines how much customers are charged monthly for each phone number.
The AI Phone system automatically deducts credits from user or team accounts when calls are completed. This is handled by the webhook at apps/web/app/api/webhooks/retellAI/route.ts.
1. AI Phone Call Completes
↓
2. Provider sends "call_analyzed" webhook
↓
3. Webhook verifies signature for security
↓
4. System looks up phone number owner (user/team)
↓
5. Calculates credits based on usage factors
↓
6. Verifies sufficient credits available
↓
7. Deducts credits from account
↓
8. Logs transaction for audit
Credits are deducted based on multiple factors including:
The system calculates the total cost and converts it to credits for deduction from the user or team account.
The webhook requires proper configuration:
The webhook integrates with Cal.com's credit system to check and deduct credits appropriately.
The webhook includes comprehensive error handling:
The webhook processes call completion events that contain the final usage data and cost information. Other events are acknowledged but not processed for billing purposes.