Documentation Bookings and calendars Cal.com

Bookings integration

Cal.com

Cal.com integration overview
  • CategoryBookings
  • AuthAPI key

Overview

Cal.com connects from Integrations in the MessageMind dashboard using an API key from your hosted Cal.com account. The Connect Cal.com modal has one API Key field. MessageMind previews the account's non-hidden event types, then you select the types the AI may offer and save the connection. The AI can check availability, submit bookings, reschedule and cancel on the saved selection. The current connector uses api.cal.com; self-hosted API base URLs are not supported.

What MessageMind can do with it

  • Offer the saved selection of non-hidden Cal.com event types inside the conversation.
  • Check live availability for a specific event type across a date window, honouring the host's working hours, buffers and date overrides.
  • Submit a Cal.com booking after the customer confirms a slot and provides the required fields; the result distinguishes confirmed bookings from bookings awaiting host confirmation.
  • Reschedule an existing booking to a new time on the same event type without leaving the thread.
  • Find and cancel an existing booking using the attendee email, event type, date and time, with the customer's reason included in the request.
  • Reopen the event-type selector after connecting and save a different selection without re-entering the API key.

Requirements

  • A hosted Cal.com account.
  • An API Key issued from Settings, Developer, API Keys on the host account the AI will book on. 'Never expires' is recommended so the connection stays active.
  • A MessageMind plan on Starter, Professional or Enterprise. The Cal.com card is plan-gated to those tiers.
  • At least one non-hidden event type on the Cal.com account, selected for the MessageMind connection.

How to connect

  1. In Cal.com, open Settings, Developer, API Keys and create a new key. Set the lifetime to 'Never expires' unless your policy requires rotation; Cal.com shows the full value only once, so copy it straight away.
  2. In the MessageMind dashboard, open /integrations and click the Cal.com card. The 'Connect Cal.com' modal opens with the description 'Paste your Cal.com API key to connect. Once connected, MessageMind will fetch your event types and booking fields, and can check availability and book meetings on your behalf through AI.'
  3. Paste the key into the API Key field. The current connector uses the hosted Cal.com API and has no custom API base URL field.
  4. Click Integrate to preview the non-hidden event types using /integration/calcom/preview. Preview validates the key and opens the selector; it does not save the connection yet.
  5. If the key has no event types the selector stays empty and the toast reads 'No event types found on your Cal.com account.' If the preview call fails, the toast reads 'Failed to fetch Cal.com event types.'
  6. Select at least one non-hidden event type and submit the selection. The first connection is saved through /integration/setup, with the toast 'Connecting to Cal.com...' followed by 'Cal.com Connected!' on success. Later settings changes use /integration/calcom/update-meetings.

Authentication and permissions

Mechanism
Cal.com API-key authentication against the hosted API. There is no OAuth connection or automatic key refresh.
Credentials
A Cal.com API key and the selected event types. The current client uses api.cal.com; there is no custom API base URL setting.

Available data and actions

Reads

  • The connected Cal.com user's profile (id, username, email, time zone), so the AI knows which account the key belongs to.
  • The event types the user owns, with their slug, length, locations and required booking fields, surfaced to the selector by /integration/calcom/preview on connect and /integration/calcom/settings-preview on reopen.
  • Live available slots for a selected event type across the requested date window, in the host's time zone.
  • Existing bookings matched by attendee email, event type, date and time for rescheduling or cancellation.

Writes

  • The initial API key and selected event types saved through /integration/setup; later selection changes saved through /integration/calcom/update-meetings.
  • New bookings on a selected event type, with invitee name, email, locale and any custom booking-field answers the event type requires.
  • Reschedules of an existing booking to a new start time on the same event type.
  • Cancellations of an existing booking, with the customer's reason attached.

AI agent use cases

  • Quote available times for a selected event type in a WhatsApp or Instagram thread and submit the booking after the customer confirms.
  • Give the AI a curated subset of Cal.com event types so it never offers an internal-only link.
  • Collect the invitee fields the event type requires in-thread (name, email, custom questions) and create the booking in one go.
  • Reschedule or cancel from the same conversation using the attendee email, event type, date and time to find the booking.

Configuration

  • The event-type selector keeps only the ids you explicitly tick. Unchecking a type on the next save stops the AI from offering it.
  • The settings panel reopens from the Cal.com card after connect. MessageMind caches the last /integration/calcom/settings-preview response per user so the selector opens instantly on a return visit.
  • API endpoint: the hosted api.cal.com service. Self-hosted API base URLs are not supported by the current connector.
  • Availability searches use the requested date or date range. A time-only search scans the next 14 days; a requested date range scans up to 31 days. Nearest-slot searches scan calendar-month windows.
  • Only the saved selection of non-hidden Cal.com event types is available to the AI.
  • Required fields: whatever a Cal.com event type marks as required is asked for in-thread before the AI writes the booking.

