feat: cal.ai self serve #21827

Udit-takkar · 2025-06-15T20:53:15Z

What does this PR do?

This PR introduces a comprehensive AI phone system that enables users to create AI agents, manage phone numbers, and integrate AI-powered calls into Cal.com workflows

I have used Repository Pattern for database queries (one place instead of scattered), Strategy Pattern so all AI providers work identically (easy to swap), Factory Pattern to create the right provider automatically, Service Pattern to bundle complex operations.

Core AI Phone Capabilities

AI Agent Management: Create, configure, and manage AI agents with custom prompts and voices
Phone Number Provisioning: Purchase and manage phone numbers through Stripe integration
Workflow Integration: AI phone calls as workflow steps with multiple trigger types

Workflow Integration

Multiple Triggers: BEFORE_EVENT, AFTER_EVENT, NEW_EVENT, RESCHEDULE_EVENT, CANCELLED_EVENT
Dynamic Variables: Automatic injection of booking data (guest name, event details, etc.)
Scheduling: Time-based triggers (X hours/minutes before/after events)

Billing & Credits

Credit-Based System: 5 credits minimum for AI phone calls
Stripe Integration: Monthly phone number subscriptions via Stripe checkout
Usage-Based Billing: Automatic credit deduction via webhooks after call completion
Team Support: Both personal and team-based billing

More in https://github.com/calcom/cal.com/pull/21827/files#r2251947957

Mandatory Tasks (DO NOT REMOVE)

I have self-reviewed the code (A decent size PR without self-review might be rejected).
N/A I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. If N/A, write N/A here and check the checkbox.
I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

Environment Variables Required

RETELL_AI_KEY=your_retell_ai_api_key
STRIPE_PHONE_NUMBER_MONTHLY_PRICE_ID=price_xxxxxxxxxxxx

Create a workflow and select cal ai voice agent as action and click on setup
https://github.com/user-attachments/assets/bc66ea5f-4b90-493b-93f3-3d8939d16bf5
Click on edit and go to Phone Number tab to buy/import phone number

Screen.Recording.2025-08-05.at.12.59.01.AM.mov

Now you can activate this on some event types and you see a new phone number input on the booking page (Just like SMS reminder workflow action)

Then you can fill any US based phone number then you see that a task is created in tasker which can be executed if you run tasker

Summary by cubic

Added a self-serve feature for creating and managing AI-powered phone agents for event types, including phone number purchase, agent setup, and test calls.

New Features
- Users can buy dedicated phone numbers and assign them to event types.
- Added UI to configure phone agents and trigger test calls.
- New backend endpoints and database tables to support phone number management and agent configuration.

vercel · 2025-06-16T14:45:40Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
cal	⬜️ Ignored (Inspect)	Visit Preview		Aug 7, 2025 8:57am
cal-eu	⬜️ Ignored (Inspect)	Visit Preview		Aug 7, 2025 8:57am

delve-auditor · 2025-06-24T12:54:11Z

✅ No security or compliance issues detected. Reviewed everything up to b1b9aac.

Security Overview

🔎 Scanned files: 53 changed file(s)

Detected Code Changes

The diff is too large to display a summary of code changes.

Reply to this PR with @delve-auditor followed by a description of what change you want and we'll auto-submit a change to this PR to implement it.

Udit-takkar · 2025-07-03T12:01:31Z

packages/trpc/server/routers/loggedInViewer/_router.tsx

+  makeSelfServePhoneCall: authedProcedure
+    .input(z.object({ eventTypeId: z.number(), numberToCall: z.string() }))
+    .mutation(async ({ ctx, input }) => {
+      const { eventTypeId, numberToCall } = input;
+      console.log("makeSelfServePhoneCall", ctx, input);
+
+      const { handleCreateSelfServePhoneCall } = await import(
+        "@calcom/features/ee/cal-ai-phone/handleCreateSelfServePhoneCall"
+      );
+      const call = await handleCreateSelfServePhoneCall({
+        userId: ctx.user.id,
+        eventTypeId,
+        numberToCall,
+      });
+      return call;
+    }),


Endpoint for making phone call

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts (1)

40-63: Add validation for subscription status.

