Cal.com | Smallest AI Docs

Connect Cal.com so your agent can offer real open slots, book the caller in, and move or cancel bookings they already have.

At a glance


Authentication	Cal.com API key
Asked at connect	Your API key
Books into	One default event type, picked when you connect
Works with	Single-prompt agents

Connect Cal.com

Create an API key in Cal.com

Cal.com keys expire after 30 days by default. Turn on Never expires when you create the key, or your agent stops booking when it expires.

Paste it on the Integrations page

Open the Integrations page in the dashboard, click Connect next to Cal.com, paste the key into API key, and click Connect.

The key is checked against your account straight away and stored encrypted. It’s never shown again.

Add the tools to your agent

Click Go to Tools, then Add tool → Integration tool, choose Cal.com, tick the tools this agent needs, and click Add tools. From inside an agent, use Add tool → New tool → Integration tool instead.

Which event type the agent books

When you connect, the event type whose length is closest to 30 minutes becomes the default. Bookings made by the agent use that event type, with its duration, location and booking questions.

The default is chosen once, at connect. If you add or change event types in Cal.com later, disconnect and connect again so the agent picks the new closest-to-30-minutes one.

Tools

Tool	Function name	What it does
Check availability	`cal-com_check_availability`	Returns open slots in a time window
Book meeting	`cal-com_book_meeting`	Books the caller into the default event type
Reschedule meeting	`cal-com_reschedule_meeting`	Moves a booking to a new time
Cancel meeting	`cal-com_cancel_meeting`	Cancels a booking
Find bookings by attendee	`cal-com_find_bookings_by_attendee`	Finds a caller’s bookings by email or name
Get all bookings	`cal-com_get_all_bookings`	Lists bookings with filters
Get booking	`cal-com_get_booking`	Reads one booking

Fields

Check availability

Field	Required	Description	Pinnable
`start_time`	Yes	Start of the window. Local date and time in `timezone`, no UTC offset (for example `2026-09-01T09:00:00`)	Yes
`end_time`	Yes	End of the window, in the same form
`timezone`	Yes	IANA timezone, for example `America/New_York`	Yes
`event_type_id`	No	Check a different event type	Yes

A window that starts in the past is moved to start now.

Book meeting always books the default event type. Leave event_type_id empty so the agent doesn’t offer slots from one event type and book another.

Book meeting

Field	Required	Description	Pinnable
`start_time`	Yes	A slot returned by Check availability
`timezone`	Yes	The attendee’s IANA timezone	Yes
`attendee_name`	Yes	Full name	Yes
`attendee_email`	Yes	Where the confirmation goes	Yes
`attendee_phone`	No	Phone number
`title`	No	Defaults to the event type’s name	Yes
`attendee_language`	No	Language code such as `en` or `es`. Defaults to English	Yes
`guests`	No	Comma-separated guest emails, up to 10	Yes
`booking_fields_responses`	No	Answers to the event type’s booking questions, as JSON, for example `{"notes":"Bring the contract"}`
`length_in_minutes`	No	Only for event types with Allow multiple durations turned on	Yes

Reschedule meeting · Cancel meeting

Field	Required	Description	Pinnable
`booking_uid`	Yes	The booking’s UID, from Find bookings by attendee
`start_time`	Reschedule only	The new start time
`timezone`	Reschedule only	IANA timezone of the new time
`reason`	No	Why it’s being moved or cancelled	Cancel only

Find bookings by attendee · Get booking

Field	Required	Description	Pinnable
`attendee_email` or `attendee_name`	One of them	Who to look up	Yes
`booking_uid`	Get booking only	The booking to read

Get all bookings

Every field is optional: attendee_email, attendee_name, status (upcoming, cancelled, past), event_type_id (defaults to the default event type), event_type_ids, after_start, before_end, sort_start, sort_end and take. You can pin event_type_id, the sort fields and take.

Pin the values that never change

Field	Typical pin	Why
`timezone`	`Europe/London`	Callers are offered times in your local zone. Pin it on Check availability and Book meeting; Reschedule meeting still asks for it
`attendee_language`	`en`	Confirmation emails go out in the right language
`reason` (cancel)	`Cancelled by caller over the phone`	Your team sees why a booking disappeared

How it works on a call

Offer real slots

The agent calls Check availability for the window the caller asks about and reads out two or three open times.

Book

Once the caller picks one and confirms their name and email, Book meeting creates the booking and Cal.com sends the confirmation.

Change plans

For “I need to move my appointment”, Find bookings by attendee finds the booking, then Reschedule meeting or Cancel meeting changes it.

Limits

The agent books only the default event type.
One Cal.com account per organization. To switch to a different one, click Disconnect, then Connect again.

Troubleshooting

'Invalid Cal.com API key' when connecting

Copy the key again from Settings → Developer → API keys, make sure nothing was cut off when pasting, and check it hasn’t expired.

'No event types found on this Cal.com account'

Create at least one event type at app.cal.com/event-types, then connect again.

Booking fails for a time the agent just offered

The slot may have been taken in the meantime. Tell the agent, in the Book meeting condition prompt, to check availability again and offer another time if booking fails.

Calls fail with 'Cal.com rejected the credential'

The key was deleted or has expired. Cal.com keys expire after 30 days unless Never expires was turned on. Create a new key, then on the Integrations page click Disconnect and Connect with it.

Integrations overview

Connecting, pinning fields and disconnecting

Calendly

The same flow for Calendly