Example workflows

First-time connect and event-type selection

  1. On /integrations, click the Cal.com card. The 'Connect Cal.com' modal opens.
  2. Paste the API Key from your hosted Cal.com account and click Integrate.
  3. MessageMind calls /integration/calcom/preview with the key, proves the credential and returns the list of event types the connected user owns.
  4. Select at least one non-hidden event type and save. The first connection is persisted through /integration/setup with the API key and selected event-type IDs.
  5. The AI can now check availability on, and book, any of the selected event types. Non-selected types are not visible to the AI.

Reopen the event-type selector after connect

  1. Open Cal.com settings. The dashboard uses a cached preview when available; otherwise /integration/calcom/settings-preview loads the current event-type list and saved selection. A page reload clears that in-memory cache.
  2. If the saved key is no longer valid, the toast reads 'Your saved Cal.com credentials are no longer valid. Please reconnect.' and the selector stays closed.
  3. If the preview call fails for another reason, the toast reads 'Failed to load Cal.com settings.' Retry the modal.
  4. Edit the selection and save. /integration/calcom/update-meetings validates the current catalog and saves the new selection without re-entering the key.

AI books a Cal.com meeting from chat

  1. The customer asks for a meeting on a selected event type.
  2. MessageMind pulls live slots for that event type across the requested window in the host's time zone.
  3. The AI quotes the first viable slot in the chat.
  4. The customer confirms. The AI collects the invitee fields the event type requires (name, email and any custom questions).
  5. The AI submits the booking and reports the result, including whether host confirmation is still required.

Limitations

  • No OAuth means token rotation is manual. Regenerating the key in Cal.com requires updating the connection in MessageMind.
  • A Cal.com API Key is scoped to the user that created it. Event types owned by other team members are not visible unless that user owns them in a shared workspace.
  • Self-hosted Cal.com deployments cannot be connected through a custom base URL in the current integration.
  • Availability can change between the check and the booking request. If Cal.com rejects the booking, check availability again before choosing another slot.
  • Connecting requires at least one non-hidden event type. If preview returns none, it shows 'No event types found on your Cal.com account.' and does not open the selector.

Troubleshooting

Submitting the connect form shows 'Please provide a Cal.com API Key.'

The API Key field was empty. Paste the key from Cal.com, Settings, Developer, API Keys (Cal.com shows the full value only once) and click Integrate again.

The connect toast reads 'Cal.com connection failed, try again!'

The hosted Cal.com API rejected the key or could not be reached. Generate a valid key in your hosted Cal.com account under Settings, Developer, API Keys and paste the complete value. Self-hosted deployments are not supported.

The preview opens empty with 'No event types found on your Cal.com account.'

The preview found no non-hidden event types for this account. Create or unhide an event type in hosted Cal.com, then preview the account again.

The preview call fails with 'Failed to fetch Cal.com event types.'

The Cal.com event-type API refused the request. Retry the modal; if the problem persists, confirm the key is still active on this host and that the host account can see the event types in the Cal.com UI.

A toast reads 'Your saved Cal.com credentials are no longer valid. Please reconnect.'

Cal.com rejected the saved key. Reconnect with a valid API key and select the event types the AI should offer.

A toast reads 'Failed to load Cal.com settings.'

The /integration/calcom/settings-preview call failed. Retry the modal; if the problem persists, confirm the host is reachable and that the stored key still works in Cal.com.

The AI does not find availability in the requested period.

Check the event type's availability in Cal.com and ask for a specific date or a narrower date range. Search windows vary by the kind of availability request.

Booking fails with 'no_available_users_found_error'.

No eligible host was available for that booking request. Check availability again and choose another available slot.

Disconnect and reconnect

  • In Integrations, use the Cal.com disconnect control to remove the MessageMind connection. The API key remains valid in Cal.com until you revoke it there.
  • Bookings already written in Cal.com stay on the host's calendar; disconnecting does not cancel them.
  • On Cal.com, revoke the key from Settings, Developer, API Keys if you also want to kill it on Cal.com's side.
  • To reconnect, generate a fresh key in Cal.com and paste it into the connect form. The event-type selector reopens so you can pick which types the AI may offer.