> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Calendly
> Connect Calendly to Retell AI with a personal access token so agents can check availability, book appointments, and cancel scheduled events.
Connect Calendly with a personal access token that has the [required scopes](#required-token-scopes). One connection gives you [agent functions](/integrations/calendly-functions): your agents check real availability, book appointments, and look up or cancel scheduled events.
## When to use it
Connect Calendly when your scheduling already runs on it and you want callers booked without a human in the loop. It's the right choice when you want to:
* **Read live openings to the caller.** The agent checks the event type's availability and offers actual slots.
* **Book while the caller is on the line.** After the caller confirms a time and gives their name and email, the agent books it; the invitee gets Calendly's usual confirmation.
* **Handle cancellations on the same call.** The agent finds the caller's upcoming events by email and cancels the one they name.
For example, a solar installer's inbound agent qualifies the caller, checks the sales team's consultation event type for this week, books Thursday 2pm with the caller's email, and the rep's calendar fills itself.
## Prerequisites
* A Calendly account that owns the event types you want to book. The token identifies one Calendly user, and Retell books and reads **that user's** event types and scheduled events.
* A **paid Calendly subscription** for booking. Availability checks, lookups, and cancellations work on any plan, but creating bookings uses Calendly's Scheduling API, which Calendly restricts to paid subscriptions (as of August 2026).
## Step 1: Create a personal access token
In Calendly, go to **Integrations & apps** and open the **API & webhooks** tile. On **Your personal access tokens**, click **Create a token** and name it something descriptive, for example `Retell AI`.
### Required token scopes
Before creating the token, select the scopes for your tools (as of September 2026):
| Scope | Used for |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `users:read` | Validate every connection by fetching the token's Calendly user. |
| `event_types:read` | Resolve the scheduling link for **Check Availability** and **Book Appointment**. |
| `availability:read` | Read available times for **Check Availability**. |
| `scheduled_events:read` | Read scheduled events and invitees for **List Bookings** and **Get Booking**. |
| `scheduled_events:write` | Create bookings with **Book Appointment** and cancel them with **Cancel Booking**. |
To use all five tools, grant all the permissions above. Calendly's [`:write` scopes include the matching `:read` permission](https://developer.calendly.com/docs/authentication/scopes), so `scheduled_events:read` doesn't need to be selected separately if you grant `scheduled_events:write`. For read-only tools, omit `scheduled_events:write`.
Create the token and copy it right away; Calendly shows it only once. For the scopes needed by each tool, see [Calendly agent function permissions](/integrations/calendly-functions#permissions).
The token's access also depends on the Calendly user's role. An **admin** token can access data across the organization within its granted scopes. To limit the data it can reach, create it from a dedicated non-admin account.
## Step 2: Connect Calendly in Retell
In the Retell Dashboard, open **Integrations**, select the **Available** tab, find **Calendly**, and click **Connect** (**Add Account** if a connection already exists).
Fill in the fields:
| Field | Value |
| ------------------- | --------------------------------------------------------------- |
| **Connection name** | Alias for this connection; prefilled with `Calendly - API key`. |
| **API Key** | The personal access token from Step 1. |
Click **Connect** (**Add Account** if a connection already exists). Retell tests the token by [fetching the Calendly user it belongs to](https://developer.calendly.com/api-docs/calendly-api/users/get-current-user), which requires `users:read`. This check doesn't validate the other tool scopes.
On success the connection appears on the **Connected** tab. From here, add tools to an agent: see [Calendly agent functions](/integrations/calendly-functions) for what each tool does and how it's configured.
## Troubleshooting
Confirm you pasted a **personal access token**, not an OAuth client secret or a webhook signing key, and that it hasn't been revoked in Calendly.
A valid token can still fail with **Could not connect. Check your credentials and try again.** if it lacks `users:read`. Create a new token with `users:read` and the [scopes for your tools](#required-token-scopes), paste it into **API Key**, and try connecting again. For an existing connection, replace the token in its settings and click **Reconnect**.
Retell flags a connection as errored when Calendly rejects the token, usually because it was revoked, or because Calendly invalidates tokens when the account's password or email changes. If you replaced the token, check that the new one has the [required scopes](#required-token-scopes). Open the connection's settings, paste a current token, and click **Reconnect**.
## FAQ
Event types owned by the Calendly user whose token you connected. To book for several team members, connect a token per user (multiple connections are fine) or use a shared account that owns the event types.
## Next steps
Check availability, book appointments, and look up or cancel events mid-conversation.
See every provider Retell connects to and how integration tools work.
The other calendar option, with rescheduling support.
