Booking with Cal.com

This page is the Cal.com-specific companion to Configuring an action: which mode to pick, what Cal.com asks for in each, and what the errors mean. Using Calendly instead? See Booking with Calendly.

Pick a mode

Every mode works on Cal.com's standard plans — there is no free-plan restriction like Calendly's.

Your API key

Connected and Advanced mode both use a Cal.com API key: Cal.com → Settings → Developer → API keys → create one. It is a single short string starting cal_ (e.g. cal_live_…).

Simple mode

Paste your public booking-page URL, e.g. https://cal.com/you/30min, into Your booking page link — the field confirms ✓ Cal.com link. No key, no verification call. The general embedded-calendar behavior (what visitors see, messaging/voice fallbacks, the "Book a meeting" widget chip) is covered in Configuring an action.

Connected mode

Paste your API key into the Cal.com panel and click Connect (Cal.com connects by key, not OAuth). Once connected, pick an event type from the Event type dropdown and save. Visitors book in the in-chat calendar, and the agent can read live open slots and offer them as tappable chips — tapping one opens the calendar on that day for the visitor to confirm.

Advanced mode

Pick Provider → Cal.com (direct booking) and fill:

• API token — the same kind of key as above, pasted into API token / secret (stored in the encrypted vault, never shown to the model).
• Cal.com event type ID — easiest: paste the token, save, then click Load event types and pick from the dropdown. By hand: open the event type in Cal.com and read the number from its URL, app.cal.com/event-types/<ID> — a positive whole number.
• Default time zone (optional) — an IANA name such as America/New_York; the fallback for channels that cannot report a browser timezone.

Saving an enabled action verifies the key and event type against Cal.com live; a definitive rejection blocks the save with a message naming which one failed.

What happens during a booking

Advanced-mode booking runs through the confirm gate: the agent collects the visitor's name, email, and time (offering real open slots as tappable chips — on the widget a tapped chip books that exact slot), reads the details back, and books only after the visitor confirms. Cal.com then creates a confirmed booking directly — there is no scheduling-link fallback tier the way Calendly has, because the direct API is available on standard plans. A volunteered +-international phone number becomes the attendee's phone.

The visitor is never told the provider's name — the agent says "our scheduling system" (see Configuring an action).

Troubleshooting

"That doesn't look like a Cal.com API key"

The connect field rejected the value before calling Cal.com. Check you pasted the cal_… key — the usual culprit is a Calendly eyJ… token (see the warning above) or a URL instead of the key.

"API token was rejected by Cal.com"

Cal.com returned 401/403: the key is revoked, mistyped, or belongs to a different account. Create a fresh key under Settings → Developer → API keys and reconnect.

"Event type N not found on this Cal.com account"

The ID doesn't exist on the account the key belongs to — typically a number copied from a different account's URL, or the event type was deleted. Click Load event types and pick from the dropdown instead of typing the ID.

The visitor's slot was taken

Cal.com rejects a booking for a slot that just filled; the agent tells the visitor honestly and offers other times. Nothing to fix — that's the honest-confirmations behavior working.

Where to go next

• Booking with Calendly
• Configuring an action
• Credentials