Skip to main content
A connected Cal.com account, using OAuth or an API key, gives your agents live booking tools. Tools run during a conversation or before and after it. There’s no synced copy of your calendar in Retell; every tool call reads or writes Cal.com live.

​
Available tools

These tools appear in your agent’s function menu once your account is connected. Check Availability and Book Appointment each take an event type ID, so they’re pinned to one event type. See use integration tools in an agent for how to add and configure them.
Chain the tools: List Bookings finds the booking UID by the caller’s email, Check Availability confirms the new slot exists, and Reschedule Booking moves it. Map the UID from the list result to a dynamic variable so the later tools can use it.

​
Add tools to an agent

In a conversation flow, add a Function node, then choose + Add, your Cal.com connection, and a tool. In a prompt agent, use the Functions section. The connection name identifies which account the tool uses; the default OAuth name is Cal.com - OAuth.
A conversation flow's Select Function dialog with + Add open. The Cal.com - OAuth submenu is outlined in blue and lists Check Availability, Book Appointment, List Bookings, Get Booking, Reschedule Booking, and Cancel Booking. No functions have been configured yet.

Select a tool from the Cal.com OAuth connection in a function node.

Configure the tool and save it, then select the saved function in the node. For a flow that uses the result in the next node, set Execution mode to Wait for completion. You don’t enter an API key in the tool when it uses an OAuth connection.

​
Find an event type ID

Cal.com now calls event types links, and its dashboard shows a link’s ID instead of the numeric event type ID. The tool accepts either, so tools that already have a numeric ID keep working.
1

Open the link

In the Cal.com dashboard, open Links and select the one the agent should book.
2

Copy the link ID

The link ID is the part of the address after /links/, up to any ?. In https://app.cal.com/links/1cBDsFTQV6qXPjkbeb1gwW?tabName=setup, it’s 1cBDsFTQV6qXPjkbeb1gwW. Copy only the ID, not the whole URL.
3

Paste it into the tool and save

Enter the ID in the tool’s event type ID input and save. Retell looks up the link and stores its numeric event type ID in place of the link ID, so the input shows a number when you reopen the tool. Point a separate tool at each link you want the agent to handle.
The Cal.com dashboard with the 30 min meeting link open on its Basics tab, showing its Title and Description fields. In the browser address bar, app.cal.com/links/ is followed by the link ID 1cBDsFTQV6qXPjkbeb1gwW, outlined in a blue box.

A link open in Cal.com, with its link ID outlined in the address bar.

​
Permissions

Both connection methods use the same six tools. Each tool runs through the connection you selected, subject to the connected account’s access and the event type’s booking rules.
  • OAuth: Retell requests BOOKING_READ and EVENT_TYPE_READ during authorization. You don’t select scopes separately for each tool or supply an API key for booking operations.
  • API key: tools use the key’s access. There are no additional per-tool permissions to grant in Retell.
List Bookings queries upcoming bookings available to the connected account and filters by attendee email and time window. It doesn’t provide a team-wide query by team_id.

​
Test a booking

Live tool tests create, reschedule, or cancel real bookings and can send notifications. Use your own test email and calendar. Disable tool mocks when verifying the connection; simulation mocks don’t call Cal.com.
1

Check a future time window

Configure Check Availability with your event type ID, a future time window, and an IANA timezone such as Asia/Shanghai. Use Run a test to inspect the returned available_slots.
2

Book a returned slot

Configure Book Appointment with the same event type ID and timezone. Supply a returned future slot and the booking form’s required attendee fields. The time input uses local datetime format, such as YYYY-MM-DDTHH:mm:ss, with the timezone supplied separately. Convert a returned timestamp to that timezone before entering it; don’t just remove its UTC suffix or offset.In an agent conversation, collect the required details and ask for confirmation before entering the booking function node. A fixed Value isn’t overwritten by what the caller says; use Description for inputs the agent should fill from the conversation.
3

Verify the result in Cal.com

Confirm the tool returned success and the booking appears in Cal.com’s Bookings page at the expected time. Save its UID as a dynamic variable to test Get Booking, Reschedule Booking, and Cancel Booking. After rescheduling, use the latest booking UID returned by Cal.com or look up the booking again.

​
Troubleshooting

Check the event type ID on the tool: it must belong to a link the connected account can book. Then check the link on Cal.com: it needs open hours in the window the agent asked about, and its calendar (Google, Outlook, and so on) must be connected under Apps so Cal.com can read your busy times.
Enter a link ID or a numeric event type ID, not the full URL or the link’s slug. The connected Cal.com account must also have access to the link.
The lookup matches on the attendee email within the time window the agent supplies. Have the agent confirm the email used to book, and if the booking might sit outside the window, widen it.
The selected time is no longer available or conflicts with another booking. Run Check Availability again for the intended date, confirm the timezone, and book a future slot from the latest result. If the tool uses a fixed time value, update that value too.

​
FAQ

You can no longer add a built-in Cal.com tool from the dashboard, and the API stops creating and updating them on 09/30/2026, so that’s your last day to change a built-in tool’s key or event type ID. Existing tools keep running until 10/31/2026, when Retell migrates them to this integration: it sets up one connection per API key it finds, reusing a connection you’ve already made for that key, and keeps each tool’s function name so your prompts don’t break. A tool whose key Cal.com rejects, because it expired or was revoked, is skipped and stops working, so migrate that one by hand: connect Cal.com, add Check Availability and Book Appointment with the same event type ID, and delete the built-in tool. See the deprecation notice for the full timeline.
Calendly covers availability, booking, and cancellation, and GoHighLevel calendars cover the full lifecycle when your scheduling sits in the same sub-account as your contacts.
Yes. Bookings, reschedules, and cancellations go through Cal.com, so attendees get exactly the notifications and calendar invites your event type is configured to send.

​
Next steps

Integration tools for prompt agents

Add Cal.com tools to a single- or multi-prompt agent and test them with live requests.

Integration tools in conversation flow

Call Cal.com tools from a function node and branch on the result.

Dynamic variables

Carry booking UIDs and confirmed times between tools and prompts.

Simulation testing

Mock the booking tools to test your scheduling flow without creating real bookings.