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

# Calendly

> Sign in with Calendly and let an agent book, find and cancel appointments on its event types

Check availabilityBookFindRescheduleCancelList

Calendly is a scheduling system like Cal.com: the event type owns the duration, the buffers, the notice period and the holidays, and Calendly is the authority on whether a slot is free. Roark maps your agent's actions onto it.

The one difference that shapes an agent's design: **Calendly has no reschedule API**. The tool is therefore never created, and a caller who wants to move an appointment is handled by cancelling and booking again.

***

## What you need

| | |
| :- | :- |
| **Credential** | A Calendly sign-in. There is nothing to paste |
| **Scopes requested** | `users:read`, `event_types:read`, `scheduled_events:read`, `scheduled_events:write` |
| **How they are granted** | Calendly has **no per-scope checkbox**: the grant carries all four or you declined the whole thing |
| **Who should sign in** | The Calendly user that owns the event types the agent should book |

| Scope | Why it is needed |
| :- | :- |
| `users:read` | Identifies the connected user, which every other read is filtered by |
| `event_types:read` | Lists the event types an appointment type can point at, and reads their length |
| `scheduled_events:read` | Finds a caller's appointment and lists their upcoming ones |
| `scheduled_events:write` | Books and cancels |

***

## 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 Calendly**. Name the account, leave the time zone on *The account's own* to adopt Calendly's setting, then **Sign in with Calendly**.

![The Account step of the calendar setup dialog for Calendly, with a name, a time zone and the Sign in with Calendly button](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/connect-calendly.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=33bdb9e87e9630df1172e5e225ec362d)

**2. Consent**

Calendly opens its consent screen in a new window. Nothing is created until you accept: Roark exchanges the code, verifies the credential, 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. Pick the event types the agent may book**

Each appointment type points at one of the account's event types, with a line telling the agent when it fits. Event types are read live, so one added in Calendly since you connected is already in the list.

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

**4. Switch on the tools**

Five of the six actions are available. **Reschedule** is greyed out with *Calendly has no way to do this.* — give the agent cancel and book instead, and say so in its prompt so it does not promise a move it cannot make.

![The Tools step, with a switch for each calendar action 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"}}
roark connections calendar calendly-oauth start \
  --label "Sales calls" \
  --timezone America/New_York

roark connections calendar list --provider CALENDLY
```

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

***

## Calendly specifics

> [accordion] No reschedule, and what to do instead
>
> Calendly offers only a browser `reschedule_url` it emails the invitee — there is no API a tool could call. Roark never registers the tool, so the agent cannot reach for something that does not exist. Tell the agent in its prompt to cancel the existing appointment and book the new time, and it will read the new reference back.

> [accordion] Event types are named by URI
>
> Calendly names everything by absolute URL, so an appointment type points at an event type URI such as `https://api.calendly.com/event_types/AAAAAAAAAAAAAAAA`. In config, that is the `eventTypeUri` field. Only a Calendly host is accepted.

> [accordion] Availability is read 31 days at a time
>
> Calendly refuses an availability query wider than 31 days. A caller asking about a longer range is answered from several queries; you do not have to do anything.

> [accordion] The caller's email is required
>
> Calendly needs an invitee email to book, so the agent asks the caller for one and the setup dialog says so while you configure the appointment types.

> [accordion] Event types with several durations
>
> Calendly lets the invitee choose the length at the moment a slot is taken, and the slot `check_availability` offered has already settled it — so there is no duration to pin on the appointment type.

> [accordion] No slot holds
>
> Calendly cannot hold a time while the caller thinks about it. A slot that goes between being offered and being booked comes back as `SLOT_TAKEN`, with fresh times for the agent to offer.

> [accordion] Cancellation reason
>
> A caller who gives no reason is recorded as *Cancelled by the caller*, which is what shows in Calendly and in the cancellation email the invitee receives.

***

## Signing in again, and disconnecting

Calendly rotates its refresh token, and a grant can be revoked from the Calendly account. A connection that stops working 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"}}
roark connections calendar calendly-oauth start --calendar-connection-id <connection-id>
roark connections calendar check <connection-id>
```

Disconnecting in Roark destroys the stored credential and hands the grant back to Calendly, so the disconnect is visible in the customer's Calendly account. Appointments already recorded are kept.

***

## Troubleshooting

| What you see | What it means |
| :- | :- |
| The connection is refused after consent | The consent was declined, or the window was closed before Calendly redirected back. Try again |
| The reschedule switch is greyed out | Expected: Calendly has no reschedule API. Use cancel and book |
| A caller's appointment is not found by phone number | A phone number only finds appointments **this agent** made. A booking reference or the email the appointment was made with finds any of them |
| Status is `INVALID_CREDENTIALS` | The grant was revoked or the refresh token no longer works. Use **Sign in again** |
| Disconnect refused with a `409` | A calendar tool is still bound to the connection; the refusal names the tools |

***

## 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)
>
> Declare a Calendly tool in your config

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

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