> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect Cal.com, Google Calendar, Calendly or GoHighLevel and let an agent built on Roark check real availability and book, move and cancel real appointments

A calendar connection gives an [agent built on Roark](https://docs.roark.ai/documentation/config-as-code/agents.md#agents-built-on-roark) the ability to work a real diary: it offers times that are actually free, books the one the caller picks, finds an existing appointment, moves it, and cancels it.

Roark holds the credential and runs the tool itself. There is no endpoint to host, no webhook to receive, and no booking code to write — you connect an account once for the project, say what kinds of appointment it offers, and switch on the actions the agent is allowed to take.

![The Calendars card on an agent's Tools tab, showing a connected Cal.com account and a Google Calendar account with their appointment types and tools](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/calendars-card.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=2f25f24f4ea484ce35610fb3ae6bd2f6)

> [!NOTE]
>
> Calendar tools execute only for agents built on Roark. For an agent running on another platform (VAPI, Retell, your own stack), a tool definition is still useful — Roark [grades and mocks](https://docs.roark.ai/documentation/config-as-code/tools.md) the tool call in simulations — but Roark does not call your calendar on that agent's behalf.

***

## Supported calendars

> [card] [Cal.com](https://docs.roark.ai/documentation/integrations/calendars/cal-com.md)
>
> API key. Books an event type, which owns its own length, buffers and notice

> [card] [Google Calendar](https://docs.roark.ai/documentation/integrations/calendars/google-calendar.md)
>
> Sign-in. Books time on a calendar, with booking rules Roark holds for you

> [card] [Calendly](https://docs.roark.ai/documentation/integrations/calendars/calendly.md)
>
> Sign-in. Books an event type. No reschedule: Calendly has no API for it

> [card] [GoHighLevel](https://docs.roark.ai/documentation/integrations/calendars/gohighlevel.md)
>
> Private Integration Token plus a Location ID. Books into a sub-account calendar

### What each provider supports

| Provider | Connect with | The agent books | Actions |
| :- | :- | :- | :- |
| [**Cal.com**](https://docs.roark.ai/documentation/integrations/calendars/cal-com.md) | API key | An event type | All six |
| [**Google Calendar**](https://docs.roark.ai/documentation/integrations/calendars/google-calendar.md) | Sign in with Google | Time on a calendar | All six |
| [**Calendly**](https://docs.roark.ai/documentation/integrations/calendars/calendly.md) | Sign in with Calendly | An event type | No reschedule |
| [**GoHighLevel**](https://docs.roark.ai/documentation/integrations/calendars/gohighlevel.md) | Token + Location ID | A calendar | All six |

The six actions are check availability, book, find a booking, reschedule, cancel and list bookings.

| Provider | Booking rules live in | Caller's email | Availability window |
| :- | :- | :- | :- |
| **Cal.com** | Cal.com | Required to book | No cap |
| **Google Calendar** | Roark (you set them) | Optional | No cap |
| **Calendly** | Calendly | Required to book | 31 days per query |
| **GoHighLevel** | GoHighLevel | Optional | 31 days per query |

Where the caller's email is optional, the agent can still book without one: Google attendees are optional, and GoHighLevel matches its contact on a phone number alone.

An operation the provider cannot do is **never registered as a tool**, so the agent cannot promise it. Calendly has no reschedule endpoint, so a Calendly agent is given cancel and book instead, and the switch for it is greyed out in the setup dialog.

> [!NOTE]
>
> A window wider than a provider's cap is split into several queries automatically — the cap is a provider limit, not a limit on what a caller can ask about.

***

## Permissions each provider needs

What you grant when you connect, and nothing more. Full instructions are on each provider's page.

| Provider | Credential | Permissions / scopes |
| :- | :- | :- |
| **Cal.com** | API key from **Settings → Developer → API keys**, starting `cal_` | Cal.com keys are not scoped: the key carries the permissions of the account that created it, so create it on the account that owns the event types |
| **Google Calendar** | OAuth consent | `calendar.events` (read and write events) and `calendar.readonly` (list calendars, read free/busy). **Both checkboxes must be ticked** on the Google consent screen or the connection is refused. Roark never asks for the full `calendar` scope, which can delete whole calendars |
| **Calendly** | OAuth consent | `users:read`, `event_types:read`, `scheduled_events:read`, `scheduled_events:write`. Calendly has no per-scope checkbox: the grant carries all four or none |
| **GoHighLevel** | Sub-account Private Integration Token (`pit-…`) plus the Location ID it was minted in | `calendars.readonly`, `calendars/events.readonly`, `calendars/events.write`, `contacts.readonly`, `contacts.write`, `locations.readonly` |

> [!WARNING]
>
> Credentials are verified against the provider **before** anything is stored. A key the provider rejects is a `400` and no connection is created, because a connection that never worked would next be exercised by an inbound call at 2am with nobody there to fix it.

***

## Setting one up

Calendars live on the **Tools** tab of an agent built on Roark. Open the agent, scroll to **Calendars**, and pick your provider's chip.

**1. Connect the account**

Give the account a name you will recognise, choose the time zone the business keeps, and hand over the credential — an API key, or a sign-in for Google and Calendly.

An account is connected **once per project** and shared by every agent in it. Connecting again from another agent reuses the same account.

![The Account step of the calendar setup dialog, with a name, a time zone and a Cal.com API key](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/connect-cal-com.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=54057dd1425407cd71fd2b81277e2521)

> [!NOTE]
>
> The time zone is the **business's**, not the caller's. A clinic's 3pm is 3pm whoever dials it. Leave it on *The account's own* for a signed-in account to adopt the provider's setting. A fixed offset such as `-08:00` is rejected — it does not observe daylight saving.

**2. Describe the appointment types**

An appointment type is one kind of appointment the agent can book: a name the agent passes, a line saying when it fits, and the thing it books into.

![The Appointment types step, with two Cal.com event types named Checkup and New patient and a line describing when each one fits](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/appointment-types.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=87752cb767c8a7782c401472821784fd)

On Cal.com, Calendly and GoHighLevel, the type points at something that already exists on the account and the provider keeps the rules. On Google Calendar there is nothing to point at, so you set the length, buffer and open hours here and Roark holds them.

Appointment types also **scope** the tools: an agent can reach the types you listed and nothing else on the account.

**3. Switch on the tools**

One tool per action. The three that write — book, reschedule, cancel — are marked **Changes data**. Each tool's name and the line the agent reads can be edited.

![The Tools step, with a switch for each of the six calendar actions and a Test bookings switch](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/tools.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=0f1c4dfb00344f1147db614da2e84334)

Only switch on what the agent should be allowed to do. A front desk that books but never cancels is three tools, not six.

***

## What the agent actually gets

Each switched-on action becomes one tool with a fixed contract. You do not define its arguments; Roark does, and the rules below are enforced on Roark's side rather than in a prompt.

| Tool | The agent passes | It gets back |
| :- | :- | :- |
| `check_availability` | `from_date`, `to_date` (plain `YYYY-MM-DD` days), optional `part_of_day`, and `appointment_type` when the account offers more than one | A few slots, each an opaque `slot_id` and a `when` already worded for speech, plus a `say` line that is safe to read out |
| `book` | `slot_id`, `name`, and optionally `email`, `phone`, `notes` | `outcome` (`CONFIRMED`, `PENDING_CONFIRMATION`, `SLOT_TAKEN`, `ALREADY_BOOKED`, …), the `booking_ref`, the time, and alternative slots when the time has gone |
| `find_booking` | `booking_ref`, `email` or `phone` | The matching appointments, with whether each is confirmed |
| `reschedule` | `booking_ref` and a new `slot_id` | The new `booking_ref` and time, or alternatives |
| `cancel` | `booking_ref`, optional `reason` | `CANCELLED`, `NOT_FOUND` or `ALREADY_CANCELLED` |
| `list_bookings` | `email` or `phone` | The caller's upcoming appointments |

> [accordion] Why the agent is given dates, not datetimes
>
> A voice model composing an ISO datetime with an offset gets it wrong often enough to book the wrong hour. The tools take plain calendar days and the server expands them in the business's time zone. Roark appends the business's time zone and today's date to the agent's prompt, so "next Tuesday" is arithmetic the model can do.

> [accordion] Why book only accepts a slot\_id
>
> `check_availability` hands out opaque slot ids that are single-use and expire after 10 minutes. `book` takes one of those and nothing else, so the agent cannot book a time it mis-heard or invented. The slot id is also the idempotency key: a `book` that times out and is retried returns the first appointment rather than making a second one.

> [accordion] Why "confirmed" is never assumed
>
> An event type with a confirmation policy accepts a booking without confirming it. That comes back as `PENDING_CONFIRMATION`, and the sentence Roark hands the agent says the time is *requested*. The agent never composes the outcome itself.

> [accordion] Reading a booking reference back
>
> A booking reference **changes when an appointment is rescheduled**. The reschedule tool returns the new one and the agent reads it back to the caller.

> [accordion] Looking an appointment up by phone number
>
> A booking reference or an email address finds appointments made anywhere. A phone number only finds appointments **this agent** made — a caller who booked on your website and offers only a phone number is asked for their email or reference instead.

***

## Test bookings

A hosted agent under test is bound to your live calendar, so a hundred-call test run would otherwise be a hundred real appointments in a real diary.

* **Test bookings on** (the switch on the Tools step, `simulate` in config): every call on the tool books on a simulated calendar instead of yours. Use it while you are building.
* **During a Roark simulation**: a test call Roark can confirm is routed to the simulated calendar before your credential is touched at all, so a simulated call cannot reach your diary.

The simulated calendar offers weekday office hours against an empty diary, and applies a Google target's own hours, length and buffers where you have set them — so what you test is the behaviour you configured.

> [!NOTE]
>
> Slot ids are signed with the mode they were offered in. A slot offered on the test calendar cannot be booked on the real one, or the reverse.

***

## Limits

| | |
| :- | :- |
| Calendar call timeout | 8 seconds (a provider read is bounded at 3 seconds — a caller is on the line) |
| Calendar calls per conversation | 20 |
| Slot id lifetime | 10 minutes, single use |
| Appointment types per tool set | 1 to 24 |
| Availability window | Split to fit the provider's cap (31 days on Calendly and GoHighLevel) |

***

## Managing a connection

> [accordion] Connection status
>
> A connection is `ACTIVE`, `INVALID_CREDENTIALS` (the provider rejected the credential — it needs a new one), or `ERROR`. A provider outage never changes the status: being unable to reach a provider is not evidence that your credential is bad.
>
> Re-verify at any time with `POST /v1/connections/calendar/{connectionId}/check`, or `roark connections calendar check <connection-id>`.

> [accordion] Rotating a credential or signing in again
>
> For a key-based provider, paste the new key: it is verified first, and a verified key returns the connection to `ACTIVE`. For Google and Calendly, use **Sign in again** on the account row — the consent screen replaces the credential in place, so every tool bound to the connection keeps working.

> [accordion] Disconnecting
>
> Disconnecting destroys the stored credential; it is not an archive. Appointments already recorded against the connection are kept, so a booking stays explainable afterwards.
>
> A disconnect is refused with a `409` while a calendar tool is still bound to the connection, and the refusal names the tools. Point them at another calendar, or delete them, first.

***

## As code

A calendar tool is a [`kind: tool`](https://docs.roark.ai/documentation/config-as-code/tools#calendar-handler) resource with a `calendar` handler. Each action is its own tool, naming the same connection:

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# roark/tools/check-availability.yaml
kind: tool
name: check-availability
agent: frontdesk
description: Find open times for the appointment type the caller needs
handler:
  type: calendar
  calendarConnection: 3f2a9c1e-8b4d-4e6f-9a7b-1c2d3e4f5a6b
  operation: CHECK_AVAILABILITY
  appointmentTypes:
    - name: checkup
      whenToUse: A routine cleaning and exam, every six months
      eventTypeId: 123456
  simulate: false
```

The credential never goes in your config: connect the account in the app, through the [API](https://docs.roark.ai/api-reference/calendar-connection/connect-a-calendar-account.md), or with the CLI, then reference the connection by id.

```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# Connect, then list what the account can book
roark connections calendar create --provider CAL_COM --label "Front desk" --api-key cal_live_...
roark connections calendar list
roark connections calendar target list <connection-id>
```

***

## Security and data

* **Verified, then encrypted.** A credential is checked against the provider before it is stored, and stored encrypted. It is never returned by the API and never appears in a config file.
* **One account, many agents.** A connection belongs to the project. Every agent in the project can book on it; no agent can reach another project's calendar.
* **Scoped to what you listed.** A tool can only reach the appointment types configured on it, so a booking reference cannot be used to cancel an appointment on another event type.
* **Caller details are logged by key, not value.** Names, emails, phone numbers, notes and cancellation reasons passed to a calendar tool are never written to logs verbatim.
* **Sensitive data in transcripts** is handled by [PII redaction](https://docs.roark.ai/documentation/observability/pii-redaction.md) like any other call content.

***

## Next steps

> [card] [Cal.com](https://docs.roark.ai/documentation/integrations/calendars/cal-com.md)
>
> Connect with an API key and book event types

> [card] [Google Calendar](https://docs.roark.ai/documentation/integrations/calendars/google-calendar.md)
>
> Sign in and set the bookable hours yourself

> [card] [Calendly](https://docs.roark.ai/documentation/integrations/calendars/calendly.md)
>
> Sign in and book Calendly event types

> [card] [GoHighLevel](https://docs.roark.ai/documentation/integrations/calendars/gohighlevel.md)
>
> Connect a sub-account with a Private Integration Token

> [card] [Tools as code](https://docs.roark.ai/documentation/config-as-code/tools.md#calendar-handler)
>
> The `calendar` handler, field by field

> [card] [Test tool calls](https://docs.roark.ai/documentation/recipes/tool-call-testing.md)
>
> Exercise booking paths in simulations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.