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

# Connecting Calendly

> Create a Calendly Personal Access Token and connect it to Voxworks so your voice agents can book appointments into your Calendly event types.

## Overview

Calendly is a calendar integration. Connecting it links your Calendly account to your Voxworks team so the [Book Calendar Appointment | Pro](/tools/calendar/calendly) tool can check availability and create bookings against your Calendly event types during a call.

The connection uses an **API key** — in Calendly's terms, a **Personal Access Token**. You generate the token in Calendly, paste it into Voxworks once, and Voxworks encrypts and stores it. There is no OAuth redirect. Your team holds one Calendly connection at a time, and every script on the team books through it.

Until Calendly (or another calendar provider) is connected, the calendar booking tool does not appear in the script editor's tool picker at all — connecting is the prerequisite step before any Calendly booking can be configured.

<Note>
  Integrations are typically built out for specific clients, so the full functionality of Calendly's interface might not be available. If your team needs additional features from this integration, contact the Voxworks team directly to discuss what can be added.
</Note>

***

## Creating your Personal Access Token

You create the token inside Calendly, not in Voxworks:

1. Sign in to Calendly **as the user whose scheduling link the assistant will book** (see the constraint below — this matters).
2. Open **Integrations & apps**, then find **API & webhooks**.
3. Under **Personal access tokens**, generate a new token, give it a name (for example "Voxworks"), and copy it. Calendly only shows the full token when it is created, so copy it before leaving the page.

<Warning>
  **The token must belong to the same Calendly profile as the event link.** A Personal Access Token identifies one Calendly user, and Voxworks can only see and book the event types owned by that user's profile. If the scheduling link you want the assistant to book (for example `https://calendly.com/username/30min`) belongs to a different member of your Calendly organisation than the person who generated the token, the connection will not work correctly — the availability check and the booking against that event type fail. Always generate the token while signed in as the owner of the event link.
</Warning>

One more thing to note while you are in Calendly:

* **Event type** — the current booking tool has no Calendly event URL field in the app; the event link is configured on the connection itself, and without one the availability check and booking cannot run. To set or change the event type your connection books, speak to the Voxworks team for further custom configuration.

***

## Connecting Calendly to Voxworks

1. In the sidebar under **Admin**, open **Integrations**.
2. In the **Available Integrations** section, find the **Calendly** card. It carries a **Calendar** badge and the description "Integrate with Calendly for automated scheduling".
3. Click **Connect**. The **Connect Calendly** dialog opens: "Enter your Calendly API key to establish the connection."
4. Paste your Personal Access Token into the **API Key** field and click **Connect**.

| Field   | Required | Description                                                                                                                                                                           |
| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key | Yes      | Your Calendly Personal Access Token. The field is masked as you type, and the token is encrypted before it is stored. The **Connect** button stays disabled until a value is entered. |

On success you'll see an "Integration connected successfully" message, and the Calendly card moves to the **Connected Integrations** section with a green **Connected** badge. The card's footer shows how many tools the connection makes available.

<Note>
  Voxworks stores the token immediately and does not test it against Calendly at connect time. A mistyped or revoked token — or one generated under the wrong profile — only surfaces later, as availability or booking failures on calls. Double-check the token you paste, and run a test call after setup.
</Note>

***

## What connecting unlocks

Once Calendly shows as **Connected**:

* **Book Calendar Appointment | Pro** appears in the tool picker when you edit a script step. The picker hides integration-bound tools until their provider is connected.
* With Calendly as the provider, the tool shows **no Calendly-specific fields** — only the settings shared by every calendar provider (availability window, SMS confirmation, timezone check). The event type comes from the connection itself, as described above.
* If your team has more than one calendar provider connected, a provider select appears in the tool's configuration panel so you can choose Calendly explicitly.

Successful bookings are written to `{{calendar.*}}` variables your flow can speak or send — for example `{{calendar.booking_time_spoken}}` (string, e.g. `10:30 AM on Tuesday the 22nd of July`) and `{{calendar.booking_link}}` (string — a link to the created booking, e.g. `https://cal.example.com/b/58d21aa7`). The full field-by-field and variable reference lives on the [Calendly booking tool page](/tools/calendar/calendly), and the settings shared by every calendar provider are on the [calendar tools overview](/tools/calendar/overview).

***

## Managing or removing the connection

Click the gear icon on the connected Calendly card to open **Integration Settings**:

* **Status** — a **Connected** badge plus an **API Key** badge showing the authentication type. If the connection has failed, an **Error** badge appears here and on the card, with the error message.
* **Connection Details** — when the connection was made and a masked view of the stored token. The token is never displayed again after connecting.
* **Available Tools** — how many tools this connection enables.

To replace the token (for example after revoking it in Calendly), disconnect and reconnect with the new token. If the card shows an **Error** badge, it offers a **Reconnect** button that reopens the connect dialog directly.

To remove the connection, click **Disconnect** in Integration Settings. The **Disconnect Calendly?** dialog warns that disconnecting will stop active workflows using the integration, remove access to Calendly features from your AI agents, and delete the stored authentication tokens. Any script step still configured with the Calendly booking tool will fail to book until you reconnect. You can reconnect at any time by entering a token again.

***

## Next Steps

* [Calendly Booking](/tools/calendar/calendly) — the booking tool's behaviour with Calendly and the variables it writes.
* [Calendar tools overview](/tools/calendar/overview) — settings shared by every calendar provider, from availability windows to SMS confirmations.
* [Integrations overview](/integrations/overview) — how integration connections work across your team.