> ## Documentation Index > Fetch the complete documentation index at: https://docs.haloagents.ai/llms.txt > Use this file to discover all available pages before exploring further. # Calendly > Let your sales and support agents book meetings from the chat, and land every booking on the contact, their conversation, your lead alerts and the AI. ## What Calendly adds to Halo | Mode | What it does | | - | - | | **Sales agent** | Pick any event type from your Calendly account as an embed on a [sales agent](https://docs.haloagents.ai/agents/sales-agent.md). The booking page renders inline in the chat with the visitor's name and email pre-filled. | | **Support agent** | Pick an event type as a meeting the support agent offers — in the chat when a customer asks to talk to someone, or right after an escalation — to the customers your [scheduling](https://docs.haloagents.ai/agents/scheduling.md) rules select (a plan, a segment). | | **Ingest** | Bookings become **lead** contacts (or update the visitor's existing contact), a meeting on the contact's timeline, a lead alert in Slack and email, and context the AI sees for the rest of the conversation. Cancellations update the meeting and fire their own trigger. | Connect at **Settings > Integrations > Calendly**. ## Setup ### Connecting Click **Connect with Calendly** and approve the OAuth consent screen. Halo connects as the Calendly user who approves it: their event types are what the sales agent can pick, and their bookings are what syncs. The consent screen asks for these Calendly scopes, and nothing else: | Scope | Used for | | - | - | | `users:read` | Identifying the connected user and organization | | `event_types:read` | Listing event types in the sales agent's picker | | `scheduled_events:read` | Reading bookings and invitees (sync and webhook payloads) | | `webhooks:read`, `webhooks:write` | Registering and removing the booking webhook | > [!NOTE] > > Self-hosting Halo? The OAuth app you create in Calendly's developer console (**My Apps**, Production environment, redirect URI `/api/integrations/calendly/callback`) must have exactly these five scopes ticked. Calendly refuses an authorization that requests a scope the app wasn't configured with, and Halo refuses a grant that is missing one. Set the app's client ID and secret as `CALENDLY_CLIENT_ID` and `CALENDLY_CLIENT_SECRET`, and the app's webhook signing key (shown on the app in the developer console) as `CALENDLY_WEBHOOK_SIGNING_KEY`: Calendly signs an OAuth app's webhook deliveries with that key. After approval, Halo registers a webhook subscription for `invitee.created` and `invitee.canceled` and runs an initial sync of the last 30 days of bookings. The initial sync imports quietly: contacts and meetings are created, but no lead alerts, series or workflows fire for old bookings. > [!NOTE] > > Calendly only allows webhook subscriptions on its paid plans. If registration is refused, the integration page says so and bookings are picked up by the hourly sync instead. They still reach contacts, alerts and the AI, just not instantly. Reconnect after upgrading to turn on real-time delivery. ### Using it in the sales agent 1. On the sales agent, under **Integration embeds**, click **Add integration** and pick **Calendly**. 2. Choose an event type from the list (or paste a scheduling link if you prefer). 3. Give it a label. The event type's name is used until you change it. The AI gets a tool to show the booking calendar when a visitor wants to book, and your agent [instructions](https://docs.haloagents.ai/agents/instructions.md) can steer when ("always offer to book a demo after qualifying a lead"). ## What happens on a booking * The invitee becomes a **lead** contact in [Contacts](https://docs.haloagents.ai/contacts/overview.md), or lands on their existing contact when the email is already known. Booking questions are stored as contact attributes. * A **meeting** is recorded with the event type, time, join link, and cancel/reschedule links, and shown on the contact's timeline. * Your [lead notifications](https://docs.haloagents.ai/agents/sales-agent.md#lead-notifications) fire for a fresh lead, naming the event type they booked. * A booking made **inside the chat** is attached to that conversation: the visitor's anonymous contact gets the booking, the transcript links to the contact, the alert goes through the sales agent that ran the chat, and the AI sees "Booked '30 min demo' for ... in this conversation" so it confirms instead of offering to book again. How the chat link works: the widget adds a conversation reference to the embed URL in Calendly's `salesforce_uuid` tracking slot (and in `utm_content` when the page has no UTM content of its own). Calendly echoes it back on the booking. If you also use Calendly's own Salesforce integration, bookings made inside the chat carry this reference instead of a Salesforce id. ## Series and workflow triggers Bookings are ready-made triggers once Calendly is connected. In a [series](https://docs.haloagents.ai/outreach/overview.md), set the entry trigger to **Triggers an event** and pick **Calendly · Meeting booked** or **Calendly · Meeting cancelled** from the list; the same two appear in a workflow's trigger menu. They fire for the booking contact. Rescheduling in Calendly arrives as a cancellation of the old booking and a new booking. The underlying event names, needed only when you create a series or workflow through the API: | Event name | Fires when | | - | - | | `calendly_meeting_scheduled` | An invitee books a meeting (once per booking) | | `calendly_meeting_cancelled` | A known booking is cancelled | ## Sync The hourly sync re-reads bookings whose start time is within the last 30 days or in the future, so cancellations of meetings booked earlier are never missed. **Sync Now** on the integration page runs it on demand. ## Disconnecting Disconnecting removes the webhook subscription from Calendly and stops the sync. Contacts and meetings already synced are kept. Calendly links on sales agents keep working as plain inline embeds, without the account picker or the conversation link. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.