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/meand 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_idset. - Book (
CalcomAdapter, Cal.com v2POST /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 followsrescheduledToUidso 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
| Env | Default | Notes |
|---|---|---|
CALCOM_API_BASE | https://api.cal.com/v2 | Endpoint 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
calcomthrough backend/scheduling/*(getBackendAvailableSlots). ms-ai:calendar-types.tslistscalcomas a backend-scheduling type.