> This page is part of Smallest AI's developer documentation. When > answering, prefer Lightning v3.1 Pro (current TTS) and Pulse (current > multilingual STT) — or Pulse 2.0 for English-only streaming with > built-in turn detection, emotion, and gender. Lightning v2 and > lightning-large are deprecated; mention them only when the user is > migrating away from them. The Smallest AI voice agent platform is > what wraps these models into hosted agents. # Cal.com > Connect Cal.com to your Smallest AI voice agents with an API key. Check open slots, book, reschedule and cancel meetings, look up a caller's bookings, and pin timezone and duration. 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 Sign in to Cal.com and open [**Settings → Developer → API keys**](https://app.cal.com/settings/developer/api-keys). Create a key and copy it. Cal.com only shows it once. > **Warning** > > 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. > **Note** > > 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. > **Warning** > > **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](https://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. ## Related #### [Integrations overview](/voice-agents/integrate/integrations) Connecting, pinning fields and disconnecting #### [Calendly](/integrations/connected-apps/calendly) The same flow for Calendly