Booking with Cal.com

Connect your calendar#

Open Agent → Actions → Cal.com. Enter a Cal.com API key starting with cal_, the positive numeric event type ID and an IANA time zone such as Asia/Seoul. Choose Save connection. Each agent has its own connection. The key is encrypted on the server; the dashboard shows only its last four characters. Leave the key blank when updating an existing connection to keep it.

Choose Test connection to read up to three upcoming slots over the next seven days using the entered settings. This test does not save the connection or create a booking. No slots can simply mean the event type has no availability in that period. Check the key, event type and schedule in Cal.com if the test fails. Removing the connection stops new Cal.com bookings; it does not cancel existing bookings.

Payments are out of scope. Google Calendar is a separate option that is not generally available yet.

From slots to a booking#

1. The agent calls find_slots for real future availability. It shows up to eight times in the configured time zone. The default range is today through seven days later; the maximum date span is 14 days. A single available time is shown alone.
2. The customer chooses a time and supplies name, email and an optional note. The agent rechecks that the time is free and was offered to this conversation. Slot offers expire after 15 minutes.
3. A confirmation card shows the date, time, time zone and attendee details. The customer must tap Confirm. A chat message or time selection alone does not book anything. The proposal expires after 15 minutes and does not hold the slot.
4. Only after confirmation does the adapter request the Cal.com booking. A Cal.com accepted result becomes done, with the booking UID as reference. pending or awaiting_host remains pending; rejection or cancellation becomes failed.

Booking proposals are private-chat-only on messaging channels. Rehearsal does not call Cal.com or create a booking. Without a Cal.com connection, the existing booking-request flow remains available; it does not prove a calendar reservation. Changing the key, event type or time zone invalidates a proposal's execution target, so start again after connection changes.

If a slot is taken or the result is uncertain#

Another customer can take a slot before confirmation completes. If the time is no longer free, the agent reports that it is unavailable; if Cal.com rejects it during creation, the receipt shows failure. Ask for fresh times and confirm a new proposal. The failure receipt does not automatically attach fresh choices.

A network timeout is not proof of failure or success. The receipt shows an unknown result while the service checks again. Cal.com's create endpoint has no documented idempotency-key contract, so the adapter stores the run ID in metadata.maf_run and looks for that booking across all statuses and pages before retrying creation. An incomplete lookup never permits another create request. This reduces duplicate risk but is not a provider-backed exactly-once guarantee. Before making another booking after exhausted retries, check Cal.com.

Cal.com host approval is separate from owner approval for custom change actions. A pending Cal.com booking is not automatically refreshed by this integration; check its final status in Cal.com. The web widget can poll the stored run receipt, and supported private channels receive delayed receipts subject to their service windows. See receipt delivery.

API versions and release checks#

The adapter sends Bearer authentication and these endpoint-specific cal-api-version values, verified against the official docs on 2026-10-13:

Before using it with customers, test a controlled booking, verify the UID in Cal.com, try a taken slot, and check receipts on every intended channel. A successful connection test proves only a slots read, not a real booking or production readiness.