Connecting Cal.com

Last updated: April 2026 · Receptionist, Inc.

Why Cal.com is the calendar layer

Aria books appointments through Cal.com rather than connecting to your calendar directly. This sounds like an extra step, but it is deliberate: Cal.com handles a bunch of scheduling concerns (event types, time zones, buffer times, scheduling rules, calendar conflict detection) that we do not want to reimplement ourselves. By routing through Cal.com, Aria inherits all of that capability for free.

Cal.com is open-source, has a generous free tier, and works with every major primary calendar (Google Calendar, Outlook, Office 365, Apple, Fastmail). You keep full control of your scheduling — you can log into Cal.com directly at any time, adjust your availability, change event types, or use Cal.com for non-Aria bookings (public booking pages, team scheduling, internal meetings) without affecting how Aria works.

Setup walkthrough

1. **Create a Cal.com account** at cal.com if you do not already have one. The free tier is sufficient for a single-user business.

2. **Connect your primary calendar inside Cal.com.** Go to Cal.com → Settings → Calendars and connect whichever calendar you use day to day (Google Calendar, Outlook, Apple, etc.). This is the calendar Cal.com will read for availability and write bookings to.

3. **Create event types for each service you offer.** An event type in Cal.com represents one kind of thing Aria can book. For a hair salon, you might have event types for "Cut", "Color", "Cut & Color", and "Consultation". For a plumber, you might have "Service Call", "Free Estimate", and "Emergency Repair". Set the duration, buffer time, and any availability restrictions for each.

4. **Generate a Cal.com API key** in Cal.com → Settings → Developer → API Keys.

5. **Paste the API key into your Receptionist.co dashboard settings** in the Cal.com integration section.

6. **Choose which event types Aria is allowed to book.** You do not have to expose every event type through Aria. For example, you might expose "Service Call" and "Free Estimate" but keep "Internal team meeting" Cal.com-only.

Verifying the connection

After you paste the API key and save:

•Your dashboard should show a "Cal.com connected" indicator

•Create a test appointment directly from your dashboard

•Verify the test appointment appears in Cal.com and in your connected primary calendar

•Call your Aria number and ask to book an appointment — Aria should check real availability and offer current slots

If Aria tells a caller "I am not able to check availability right now," the Cal.com API key is wrong, expired, or unauthorized. Rotate it in Cal.com and paste the new key into your Receptionist.co settings.

Common setup mistakes

•**Skipping the primary calendar connection inside Cal.com.** If you connect Cal.com to Receptionist.co but forget to connect your Google Calendar or Outlook inside Cal.com itself, Cal.com has nothing to check availability against and every slot appears available. The result: Aria books appointments that conflict with your existing calendar events. Always connect the primary calendar inside Cal.com first.

•**Creating event types with no available time slots.** If you set an event type's availability to a narrow window or forget to set it at all, Cal.com reports no availability to Aria and bookings fail. Check your event type availability settings.

•**Time zone mismatches.** If your Cal.com time zone, your primary calendar time zone, and your Receptionist.co business hours are all set to different zones, bookings appear at the wrong time. Keep all three in sync.

Disconnecting or rotating

To rotate your Cal.com API key (for example, if you suspect it has been exposed):

1. Generate a new key in Cal.com

2. Paste the new key into your Receptionist.co dashboard

3. Delete the old key in Cal.com

The rotation takes effect on the next booking attempt. No bookings are lost, and your existing appointments are unaffected.

Was this article helpful?

👍 Yes 👎 No