Skip to main content

Cal.com

Audience: Sales, support, engineering · Where in app: Settings → Integrations → Calendars & booking → Cal.com card · Plan availability: All plans, no flag

Added with the tenant-chosen booking calendar (backend 225840d0d, ms-comm 5f1417d, ms-ai 5d620a17c, frontend 97eed5ef, 2026-11-05) and verified on a live account. Cal.com owns availability (its schedules, buffers, limits); we read slots for the picked event type and book into it.

How it works​

  • Connect: POST /calcom/connect { api_key } calls /me and lists event types (401/403 → "Cal.com rejected that API key", else "Could not reach Cal.com"). The key goes to the credential vault (provider: 'calcom', hint = last 4) and is never returned. Exactly one event type → auto-picked.
  • Pick: GET /calcom/event-types, POST /calcom/select-event-type (must exist on the account). GET /calcom/status, DELETE /calcom/disconnect.
  • Data (companies.calcom_integration): account_email, username, time_zone, event_type_id, event_type_title, event_type_length, connected_at. Bookable (ladder) = event_type_id set.
  • Book (CalcomAdapter, Cal.com v2 POST /bookings): email required; attendee name/email/timezone, phone only when it is E.164 (Cal.com rejects others and would fail the booking); metadata.source: 'knock-knock'. HTTP 409, or a 400 whose body reads like a taken slot, → SLOT_TAKEN. Session rows: booking_type: 'calcom', calcom_booking_uid.
  • Reschedule = book the new time then cancel the old (canMoveInPlace = false), because Cal.com mints a new uid on reschedule — same as Calendly. Cancel follows rescheduledToUid so a booking moved inside Cal.com is still cancellable.
  • Sync back: CalendarSyncJob (15 min) applies cancels/moves made in Cal.com.
  • Ladder rung: after Calendly, before Google.

Configuration & environment​

EnvDefaultNotes
CALCOM_API_BASEhttps://api.cal.com/v2Endpoint versions per the Cal.com v2 docs (services/calcom/client.js)

No platform credentials: each tenant brings its own API key. The key is decrypted on the schedular for CalendarSyncJob, so SECRET_ENCRYPTION_KEY must match across pods.

Technical implementation​

  • backend: controllers/CalcomController.js, services/calcom/client.js, services/scheduling/adapters/CalcomAdapter.js, jobs/CalendarSyncJob.js, routes/calendarIntegrationRoutes.js. Spec: outlook-calcom-scheduling-adapters.spec.js.
  • frontend: components/integrations/CalcomCard.vue, CalcomModal.vue (key step → event-type step, vee-validate + zod).
  • ms-comm: widget slots/booking route calcom through backend /scheduling/* (getBackendAvailableSlots). ms-ai: calendar-types.ts lists calcom as a backend-scheduling type.