Skip to main content

​
The Cal.com integration replaces the built-in Cal.com tools

The built-in Cal.com tool types check_availability_cal and book_appointment_cal are deprecated in favor of the Cal.com integration. This lands in three stages: the dashboard no longer offers these tools, the API stops accepting them on 09/30/2026, and on 10/31/2026 Retell migrates the tools you already have to the integration. Each built-in tool carries its own cal_api_key, so a workspace with ten booking agents holds ten copies of the same key, and rotating that key means editing all ten tools. The integration holds one key per workspace connection, adds booking lookup, reschedule, and cancel on top of availability and booking, and works with EU-hosted cal.eu accounts, which the built-in tools never supported. Affected APIs: Deprecated tool types:
  • check_availability_cal — fields cal_api_key, event_type_id, timezone
  • book_appointment_cal — fields cal_api_key, event_type_id, timezone
Use instead: connect Cal.com once for the workspace, then add its agent functions to each agent. What changed on 08/23/2026:
  1. The dashboard’s function menu no longer offers Check Calendar Availability or Book Appointment, so you can’t add one to an agent from the dashboard.
  2. The API still creates and updates built-in Cal.com tools until 09/30/2026.
What’s changing on 09/30/2026:
  1. The API stops accepting check_availability_cal and book_appointment_cal on both create and update. Requests that add one of these tools, or change one you already have, fail.
  2. Existing tools keep running unchanged until the migration, but no surface can edit them any more, since the dashboard writes through those same endpoints. 09/30/2026 is your last day to change a built-in tool’s API key, event type ID, or timezone.
What’s changing on 10/31/2026:
  1. Retell migrates existing built-in Cal.com tools to the integration. One connection covers each distinct API key: tools that share a key all point at the same connection, and a key you’ve already connected reuses that connection instead of getting a duplicate. Any connection the migration creates shows up on the Connected tab of the dashboard’s Integrations page.
  2. Migrated tools keep their current function name, so prompt text that calls the function by name (for example, “call the check_calendar_availability function”) keeps working. The event type ID and timezone carry over.
  3. Tools that can’t be migrated are skipped and stop working. A tool is skipped when Cal.com rejects its key at migration time, because the key expired or was revoked. A skipped tool fails mid-call, the first time the agent tries to check availability or book.
  4. API responses stop returning check_availability_cal and book_appointment_cal. Read a migrated agent back and you’ll get the integration’s tools instead, so client code that keys off the old tool types needs updating.
If your Cal.com key expires before 10/31/2026, replace it on the built-in tool before 09/30/2026, the last day an edit is accepted. After that the only fix is migrating the agent to the integration by hand.
Migration:
  1. Find the agents still on the built-in tools. On the dashboard, check each agent’s Functions section for Check Calendar Availability or Book Appointment. Through the API, call Get Retell LLM or Get Conversation Flow and look for tools with type set to check_availability_cal or book_appointment_cal.
  2. Connect Cal.com on the dashboard’s Integrations page. Create the API key with Never expires turned on, and set Domain to Cal.com, the instance the built-in tools used. Pick Cal.eu only if your account has since moved to Cal.com’s EU instance.
  3. On each agent, add the integration’s Check Availability and Book Appointment tools and give them the same event type ID the built-in tool used.
  4. Delete the built-in tool. If your prompt names the old function, update it to the new tool’s name.
  5. Test the agent before you ship it. Simulation testing can mock the booking tools so you don’t create real bookings.
You can create the connection through the API: Create App takes the Cal.com API key in auth_config and the instance in tenant_url (cal.com or cal.eu). Adding the resulting tools to an agent is dashboard-only (as of August 2026), so an agent built entirely through the API still needs one dashboard pass.
Effective dates: The dashboard stopped offering the built-in Cal.com tools on 08/23/2026. The API stops creating and updating them on 09/30/2026, after which existing tools keep running but can no longer be edited. On 10/31/2026 Retell migrates them to the Cal.com integration.