Calendly

What your agents can doCopy Anchor Link

Helios agents use Calendly API v2 to read and update scheduling data. Access depends on the connected user's permissions, token scopes, and Calendly plan.

• Find open times for an event type, and book a meeting at one through Calendly's Scheduling API
• Share an event type's booking link, or create a single-use link
• List upcoming meetings with their invitees and answers, cancel a meeting with a reason, and mark no-shows
• Create and update event types and their availability
• Look up and update contacts, and read meeting recaps and transcripts from Calendly Notetaker
• Look up routing form submissions and the meetings they led to

Calendly's API can't reschedule a meeting. An agent can share the invitee's reschedule link instead. The agent's API tool can only reach api.calendly.com.

Booking meetingsCopy Anchor Link

The agent books through Calendly's Scheduling API, POST /invitees. Calendly then sends the same emails and calendar invites as a booking made on the booking page.

• Plan: the Scheduling API needs a paid Calendly plan, Standard or higher.
• Booking limits: a trial account can book 5 meetings a day per user. Paid plans below Enterprise allow 10 bookings a minute, 50 an hour, and 100 a day per user. Enterprise allows 500 a minute.
• Booking questions: the agent must answer every required question on the event type, with the question text exactly as written. An event type with a location also needs the location in the request.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

ScopesCopy Anchor Link

Give both methods every scope, so agents can reach the whole API and triggers can receive every event.

These admin scopes reach features that only organization owners and admins can use:

A :write scope includes the matching :read scope.

Calendly Personal Access TokenCopy Anchor Link

Any Calendly user can create a personal access token. For triggers that cover every member's meetings, and for routing form triggers, use a token from an organization owner or admin.

1. In Calendly, open the Integrations page and select the API & Webhooks tile.
2. Select Get a token now under Personal Access Tokens. If you already have a token, select Generate new token under Your personal access tokens.
3. Name the token and check all six scope groups: Scheduling, User management, Contacts, Notetaker, Security & Compliance and Webhooks. That selects every scope in both tables above.
4. Select Create Token. Calendly emails a verification code to the account's address. Enter it to finish.
5. Select Copy token. Calendly doesn't show it again.
6. In Helios, choose Calendly Personal Access Token and paste the token into Personal Access Token.
7. Save.

Calendly revokes the token if the user's login email, password, or login method changes. Create a new token, enter it through Manage, and save.

Your own Calendly OAuth appCopy Anchor Link

The developer account is separate from your Calendly user account.

1. Go to developer.calendly.com, click Sign Up in the top right, and sign up with GitHub or Google.

2. Create a new OAuth application. Choose web as the kind of application and Production as the environment.

3. Set the redirect URI to:

   Copy Text

   https://api.heliosapp.com/integrations/calendly/oauth_callback

4. On the app's Scopes tab, check all six scope groups: Scheduling, User management, Contacts, Notetaker, Security & Compliance and Webhooks. To change the scopes later, open the app from My Apps and use the same tab.

5. On the next step, copy the Client ID, Client Secret, and Webhook signing key. Calendly shows the secret and the signing key only once.

6. In Helios, choose Your own Calendly OAuth app and enter the three values in Client ID, Client Secret, and Webhook Signing Key.

7. Check Admin access if an organization owner or admin will approve the app and agents need the admin scopes.

8. Save, then approve access in Calendly. Approve as an organization owner or admin for triggers that cover the whole organization.

Calendly signs every webhook of an OAuth app with the app's signing key, which is why Helios needs it. If you lose the signing key, ask Calendly at [email protected]. If you lose the client secret, Calendly can't show it again, so create a new app and enter its values through Manage.

Access tokens last two hours, and Helios renews them with the refresh token. Calendly issues a new refresh token on every renewal, and Helios stores it. Calendly revokes the tokens if the approving user's login email, password, or login method changes. Connect again if that happens, or after you change the app's scopes or Admin access.

TriggersCopy Anchor Link

Calendly can start a Workflow when something happens in your account. Helios registers webhook subscriptions in Calendly when you save the connection, so there is nothing to set up in Calendly. They need the webhooks:write scope, and each event needs the read scope listed in Scopes.

When you delete the connection, Helios attempts to remove its webhooks. If cleanup fails, for example because the token was revoked or Calendly is unavailable, the connection is still deleted. Remove any remaining webhook subscriptions in Calendly.

What the webhooks cover depends on who connects:

• An organization owner or admin: one webhook covers the whole organization. A second webhook covers the owner's or admin's own meeting recaps, because Calendly sends meeting recap events only to webhooks for one user.
• Any other member: one webhook covers only that member's meetings, event types, contacts, and recaps. Routing form submissions aren't available, because Calendly sends them only to organization webhooks.

If the token lacks the read scope of some events, Helios registers the webhook for the other events. The trigger picker shows the events a connection can't receive as unavailable, with the reason. They stay unavailable until the connection changes. After you enter a token with the missing scopes, or after the user becomes an owner or admin, save the connection again.

All filters are optional, and you pick their values from a menu.

• Event type matches meetings and no-shows of the event types you pick. On event_type.updated and event_type.deleted, it matches the event type that changed.
• Part of a reschedule separates reschedules from new bookings and real cancellations. A reschedule sends invitee.canceled for the old time and invitee.created for the new one. Set it to No to skip both, or Yes to match only reschedules.
• Routing form matches submissions of the forms you pick. The menu needs a connection from an organization owner or admin.

Deliveries are verified with the HMAC-SHA256 Calendly-Webhook-Signature header. Helios rejects deliveries signed more than three minutes ago.

Calendly's delivery rules: when deliveries fail, Calendly retries for up to 24 hours. If no delivery succeeds in that time, it disables the webhook. Save the connection again to create a new one.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Calendly rejected the token. See Common errors.
• A trigger:
  1. Add invitee.created to a workflow with no filters.
  2. Book a test meeting on one of your booking pages.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

• Plans: the API works on every plan, including Free. Webhooks and the Scheduling API need Standard or higher. The activity log, data deletion, and outgoing communications need Enterprise.
• Rate limits: Calendly allows 500 requests a minute per user on paid plans, and 50 on the Free plan. Bookings have their own limits, listed under Booking meetings. See Calendly's rate limits.