The status mapping logic is well-implemented, but consider adding validation for subscription.status to handle cases where it might be undefined or null.

  const statusMap: Record<string, PhoneNumberSubscriptionStatus> = {
    active: PhoneNumberSubscriptionStatus.ACTIVE,
    past_due: PhoneNumberSubscriptionStatus.PAST_DUE,
    cancelled: PhoneNumberSubscriptionStatus.CANCELLED,
    incomplete: PhoneNumberSubscriptionStatus.INCOMPLETE,
    incomplete_expired: PhoneNumberSubscriptionStatus.INCOMPLETE_EXPIRED,
    trialing: PhoneNumberSubscriptionStatus.TRIALING,
    unpaid: PhoneNumberSubscriptionStatus.UNPAID,
  };

- const subscriptionStatus = statusMap[subscription.status] || PhoneNumberSubscriptionStatus.UNPAID;
+ const subscriptionStatus = subscription.status 
+   ? statusMap[subscription.status] || PhoneNumberSubscriptionStatus.UNPAID
+   : PhoneNumberSubscriptionStatus.UNPAID;

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 70c18b8 and 953001f.

📒 Files selected for processing (3)

apps/web/app/api/phone-numbers/subscription/success/route.ts (1 hunks)
packages/features/ee/billing/api/webhook/_checkout.session.completed.ts (2 hunks)
packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

apps/web/app/api/phone-numbers/subscription/success/route.ts
packages/features/ee/billing/api/webhook/_checkout.session.completed.ts

🧰 Additional context used

📓 Path-based instructions (2)

**/*.ts

📄 CodeRabbit Inference Engine (.cursor/rules/review.mdc)

**/*.ts: For Prisma queries, only select data you need; never use include, always use select
Ensure the credential.key field is never returned from tRPC endpoints or APIs

Files:

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts

**/*.{ts,tsx}

📄 CodeRabbit Inference Engine (.cursor/rules/review.mdc)

Flag excessive Day.js use in performance-critical code; prefer native Date or Day.js .utc() in hot paths like loops

Files:

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts

🧠 Learnings (4)

📓 Common learnings

Learnt from: Udit-takkar
PR: calcom/cal.com#21827
File: packages/lib/server/repository/phoneNumber.ts:153-160
Timestamp: 2025-08-05T13:17:23.491Z
Learning: In the Cal.com Cal AI phone feature, the deletePhoneNumber repository method validation is properly handled in the service layer (RetellAIService.deletePhoneNumber) which validates user ownership and authorization before calling the repository method. The repository layer correctly focuses on data access only.

📚 Learning: the office365calendar webhook handler in packages/app-store/office365calendar/api/webhook.ts is spec...

Learnt from: vijayraghav-io
PR: calcom/cal.com#21072
File: packages/app-store/office365calendar/api/webhook.ts:120-123
Timestamp: 2025-07-18T17:57:16.395Z
Learning: The office365calendar webhook handler in packages/app-store/office365calendar/api/webhook.ts is specifically designed for Office365 calendar integration, not as a generic webhook handler. Therefore, it's safe to assume that fetchAvailabilityAndSetCache method will be implemented in the Office365CalendarService, making explicit validation checks unnecessary.

Applied to files:

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts

📚 Learning: applies to **/*.ts : for prisma queries, only select data you need; never use `include`, always use ...

Learnt from: CR
PR: calcom/cal.com#0
File: .cursor/rules/review.mdc:0-0
Timestamp: 2025-07-28T11:50:23.946Z
Learning: Applies to **/*.ts : For Prisma queries, only select data you need; never use `include`, always use `select`

Applied to files:

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts

📚 Learning: applies to **/*.ts : ensure the `credential.key` field is never returned from trpc endpoints or apis...

