Retell Cal.com Tools Deprecated: Migrate Before Oct 31

Retell is retiring its built-in Cal.com booking tools. On 30 September 2026 the Retell API stops accepting the check_availability_cal and book_appointment_cal tool types, and on 31 October 2026 Retell migrates existing tools to its new Cal.com integration. Any tool whose Cal.com API key has expired or been revoked by then is skipped and fails mid-call. If your voice agents book appointments through Cal.com, you have two days left to edit the old tools and about a month before the switch. Most agents will migrate cleanly. The ones that won't are the ones nobody's looking at.

What exactly is Retell changing?

Retell's deprecation notice lays out three dates:

• 23 August 2026: the dashboard stopped offering Check Calendar Availability and Book Appointment as built-in functions. You can't add them to a new agent from the UI.
• 30 September 2026: the API stops creating or updating the two old tool types. Existing tools keep running, but nothing can edit them anymore, because the dashboard writes through the same endpoints. This is the last day to change a built-in tool's API key, event type ID or timezone.
• 31 October 2026: Retell migrates the remaining tools to the Cal.com integration. It creates one connection per distinct API key, keeps each tool's function name, and carries over the event type ID and timezone.

The reason is sensible. Each built-in tool carried its own cal_api_key, so a workspace with ten booking agents held ten copies of the same key. Rotating it meant editing ten tools, and in practice nobody did. The integration holds one key per workspace connection and adds List Bookings, Get Booking, Reschedule Booking and Cancel Booking, which the old tools never had. For most setups this is an upgrade, not a loss.

Which agents will break on October 31?

The automatic migration has one hard dependency: Cal.com has to accept the key on migration day. Retell says a tool is skipped when Cal.com rejects its key because it expired or was revoked, and a skipped tool fails the first time the agent tries to check availability or book.

That failure mode is nasty for a phone agent. There's no error page. The caller asks for Tuesday at 2, the tool call fails, and depending on your prompt the agent either apologises vaguely, invents an answer, or offers to "have someone call you back" that nobody ever routes. You find out when the client asks why bookings dropped to zero.

Three situations put an agent at risk:

• Keys created with an expiry date. Cal.com lets you set one when you create the key. A lot of agencies did, because it felt like good hygiene.
• Keys created by someone who left. If a former contractor or employee made the key on their own Cal.com user and that account got cleaned up, the key is dead or about to be.
• Client-owned Cal.com accounts. When the key belongs to the client's account, the client can revoke it without knowing a phone agent depends on it.

The fix before 30 September is simple: replace any expiring key on the built-in tool now, while edits still work. After that date the only path is migrating that agent to the integration by hand.

How do you migrate Retell agents to the Cal.com integration by hand?

We'd migrate by hand anyway rather than wait for 31 October. You get to test on your own schedule instead of discovering problems on a Saturday. It's about 15 minutes per agent once you've done one.

1. Inventory. List every agent using the old tools. In the dashboard, look in each agent's Functions section. Through the API, call Get Retell LLM or Get Conversation Flow and filter for type equal to check_availability_cal or book_appointment_cal. Record the event type ID and timezone for each.
2. Create one never-expiring key. In Cal.com, go to Settings, Developer, API keys, and create a new key with Never expires switched on. Retell's own Cal.com connection guide is blunt about why: an expiring key silently kills the connection on its expiry date.
3. Connect once. On Retell's Integrations page, connect Cal.com with that key and the Cal.com domain. Every agent in the workspace can use this one connection.
4. Swap the tools. On each agent, add the integration's Check Availability and Book Appointment tools with the same event type ID, then delete the built-in tool. The new tools default to check_calcom_availability and book_calcom_appointment, so update any prompt text that names the old function.
5. Test. Retell's simulation testing can mock the booking tools so you don't fill a real calendar. Then make a handful of live calls against a test event type.

Two gotchas we'd flag for agencies. First, adding integration tools to an agent is dashboard-only as of August 2026, so if you provision client agents from templates through the API, each one still needs a manual pass. Second, after migration the API stops returning the old tool types, so any internal script that reads agents back and keys off check_availability_cal will quietly stop matching. Grep your provisioning code for those strings.

