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 — a follow-up question ("ok what other times do you have?", with or without the question mark) is answered instead, and the agent proposes again. Cal.com then creates a confirmed booking directly — unless the event type requires the host's confirmation, in which case it books as pending and the agent says the request is in and still has to be confirmed, instead of "all set". Beyond that, Cal.com-specific behavior:

• Custom questions are asked in the chat. If the event type has booking questions, the agent asks the visitor every required one before proposing the booking — a multiple-choice question is presented with its choices verbatim, and each answer is validated against that question's field type. The booking is not armed for confirmation until all required questions are answered, and the answers land on the Cal.com booking like a normal form submission.
• Phone numbers: a volunteered +-international number becomes the attendee's phone. Never required, never blocks a booking.
• Fallback: because the direct API works on Cal.com's standard plans, there is no free-plan fallback tier the way Calendly has — but if a booking can't complete (a network error, or Cal.com rejects it), the agent falls back to the event type's public booking page and asks the visitor to finish there. Cal.com reuses that public page link rather than minting a single-use link the way Calendly does.

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

Letting customers cancel or reschedule

Advanced mode carries an opt-in switch, Let customers cancel or reschedule, that lets the agent change bookings it made. With it on, the agent lists the customer's upcoming bookings and then cancels or moves one only after the customer confirms — on Cal.com both the cancel and the reschedule happen by API, right in the chat.

The guardrails keep it to the customer's own bookings:

• Only bookings the agent itself made can be touched — never one booked elsewhere.
• Only from the same conversation, or the same channel identity — the phone number on a call or SMS, the WhatsApp or Instagram account, or the widget browser. A typed-in email never unlocks a booking.
• A cancelled booking stops counting as a booked appointment.
• Anything the agent can't finish is handed to your team.

It applies to Advanced bookings only. Simple- and Connected-mode calendar embeds are booked on Cal.com's own page, so there is nothing here to change.

Live sync

Once an enabled Advanced action is saved, or a Connected Cal.com account is linked, Evoriqa subscribes a Cal.com webhook so a booking the agent made stays truthful when it changes outside the chat — the customer cancelling from Cal.com's confirmation e-mail, or the host cancelling, declining or accepting a booking on an event type that requires confirmation. The stored booking is updated to match Cal.com — confirmed, moved to its new time, or marked cancelled — and a cancelled one stops counting as an appointment. This covers both the tappable slot chips and the in-chat calendar.

Unlike Calendly, Cal.com webhooks work on every plan with any API key — no scope to add and no plan requirement. The connection card and the booking action card show Live sync on, or the reason it is not.

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