Learnt from: CR
PR: calcom/cal.com#0
File: .cursor/rules/review.mdc:0-0
Timestamp: 2025-07-28T11:50:23.946Z
Learning: Applies to **/*.ts : Ensure the `credential.key` field is never returned from tRPC endpoints or APIs

Applied to files:

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts

🧬 Code Graph Analysis (1)

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts (1)

packages/features/ee/billing/api/webhook/__handler.ts (2)

SWHMap (10-14)

HttpCode (25-29)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Codacy Static Code Analysis

🔇 Additional comments (3)

packages/features/ee/billing/api/webhook/_customer.subscription.updated.ts (3)

1-8: LGTM! Proper imports and type definitions.

The imports are well-organized and the type definition using SWHMap provides good type safety for Stripe webhook data.

9-32: LGTM! Proper error handling and optimized database queries.

The handler correctly validates the subscription ID and uses the select clause to fetch only required fields, addressing previous optimization concerns. The HTTP 202 status for "Phone number not found" is appropriate for webhook handlers.

34-39: LGTM! Proper TypeScript types replace previous any usage.

The function signature now uses proper TypeScript types instead of any, significantly improving type safety and maintainability. This addresses the previous concern about type definitions.

CarinaWolli · 2025-08-06T09:27:24Z

The template uses variables that are not available in the "Add Variable" dropdown {{curren_time}} {{name}} {{email}}

After all questions answered, call function end_call to hang up.

-What if the user removes this line? What does the "end_call" function do?
- Maybe we add the information somewhere what the functions like check_availability book_appointment and end_call do (will talk to @ciaranha about that)
deleteAllWorkflowReminders does not handle the AI_PHONE_CALL workflow method, which results in an error
We are not deleting Agents from the db when deleting workflows

packages/lib/server/repository/agent.ts

packages/features/ee/workflows/components/AgentConfigurationSheet.tsx

CarinaWolli · 2025-08-06T09:02:55Z

packages/features/ee/workflows/components/AgentConfigurationSheet.tsx

+                name="phoneNumber"
+                control={phoneNumberForm.control}
+                render={({ field: { value } }) => (
+                  <TextField


Can we at least fix the placeholder? Placeholder doesn't include country code

Also what is this phone number? (208) 878-2105, doesn't look like a test phone number

Udit-takkar · 2025-08-06T11:08:32Z

Can we at least fix the placeholder? Placeholder doesn't include country code

Ok I'll update the placeholder.

Edit: It's already updated. I think you are on previous commit

Udit-takkar · 2025-08-07T00:43:26Z

-What if the user removes this line? What does the "end_call" function do?

end_call is function needed by voice agent to end the call. If the user removes this line then call can be still end if no activity for 10 minutes, user hangs up, any other request fails etc.

CarinaWolli · 2025-08-07T14:14:16Z

end_call is function needed by voice agent to end the call. If the user removes this line then call can be still end if no activity for 10 minutes, user hangs up, any other request fails etc.

Can't we add this always to the template by default, hidden from the user? I feel like we alway want to end the call at the end of the template, no?

Udit-takkar · 2025-08-07T14:41:02Z

Can't we add this always to the template by default, hidden from the user? I feel like we alway want to end the call at the end of the template, no?

yes end_call should be there for every prompt but it should be customizable when user wants the agent to end the call. For:-
some people can add "Ask customer if they have any other question if no then end_call" or "Say xyz and then end_call"

CarinaWolli · 2025-08-08T11:52:50Z

yes end_call should be there for every prompt but it should be customizable when user wants the agent to end the call. For:-
some people can add "Ask customer if they have any other question if no then end_call" or "Say xyz and then end_call"

But can we make sure in case the user doesn't add end_call, it will still end the call by default when the end of prompt is reached? Or is this already done?

CarinaWolli · 2025-08-08T12:40:25Z

packages/features/ee/workflows/components/AgentConfigurationSheet.tsx

+                      />
+                    )}
+                  </div>
+                  <TextArea


Can we format this as it is in the design?

Yours:

Figma:

CarinaWolli · 2025-08-08T12:42:09Z

Maybe we add the information somewhere what the functions like check_availability book_appointment and end_call do (will talk to @ciaranha about that)

@ciaranha will update designs for that. We should highlight the functions and provide some details below

ciaranha · 2025-08-08T13:20:15Z

Maybe we add the information somewhere what the functions like check_availability book_appointment and end_call do (will talk to @ciaranha about that)

@ciaranha will update designs for that. We should highlight the functions and provide some details below

@CarinaWolli do you mean this?

Udit-takkar · 2025-09-01T15:45:02Z

PRs are merged now

feat: cal.ai self serve

5cac626

github-actions bot added the ❗️ migrations contains migration files label Jun 15, 2025

keithwillcode added core area: core, team members only enterprise area: enterprise, audit log, organisation, SAML, SSO labels Jun 15, 2025

vercel bot had a problem deploying to Preview – dev June 15, 2025 21:18 Failure

chore: progress

e38f713

vercel bot had a problem deploying to Preview – dev June 16, 2025 15:47 Failure

Merge branch 'main' into feat/cal-ai-self-serve

f52c497

vercel bot had a problem deploying to Preview – dev June 24, 2025 13:13 Failure

fix: form

b6be1fd

vercel bot deployed to Preview – dev June 24, 2025 19:52 View deployment

fix: links[endpoint] error

e7a61c4

vercel bot deployed to Preview – dev June 25, 2025 11:16 View deployment

CarinaWolli added the High priority Created by Linear-GitHub Sync label Jun 25, 2025

chore: form

d2ad1cf

vercel bot deployed to Preview – dev June 26, 2025 07:37 View deployment

Merge branch 'main' into feat/cal-ai-self-serve

ca041da

vercel bot deployed to Preview – dev June 26, 2025 13:31 View deployment

Merge branch 'main' into feat/cal-ai-self-serve

049c1bb

vercel bot deployed to Preview – dev July 2, 2025 09:11 View deployment

feat: finish setup

3b9cf80

vercel bot deployed to Preview – dev July 3, 2025 11:51 View deployment

chore: fix

def1186

Udit-takkar commented Jul 3, 2025

View reviewed changes

vercel bot deployed to Preview – dev July 3, 2025 12:19 View deployment

fix: trpc hang bug

8a5967b

vercel bot deployed to Preview – dev July 4, 2025 11:13 View deployment

Merge branch 'main' into feat/cal-ai-self-serve

b1c0524

fix: formatting

265e536

vercel bot deployed to Preview – dev August 5, 2025 17:15 View deployment

fix: type

70c18b8

vercel bot deployed to Preview – dev August 5, 2025 23:35 View deployment

refactor: stripe related webhooks

953001f

coderabbitai bot reviewed Aug 6, 2025

View reviewed changes

Merge branch 'main' into feat/cal-ai-self-serve

49bd22a

vercel bot deployed to Preview – dev August 6, 2025 00:57 View deployment

Udit-takkar mentioned this pull request Aug 6, 2025

feat: cal ai self serve architecture #1 #22919

Merged

3 tasks

CarinaWolli reviewed Aug 6, 2025

View reviewed changes

Udit-takkar marked this pull request as draft August 6, 2025 10:58

chore: imporovements

2cdbfa7

fix: types

2f52003

vercel bot deployed to Preview – dev August 7, 2025 01:14 View deployment

chore

15ddc3d

vercel bot deployed to Preview – dev August 7, 2025 09:37 View deployment

CarinaWolli reviewed Aug 8, 2025

View reviewed changes

Udit-takkar mentioned this pull request Aug 9, 2025

feat: Cal.ai Self Serve #2 #22995

Merged

11 tasks

CarinaWolli modified the milestones: v5.6, v5.7 Aug 18, 2025

Udit-takkar closed this Sep 1, 2025

feat: cal.ai self serve #21827

feat: cal.ai self serve #21827

Uh oh!

Conversation

Udit-takkar commented Jun 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Mandatory Tasks (DO NOT REMOVE)

How should this be tested?

Summary by cubic

Uh oh!

vercel bot commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

delve-auditor bot commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Udit-takkar Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

CarinaWolli commented Aug 6, 2025 • edited by Udit-takkar Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CarinaWolli Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Udit-takkar commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Udit-takkar commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CarinaWolli commented Aug 7, 2025

Uh oh!

Udit-takkar commented Aug 7, 2025

Uh oh!

CarinaWolli commented Aug 8, 2025

Uh oh!

CarinaWolli Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

Udit-takkar Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

CarinaWolli commented Aug 8, 2025

Uh oh!

ciaranha commented Aug 8, 2025

Uh oh!

Udit-takkar commented Sep 1, 2025

Uh oh!

Uh oh!

Udit-takkar commented Jun 15, 2025 •

edited

Loading

vercel bot commented Jun 16, 2025 •

edited

Loading

delve-auditor bot commented Jun 24, 2025 •

edited

Loading

CarinaWolli commented Aug 6, 2025 •

edited by Udit-takkar

Loading

Udit-takkar commented Aug 6, 2025 •

edited

Loading

Udit-takkar commented Aug 7, 2025 •

edited

Loading