> ## 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.

# Google Calendar

> Sign in with Google and let an agent book time on a calendar, with the booking rules held in Roark

Check availabilityBookFindRescheduleCancelList

Google Calendar is a raw calendar, not a scheduling system. It knows when you are busy; it has no notion of an appointment length, a buffer, a minimum notice or the hours you are open. So Roark holds those rules for you: you describe a **bookable target** — a calendar plus a booking policy — and Roark computes availability from your free/busy and that policy, and arbitrates conflicts itself.

That makes Google the one provider where you set the booking rules inside Roark.

***

## What you need

| | |
| :- | :- |
| **Credential** | A Google sign-in. There is nothing to paste |
| **Scopes requested** | `https://www.googleapis.com/auth/calendar.events` and `https://www.googleapis.com/auth/calendar.readonly` |
| **Both must be granted** | Google shows a **checkbox per permission**. If either is left unticked, the connection is refused and nothing is stored |
| **Who should sign in** | The Google account that owns, or has write access to, the calendar the agent books into |

### What each scope buys, and what Roark deliberately does not ask for

| Scope | Why it is needed |
| :- | :- |
| `calendar.events` | Create, move and cancel events on calendars the account can already reach — the booking itself |
| `calendar.readonly` | List the account's calendars and read free/busy, which is how availability is worked out |

> [!NOTE]
>
> Roark never asks for the full `https://www.googleapis.com/auth/calendar` scope. That is full control, including deleting whole calendars, and a tool that books appointments has no business being able to delete a diary.

> [!WARNING]
>
> Both scopes are classified "sensitive" by Google. On the consent screen, tick **See, edit, share, and permanently delete all the calendars you can access using Google Calendar** *and* **See and download any calendar you can access using your Google Calendar** — Roark verifies that both were granted and refuses the connection otherwise.

***

## Connect the account

**1. Start the sign-in**

Open your agent built on Roark, go to the **Tools** tab, and in the **Calendars** card choose **Add Google Calendar**. Name the account, leave the time zone on *The account's own* to adopt Google's setting, then **Sign in with Google**.

![The Account step of the calendar setup dialog for Google Calendar, with one account already connected and the sign-in button for another](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/connect-google.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=f61d4943bf14e0abfb190ab4df132f30)

**2. Grant both calendar permissions**

Google opens its consent screen in a new window. Tick both calendar permissions and continue.

Nothing is created until you consent: Roark exchanges the code, checks both permissions were granted, reads the account's own time zone when you did not set one, and stores the connection. A consent link that is not used expires.

**3. Describe what can be booked**

An appointment type on Google names the calendar to write to, how long an appointment runs, a buffer, and the days and hours it is offered in.

![The Appointment types step for Google Calendar: the calendar, the length, the buffer and the days and hours appointments are offered in](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/appointment-types-google.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=458e7758bb6f990fa4391d3cbe36dede)

Only calendars the account can **write to** are offered. A calendar you can only read would answer availability perfectly well and then fail the booking mid-call, so it is left out rather than listed and refused.

**4. Switch on the tools**

Google supports all six actions.

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

Through the API, connecting is two steps because there is no credential a request body can carry:

```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# Prints a URL to open in a browser; Roark finishes the rest server-side
roark connections calendar google-oauth start \
  --label "Dr. Lee's diary" \
  --timezone America/Los_Angeles

roark connections calendar list --provider GOOGLE
```

```bash cURL theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/connections/calendar/google/authorize-url \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Dr. Lee'\''s diary", "timezone": "America/Los_Angeles" }'
```

***

## The booking policy

Each bookable target carries the rules Google does not have. The app writes one for you when you save the setup; through the API you create it yourself.

