Cal.com

What your agents can doCopy Anchor Link

Helios agents use Cal.com API v2 to check availability and manage bookings. Access depends on your API key or OAuth scopes and the connected user's role. Helios attaches the credentials to requests and sets the cal-api-version header for endpoints that need it.

• Find open slots for an event type and book one for an attendee
• Reschedule or cancel bookings, and confirm or decline booking requests
• List upcoming and past bookings and read the attendees' answers
• Create and change event types, availability schedules, and out-of-office entries
• Manage teams, memberships, and routing forms, as a team or organization admin

The agent's API tool can only reach Cal.com's hosted API at api.cal.com.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Cal.com API KeyCopy Anchor Link

Any Cal.com user can create an API key, including on the free plan.

1. In Cal.com, open Settings → Developer → API keys and click Add.
2. In Name this key, enter a name such as Helios.
3. Under Expiration date, turn on Never expires, or pick 7 days, 30 days, 3 months, or 1 year. The default is 30 days.
4. Click Create, then Copy. Cal.com doesn't show the key again.
5. In Helios, choose Cal.com API Key and paste the key into Cal.com API Key.
6. Optional: if the key's user is an organization admin, turn on Admin access to also register an organization webhook. See Triggers.
7. Save.

Cal.com API keys have no scopes or permissions to pick. The key acts as the Cal.com user who created it and can call every endpoint that user can. Most team and organization endpoints also need the user to be a team admin or organization admin, so create the key as an admin for full access.

Cal.com doesn't let you change a key's expiry date later. If the key expires, create a new one, enter it through Manage, and save.

Your own Cal.com OAuth appCopy Anchor Link

1. In Cal.com, create an OAuth client under Settings → Developer → OAuth.

2. Add this redirect URI to the client:

   Copy Text

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

3. Select every scope in the user scopes table below. If you plan to turn on Admin access, also select every team and organization scope.

4. In Helios, choose Your own Cal.com OAuth app and enter the client's Client ID and Client Secret.

5. Optional: turn on Admin access to also ask for the team and organization scopes. For an organization admin, it also registers an organization webhook. See Triggers.

6. Save, then approve access in Cal.com.

Helios always asks for these user scopes:

Admin access adds these team scopes:

And these organization scopes:

Cal.com lets an OAuth token call only public endpoints, such as creating a booking or reading slots, and the endpoints whose reference page names a scope. Endpoints that name no scope, such as organization roles and delegation credentials, need an API key.

Cal.com reviews every new OAuth client. Until it approves yours, only the Cal.com account that registered the client can authorize it, so connect with that account. Changing the client's name, logo, website, or redirect URIs, or adding scopes, sends it back for review. Removing scopes doesn't.

Access tokens last 30 minutes, and Helios renews them with the refresh token Cal.com issues. If the connection's status shows Error, connect again. To change Admin access later, change it through Manage and save, then click Re-connect on the connection.

TriggersCopy Anchor Link

Cal.com can start a Workflow when something happens to your bookings, meetings, or routing forms. Helios registers a webhook on your Cal.com user when you save the connection and subscribes it to every Cal.com webhook trigger that a user webhook receives, so there is nothing to set up in Cal.com. Saving again updates the same webhook. Deleting the connection removes it.

The user webhook covers the connected user's own event types, including managed event types assigned to the user. Bookings of round-robin and collective team event types don't reach it.

When the connection has Admin access and the connected user is an admin of a Cal.com organization, Helios also registers an organization webhook with every Cal.com webhook trigger. It covers the team event types of every team in the organization, including round-robin and collective event types and instant meetings, and the organization's delegation credential events. Turning Admin access off on an API key connection removes the organization webhook when you save. An OAuth connection can't remove it without Admin access, and it keeps sending events. An organization admin can delete it in Cal.com under Settings → Developer → Webhooks. Cal.com's API has no webhook for a single team, so bookings of team event types in a team outside an organization don't start runs.

An event can reach both webhooks, such as an attendee declining a booking in their calendar. Helios starts one run for it.

Without an organization webhook, the trigger picker shows instant_meeting.created, instant_meeting.accepted, and the four delegation_credential events as unavailable. Cal.com offers instant meetings only on team event types in an organization, and sends the delegation credential events only to organization webhooks. The reason in the picker says what's missing: an organization, Admin access, or the organization admin role.

All filters are optional. Patterns use * as a wildcard, and case doesn't matter.

• Event type matches events of the event types you pick from the menu. With Admin access, the menu also lists the organization's team event types. Cal.com doesn't send the event type with a no-show change, so a booking.updated trigger with an event type filter skips no-show changes.
• Attendee email matches when an attendee's email matches the pattern, such as *@acme.com. For instant_meeting.created it matches the booker's email, for booking.wrong_assignment_reported the guest's email, and for calendar_entry.rejected the email of the attendee who declined.
• Change matches booking.updated events of the changes you pick: Location or No-show.
• Form name matches the routing form's name, such as Sales*.

For an event type that needs confirmation, Cal.com sends booking.requested when someone books, and booking.created once you confirm. On a seated event type that needs confirmation, the first confirmed seat sends booking.created. Each later seat sends booking.seat_accepted when a host confirms it, and booking.seat_rejected when a host declines it. Cal.com sends meeting.started and meeting.ended at the booking's scheduled start and end time, whether or not the meeting took place. It schedules them when the booking is made or confirmed, so they fire only for bookings made after you connected Cal.com. The no-show, recording, and transcript events need meetings held on Cal Video. Cal.com sends out_of_office.created for out-of-office entries added in the Cal.com app. Entries created through Cal.com's API don't send it.

Deliveries are verified with the HMAC-SHA256 X-Cal-Signature-256 header, and deliveries more than a day old are rejected. Cal.com sends no delivery ID, so Helios identifies repeat deliveries by their event type, content, and timestamp for one day.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Cal.com rejected the key or token. See Common errors.
• The webhook: in Cal.com, open Settings → Developer → Webhooks. A webhook whose URL contains /integrations/cal_com/webhooks/ should be listed.
• The organization webhook: with Admin access as an organization admin, the trigger picker in Helios shows no Cal.com events as unavailable.
• A trigger:
  1. Add booking.created to a workflow with no filters.
  2. Book one of your own event types from its public booking page.
  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

• Rate limits: Cal.com allows 120 API requests a minute by default. Cal.com support can raise it. See Cal.com's API introduction.
• Plans: the API key, the API, and webhooks work on Cal.com's free plan. Routing forms need Cal.com's Teams plan or an organization. Instant meetings and delegation credentials need a Cal.com organization.