Skip to main content
Check availability Book Find Reschedule Cancel List Cal.com is a scheduling system, so it already knows everything about how an appointment is made: the event type owns its length, its buffers, its minimum notice and the hours it is offered in, and Cal.com is the authority on whether a slot is free. Roark maps your agent’s six actions onto it and stays out of the way. Roark uses the Cal.com v2 API.

What you need

Cal.com lets you give a key an expiry date. A key that expires takes your agent’s booking with it, so either create it with no expiry or diary the rotation — and rotate it in Roark before it lapses.
Paste an API key, not an OAuth access token from a Cal.com platform app. A token verifies once and then expires mid-call, which is why Roark checks for the cal_ prefix and refuses anything else.

Connect the account

1

Create the API key in Cal.com

In Cal.com, open Settings → Developer → API keys, create a key, and copy it. It is shown once.
2

Add Cal.com to your agent

In Roark, open your agent built on Roark, go to the Tools tab, and in the Calendars card choose Add Cal.com.Give the account a name, pick the time zone the business keeps, and paste the key. Verify and connect checks it against Cal.com before anything is stored — an invalid key is refused on the spot and no connection is created.
The Account step of the calendar setup dialog for Cal.com, with a name, a time zone and the API key field
The account is connected once for the project. Every agent in the project can book on it.
3

Pick the event types the agent may book

Each appointment type points at one of the account’s event types and carries a line telling the agent when it fits. Roark reads your event types live, so one added in Cal.com since you connected is already in the list.
The Appointment types step for Cal.com, with the Checkup and New patient event types and a line describing when each fits
The agent can reach the types you list here and nothing else on the account.
4

Switch on the tools

Cal.com supports all six actions. Switch on the ones the agent should be allowed to take — the three that write are marked Changes data.
The Tools step with the six Cal.com actions and the Test bookings switch
Prefer the API or the CLI?

What Cal.com decides, and what Roark does

Event type details worth knowing

An event type with a confirmation policy accepts the booking but does not confirm it. Roark returns PENDING_CONFIRMATION, and the sentence the agent reads says the time is requested. The setup dialog flags these event types while you configure them.
An event type hidden on your Cal.com booking page is still bookable through the API, which suits an overflow or after-hours slot the agent can offer but the public page does not.
Where an event type offers a choice of lengths, pin one on the appointment type (durationMinutes). Leave it off and Cal.com uses the event type’s own length.
Cal.com needs an attendee email to book, so the agent asks the caller for one. An individual event type can declare further required booking fields of its own — Roark reads those when you configure the appointment type, so you find out at setup rather than mid-call.
Anything the caller asks to pass on is stored on the booking’s metadata (roarkNotes), which is always present and reaches the booking’s webhook and API — rather than a custom booking field whose slug differs per event type.
Cal.com issues a new reference when an appointment is moved. The reschedule tool returns the new one and the agent reads it back.
A caller who gives no reason is recorded as Cancelled by the caller, which is what shows in Cal.com and in the cancellation email the attendee receives.

Rotating the key

Paste a new key on the connection. It is verified before it is stored, and a verified key returns a connection in INVALID_CREDENTIALS to ACTIVE.

Troubleshooting


Next steps

Calendars overview

The six tools, slot ids, test bookings and limits

Tools as code

Declare the same setup in your config

Build an agent

The agent that will do the booking

Test tool calls

Exercise booking paths in simulations