| Field | Default | What it does |
| :- | :- | :- |
| `calendarId` | — | The calendar appointments are written to. `primary` is accepted and stored as the account's real id |
| `durationMinutes` | — | How long an appointment runs |
| `bufferBeforeMinutes` / `bufferAfterMinutes` | `0` | Dead time either side, counted as busy when a slot is offered |
| `minNoticeMinutes` | `120` | How soon from now an appointment may be made |
| `horizonDays` | `30` | How far ahead appointments may be made |
| `slotIntervalMinutes` | the duration | The grid slots are offered on, measured from each window's own start rather than from the hour |
| `allDayEventsBlock` | `true` | Whether an all-day event closes the day. On by default: Google marks all-day events free unless their creator says otherwise, so a public holiday entered as one would otherwise still be bookable |
| `hours` | Mon–Fri, 09:00–17:00 | The windows of the week appointments are offered in, in the connection's time zone |

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# A 20-minute consultation, Monday to Friday, 09:00–17:00
roark connections calendar target create <connection-id> \
  --name "Consultation" \
  --calendar-id primary \
  --duration-minutes 20 \
  --buffer-after-minutes 10 \
  --min-notice-minutes 120 \
  --horizon-days 30
```

Hours are ISO weekdays (Monday is `1`) and minutes from local midnight, so `{ "weekday": 1, "startMinute": 540, "endMinute": 1020 }` is Monday 09:00 to 17:00. A window that runs past midnight is two entries on two weekdays; a day the business is closed is simply absent.

> [!WARNING]
>
> A target with no windows offers nothing at all, which reads to a caller as a permanently full diary.

> [!NOTE]
>
> Editing a target changes what agents **already published** against it book, with no new agent version — the same as editing an event type on a scheduling system. `hours` replaces the whole week when you send it, because a rota is described as a week. The calendar itself cannot be changed: it is the target's identity for the booking ledger, so moving it would orphan every appointment already made on it.

***

## How availability and conflicts work

> [accordion] Availability is computed, not read
>
> Google's free/busy says when the calendar is busy; the target's policy says when the business is open and how long an appointment is. Roark turns the two into slots, applying buffers, minimum notice and the booking horizon.

> [accordion] Roark refuses double bookings, because Google will not
>
> Google will happily insert a second event on top of the first and say nothing. So every write re-checks the interval first — against both Roark's ledger and the live calendar — and refuses the booking itself, which the agent hears as "that time has gone" along with fresh times to offer.

> [accordion] A retried booking cannot become two appointments
>
> Roark generates the Google event id itself, so a retry of the same booking sends the same id and Google answers with a conflict instead of creating a second appointment.

> [accordion] What Roark writes on the event
>
> Bookings carry two private extended properties — the Roark booking id and the attendee's email — used to reconcile a write whose answer never came back. They are private to the organiser's copy, so attendees never see them.

> [accordion] The caller's email is optional
>
> Google attendees are optional, so an agent that cannot get an email spelled out over the phone can still book. Supply one and the attendee is added to the event as usual.

***

## Signing in again, and disconnecting

A Google refresh token can stop working — a password change, a revoked grant, or an account that no longer exists. The connection then reports `INVALID_CREDENTIALS` and the account row offers **Sign in again**, which replaces the credential **in place** so every tool bound to the connection keeps working.

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
# Reconnect an existing connection rather than creating another
roark connections calendar google-oauth start --calendar-connection-id <connection-id>
```

Disconnecting in Roark destroys the stored credential and hands the grant back to Google, so the disconnect is visible in the customer's Google account under **Third-party apps with account access**. Appointments already recorded are kept.

***

## Troubleshooting

| What you see | What it means |
| :- | :- |
| The connection is refused after consent | One of the two permissions was left unticked on the consent screen. Start again and grant both |
| A calendar is missing from the picker | The signed-in account has read-only access to it. Share it with write access, or sign in as an account that owns it |
| *Sign in to this account again to see and change this type's calendar, length and hours* | The credential is no longer valid, so the target's policy cannot be read. Use **Sign in again** |
| Slots are offered outside your opening hours | The target's `hours` are the source of truth, not the calendar's working hours. Edit the appointment type |
| A public holiday is still bookable | The holiday is an all-day event on a different calendar, or `allDayEventsBlock` is off for that target |

***

## Next steps

> [card] [Calendars overview](https://docs.roark.ai/documentation/integrations/calendars/overview.md)
>
> The six tools, slot ids, test bookings and limits

> [card] [Tools as code](https://docs.roark.ai/documentation/config-as-code/tools.md#calendar-handler)
>
> Point a tool at a bookable target in config

> [card] [Cal.com](https://docs.roark.ai/documentation/integrations/calendars/cal-com.md)
>
> A scheduling system that owns its own rules

> [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.