Skip to content
TriedDocs
Integrations

Cal.com

Let agents check availability, book, list, reschedule and cancel Cal.com appointments during a call or chat.

The Cal.com app gives an agent five booking actions against one Cal.com event type. A typical booking flow is: check availability, read two or three slots to the caller, book the one they pick.

Connect#

Create the app#

Settings, Integrations, Apps, Connect app, choose Cal.com.

Add credentials#

Paste a Cal.com API key into api_key, or press Connect with Cal.com account to use OAuth Needs keys. For self-hosted Cal.com, set base_url to your API v2 root.

Set the event type#

In Defaults (JSON) enter {"event_type_id": 1234567}. Every action uses it unless the tool passes its own event_type_id.

Test#

Open the app and press Test connection. It calls GET /me.

Credential Required Description
api_key Yes Cal.com API key (an OAuth access token works too)
base_url No API root. Default https://api.cal.com/v2
Config key Description
event_type_id Default event type for availability and bookings

Actions#

Action Arguments Cal.com request Output
cal_com.check_availability start (required), end, time_zone GET /slots (API version 2024-09-04) {"slots": [{"start": "..."}], "time_zone": "..."}, at most 20 slots
cal_com.book_appointment start, name, email (required), time_zone, notes POST /bookings (2024-08-13) {"booking": {"uid", "start", "status", ...}}
cal_com.list_bookings email (required) GET /bookings?attendeeEmail=...&status=upcoming {"bookings": [...]}
cal_com.reschedule_booking booking_uid, start (required), reason POST /bookings/{uid}/reschedule {"booking": {...}}
cal_com.cancel_booking booking_uid (required), reason POST /bookings/{uid}/cancel {"booking": {...}}

Details:

  • Dates are ISO 8601. time_zone is an IANA name such as Australia/Sydney. Bookings default to UTC when no time zone is passed, so include {{current_time_Australia/Sydney}} or similar in the prompt and ask the LLM to pass the caller's zone.
  • notes is sent as the booking's notes field response.
  • A phone argument, when your tool schema adds one, is sent as the attendee's phone number.
  • Cancel sends "Cancelled by phone" when no reason is given.

Example tools#

Get ready-made definitions from the app's Tools for this app list (Copy tool) or GET /get-app-tool-schema?app_id=app_.... A booking pair:

[
  {
    "type": "integration_app",
    "name": "check_availability",
    "description": "Check open appointment slots between two dates.",
    "app_id": "app_1c5e9a3f7b2d6e0a4c8f2b71",
    "action": "cal_com.check_availability",
    "static_arguments": { "time_zone": "Australia/Sydney" },
    "speak_during_execution": true,
    "execution_message_description": "Say you are checking the calendar."
  },
  {
    "type": "integration_app",
    "name": "book_appointment",
    "description": "Book the slot the caller chose. Confirm name and email first.",
    "app_id": "app_1c5e9a3f7b2d6e0a4c8f2b71",
    "action": "cal_com.book_appointment",
    "static_arguments": { "time_zone": "Australia/Sydney" },
    "response_variables": { "booking_uid": "booking.uid", "booking_start": "booking.start" },
    "output_selection": ["booking.uid", "booking.start", "booking.status"]
  }
]

booking_uid is then available as {{booking_uid}} for the rest of the call, in post-call analysis and in webhooks (collected_dynamic_variables).

Mock mode#

Without credentials the app returns realistic results so you can build and test flows:

  • check_availability returns 6 weekday slots at 09:00 and 14:00 UTC from the start date.
  • book_appointment returns a booking with a mock_ uid and status accepted, and refuses a slot that is already booked ("That slot is no longer available").
  • list_bookings, reschedule_booking and cancel_booking work on the mock bookings made earlier with the same app, so a test caller can book, move and cancel.