If you're still deciding whether Retell is the right platform for this kind of work, our Vapi vs Retell comparison covers the trade-offs, and our broader guide to Retell AI voice agents for agencies covers how we structure the builds.

What if you run self-hosted Cal.com or cal.eu?

Two groups need more than a tool swap.

Self-hosted Cal.com isn't supported by the integration (as of August 2026). It only talks to Cal.com's hosted API. If your booking calendar runs on your own server, and plenty of agencies self-host Cal.com to avoid per-seat pricing, point a Retell custom function at a webhook you control. We use an n8n workflow that receives the function call, hits the self-hosted Cal.com API, and returns a short, speakable result. You own the logic, which turns out to matter for the double-booking problem below. It also means you own the monitoring, so wire the workflow into your usual n8n error handling and alerting.

EU-hosted accounts have their own clock. The integration supports cal.eu, which the old tools never did. But Retell's docs also note that Cal.com has announced cal.eu shuts down on 1 November 2026 for non-enterprise customers, one day after the migration. If you move a cal.eu account to cal.com, reconnect with a cal.com key and the Cal.com domain, or the agent will break a second time.

Does the migration fix double bookings?

No, and this is the part worth your time while you're in there anyway. Swapping the tool changes where the key lives. It doesn't change how the agent behaves between "that time's open" and "you're booked".

Here's the race. The agent checks availability and reads out three slots. The caller thinks about it, checks with their spouse, asks whether parking is free. Forty seconds pass. In that window, someone books the 2 pm slot through the website. The caller says "2 pm works" and the agent calls Book Appointment on a slot that no longer exists.

Cal.com rejects the booking, so the calendar itself stays clean. The double booking happens in the conversation, not the database. If the prompt doesn't handle a failed booking, many agents still say "Great, you're all set for 2 pm", because the model predicted the happy path before the tool returned. The caller shows up to an appointment that doesn't exist. We covered how much a single no-show costs a service business in our post on voice agents that reduce no-shows.

Rules we put in every booking prompt:

• Never confirm without a booking ID. The agent may not say "you're booked" until Book Appointment returns a booking UID. Tell it so in plain words.
• Handle the failure path out loud. If booking fails, the agent says the slot was just taken, calls Check Availability again, and offers the next two times. Two options close faster than five.
• Re-check if the caller stalls. If more than a minute passes between reading slots and the caller choosing, check again before booking.
• Say the timezone back. The migrated tools keep their configured timezone, but the caller doesn't know what it is. Read the confirmation as "Tuesday at 2 pm Central". That matters in Texas more than people expect, since El Paso runs on Mountain time.
• Confirm the email before booking. Reschedule and cancel look bookings up by attendee email. A misheard email today means the agent can't find the booking next week.

On a custom stack you can go further and hold the slot while the caller decides. Cal.com has a reserve-a-slot endpoint that makes a slot unavailable to others for five minutes by default, configurable with an authenticated request. Our n8n booking workflows reserve the slot the caller leans toward, then book it on confirmation. The native integration tools don't expose that, which is one more reason some builds belong on custom functions rather than the built-ins.

Should you use the native integration or custom functions?

Our rule of thumb:

• Use the native integration when the client runs hosted Cal.com, has one or two event types, and just needs book, reschedule and cancel. It's less to maintain, and the new lifecycle tools cover what used to take custom work.
• Use custom functions through n8n when the calendar is self-hosted, when booking has to also create a CRM record or trigger a text, when you want slot reservation, or when you run many clients and want one place to log every booking attempt and failure.

Whichever you pick, test the failure paths, not just the happy path. A booking agent that works when the calendar is empty tells you almost nothing. Our checklist for testing AI agents before production applies directly: take the slot mid-call, feed it a caller in another timezone, and make it reschedule a booking it has to look up first.

Get a Free Automation Audit

If your Retell agents book through Cal.com and you're not sure which keys expire, which agents are still on the old tools, or what the agent says when a booking fails, we'll check for you. We'll inventory the agents, flag anything that will break on 31 October, and test the booking paths end to end. Get a Free Automation Audit, or see how we build booking agents on our voice AI agents service page.